Reuse, link, and recommend articles

Have an article that might fit in two different categories? Instead of creating those two articles independently, create a Shared content article. The content (body) of the article as well as all versions stay in sync across all shared articles. Each article can have its own title, restrictions, and callouts. Edits to any one of the synced articles will update all the others. This is a great way to have the same content appear in multiple categories or even in multiple knowledge bases.

To create a new article synced to an existing article:

1. On the Articles page, navigate to the location where you wish to add the article.
2. Select + Add Article.
3. Select Sync with an existing article. Two additional fields appear.
4. Use the dropdown to select the knowledge base where the article you want to sync from is located. If you only have one knowledge base, ignore this dropdown.
5. Next, in the Search for an article by its title field, start typing part of the article's name. This is an autosuggest search. As you type, a list of articles matching your type appear.
6. Once the article you wish to sync content with appears, select it.
7. This will copy the article Title field at the top, based on the synced article's title. You can change this if you wish.
8. Once you're done selecting the article and editing the title (if needed), select Create to create the synced article. Your new synced article opens in the article editor in Draft status so you can make any other adjustments. Remember that any changes to the article body will be updated in all shared content articles.

You can always tell if an article is synced to another article by checking for banners in the article editor. Use the links in the banner to quickly navigate to the synced article or knowledge base where it's located.

Sample parent shared content article message:

This is a parent shared content article. Updating it will update these child shared content articles:

Sample child shared content article message:

This is a child shared content article. Updating it will update its parent shared content article. Stop sharing this content

For information on what gets shared and how, see Shared content articles.

You can set an internal reuse flag to mark any article in your knowledge base as a Topic Article.

Topic articles appear in search and the table of contents like any other article. But they can also be embedded within other articles. When they're embedded, topic articles display the body of their article without the title. This is great for content that needs to be displayed as a set of preliminary or introductory steps, hidden from certain groups, and so on.

Create a topic article

Turn any article into a topic article by checking the Reuse Flags box for Topic Article in the article editor. Be sure to Save your changes.

The Topic Article checkbox is in the Reuse Flags section of the righthand column

Insert a topic article into another article

Once you have one or more topic articles created, insert them in other articles.

1. In the article you want to display the topic article in, select Insert Topic Article (the document icon) in the editor controls: 
   Select Insert Topic Article
   
   The Insert Topic Article Body modal opens.
2. Start typing the name of the topic article you want to insert.
3. As you type, the modal suggests existing topic articles. Once you find the topic article you want to insert, select it from the list.
4. Then select Insert Topic Article:
5. The editor inserts something like this: [[kb-topic:xxxxx]]. This is your topic article.
6. Be sure to Save your changes.

The body of your topic article will now display within the main article.

Tips and tricks for using topic articles

There are a few tricks to using topic articles:

• Search indexing: When a topic article is embedded within another article and a reader searches for text within the topic article, search results only list the topic article, not the article(s) it's embedded in.
• Glossary term highlighting: Automatic highlighting of glossary terms won't work in embedded topic articles; use manually inserted glossary definitions instead.
• Topic article daisy chains: Topic articles embedded within other topic articles will not display wherever that additional topic article is embedded. So, for example:
  • Topic Article A contains information on your pricing structure.
  • Topic Article B contains information on your subscription plans and discounts. Topic Article A is embedded in Topic Article B. Content should load properly.
  • Topic Article B is then embedded in Topic Article C. Topic Article B's own content will load properly, but the content of Topic Article A won't show here.
  • If you need to do something like this, consider using a snippet in place of one of these topic articles.
• Version review: If you use versions in your topic article, you cannot mark these as ready for review and view them within the article where the topic article has been embedded--you can only review them within the topic article itself.
• Reader groups: If you restrict your topic articles to reader groups: in your live knowledge base, the topic article will only be visible to readers who belong to the reader group(s).
• Topic articles and pdfs: Topic articles get a somewhat special treatment when they are embedded in other articles and that other content is downloaded to PDF. Since the PDF generator is reader-agnostic, we use this logic:
  • If the topic article has no reader group restrictions, it will be included in all PDF downloads.
  • If the topic article has reader group restrictions, it will only be included in a PDF download if that content has a matching reader group that is assigned in the Restrict to Groups or Add More Restrictions section. (It cannot depend only on an Inherited Restriction.)
    • In all cases, for reader groups to work properly, the topic article must have the reader groups added using the Restrict to Groups checkboxes (if it has no inherited restrictions) OR if it has inherited restrictions, the group is also checked in the Add More Restrictions section.
    • If the article where it's embedded has no inherited reader group restrictions, but has Restrict to Groups boxes checked, those checkboxes must match what's used in the topic article.
    • If the article where it's embedded has inherited reader group restrictions only, the topic article won't be displayed unless you explicitly add the reader group in the Add More Restrictions section of the article.
    • For PDFs where the topic article is not displayed, the text of the topic article will be completely omitted, as when you view the article in the live knowledge base without belonging to the appropriate reader group.
  • For example: let's say I have a topic article that is restricted to my Support reader group, and I have embedded it in several articles. Here's what I can expect in the PDF download of those articles:

As you can see from this information: if the article that you're embedding your topic article within only has inherited reader group restrictions, you have to also explicitly assign those same reader groups to the article in order for the topic article to show up in the article PDF.

Use cases

There are three main use cases for topic articles.

Reused text

As Linus works on his documentation, he has an article that details a series of steps all of his support agents have to go through every time they access customer information. This set of steps appears at the start of roughly half of his documentation. Rather than copy and paste these steps into every other document or link out to those steps, he can set the login steps article as a Topic article. Then he can insert this topic article into each of the documents where those are preliminary steps.

There are two advantages to this: it saves him time (inserting a topic article takes only a couple seconds) and it keeps the steps more consistent. If the steps change, he only needs to edit the topic article and all the related articles will display those new, updated steps.

Customer-facing documentation with internal-only text

One of the knowledge bases Linus works on is a customer-facing product support knowledge base. But Linus also has a team of customer support agents who reference these documents. He wants to be able to include support-specific steps in those customer-facing documents, without having to create copies or a separate knowledge base.

Topic articles, like all articles, can be shown or hidden based on the Restrict to Groups settings. Linus can create the support-specific steps as a topic article. When he inserts that topic article into his customer-facing documentation, he can put it in the section of the customer documentation it's most relevant for. Customers won't be able to see it, but his support agents will be able to see it.

Video or file libraries

Linus has a knowledge base where each video is its own article, in different categories. But he wants to be able to display a collection of his videos in one place, as a kind of video library. He can set each video article to be a topic article, and then he can create a single longer article and insert each of his video library topic articles into it.

This allows each of his videos to be searchable and navigable independently, but also makes it easy for him to have a consolidated library of all of his resources.

While you can use automatic suggestions for your related articles, for the best control, you'll want to manually suggest them.

To add a Related Article:

1. Open the article or category for editing.
2. In the Related Articles section, select Add article. The Add Related Article modal opens.
3. Enterthe article or category title you want to add as a related article. The dropdown autosuggests articles or categories based on what you've typed.
4. Select the article or category, then select Add Related Article:
5. Be sure to Save the article.

To reorder or remove related articles, follow the instructions in Reorder or remove Related Articles.

See the Related Articles guide for more information on this feature.

Recommend On Pages allows you to provide contextual help to your readers through the embeddable Contextual Help Widget (2.0) or the API. For articles or categories in your knowledge base, you enter the Recommend On Pages relative URLs where the content should be recommended. When a reader opens your widget from the site where you have it embedded, the widget grabs the relative URL and displays the list of relevant content in the Recommended tab.

For example, if you associate articles with the "/pricing" page on your website, these articles appear when the contextual help widget is opened on your pricing page. When a reader opens a different page, different resources are recommended.

In Widget 2.0, the Recommend on Pages will update the Recommended tab list:

Widget 2.0, Recommended tab

To start using this feature, you'll need to:

• Set the Widget Settings to use the appropriate Suggested Content setting
• Add URLs from your main application or website to the articles or categories you'd like to recommend in the widget or API

Configuration - Widget settings

First, in KB settings > Widget, check your widget's Admin Settings. Be sure that the Suggested Content option best matches how your website or application is set up. This is usually a one-time set-up.

Choose from:

• Suggest content based off of the page path
• Use the page query strings to suggest content
• Disable automatic page suggestions
• And choose whether to Exclude articles that have a zero starting weight

Refer to Widget Admin Settings for more details on what each option controls.

Add your recommended pages

Enter relative page paths or query strings (depending on whether you've chosen to suggest content based on page path or query string!).

For example, let's say we set our widget up to suggest content based off of the page path and we embedded it on https://www.knowledgeowl.com.

If we want to recommend an article on the pricing page (https://www.knowledgeowl.com/pricing), we'd enter /pricing as our Recommend on Pages page.

If your website or application includes URLs that have a variable ID field in them, replace that ID with {id} in your URL.

Once you have the relative URL for pages you want to specify recommended articles or categories for, you can get started.

If you're using a single page application or the URLs in your website/app don't fit well within this framework, your developers can set up the widget to call a function to send a path of your choice to the widget. Refer to Using Widget 2.0 on Single Page Applications for more information.

The interface is a little different depending on whether you're adding articles or categories, so let's look at each in turn:

Add a new recommended page

To set up an article or category as being recommended:

1. Open the content for editing.
2. Find the Recommend on Pages section in the righthand column.
3. Select Add page to begin adding a new page.
   
   Select Add page to begin adding a new page path to recommend this content on
   
   The Adding new page section displays.
4. Add your page path into the text field with the /app/documentation placeholder:
   
   The Adding new page field will appear
5. Once you've finished adding your page path, select Save directly under it.
   
   Add your page path into the text box and click the Save button directly under it
6. The editor updates to show the page path you added:
   
   The page path now appears in the section with a trashcan icon to the right
7. Repeat this process for any other pages you want to recommend this article on.
8. Be sure to Save your article once you're done adding paths.

Update an existing recommended page

To update an existing Recommend On Pages path:

1. Open the article or category for editing.
2. In the Recommend On Pages section, select the text of the path you want to edit. Here, we'll edit our /pricing page path:
   
   Click the path text to open edit mode
   
   The Edit page section displays.
3. Edit the path in the text box.
   
   The Edit page interface
4. Once you've finished making your edits, select Save directly under the page path:
   
   Edit the page path and then click Save
5. Be sure to Save your article once you're done making your edits!

Delete an existing recommended page

To remove a page path you no longer want to recommend this content on:

1. Open the article or category for editing.
2. In the Recommend On Pages section, select the trashcan icon to the right of the page path you want to remove:
   
   Select the trashcan icon next to the page path to begin deletion
   
   The Article will no longer be recommended on confirmation modal opens.
3. If the displayed page path is the one you want to delete, select OK to complete the deletion.
4. The editor updates to remove the path.
5. Once you're done making changes, be sure to Save your article!

Order recommended articles

If you've added several recommended articles and you'd like to set the order they display in, you can change the order by editing the article weights for that page in Reporting > Widget. Refer to Recommended Article Weights for more information.

When people first start using KnowledgeOwl, to create a link to another article or category, their instinct is to use the Insert Link option and to paste in the full URL of the article or category.

Don't do this! We have a specially built tool to insert links to another article or category within KnowledgeOwl. It dynamically creates the links based on the unique ID of the articles, so you never have to worry about changed permalinks breaking links in your knowledge base. This is the Insert Link to Article or Category option in the editor (square box icon with an arrow pointing diagonally up and to the right):

Modern Editor

To create a link to another article:

1. Open the article for editing.
2. Select the Insert Link to Article or Category control (a square icon with an arrow pointing diagonally up and to the right). The Add Link to Article or Category modal opens.
3. Start typing in the article or category title you'd like to link to in the Title of Article or Category field. Articles and categories matching what you've typed in will appear below. Select the article you'd like to link to:
4. The Link Text, Link Name, and Link Title are automatically set to the article or category's title. Overwrite these if you wisht:
   • Link Text is the text that appears in your article. We recommend adjusting this if the article title doesn't make sense in the context of the article, to change capitalization, and so on.
     
   • Link Title is text that displays when someone hovers over the link.
     
   • Link Name is a largely unused link field in modern web design, but may still be used by some accessibility tools. We recommend using identical text for the Link Title and the Link Name.
5. By default, links open in the same tab. Set them to open in a new tab by checking the box to Open in new browser tab.
6. Once you've finished editing the link, select Add Link to insert the link into your article.

Once inserted, you can edit the hyperlink in the future as you would any other hyperlink.

Identify hyperlinks created using Link to Article or Category

Hyperlinks inserted from Insert Link to Article or Category don't use the normal article URL in the hyperlink. Instead, they use a specially-structured code that references the article ID that begins with hg-id.

If you'd like to check if a hyperlink was created using this method:

1. Select the hyperlink to open the hyperlink contextual menu.
2. Select Edit Link (the box containing a pencil icon).
   
   Select Edit Link for the hyperlink
   
   A small modal opens to display the hyperlink's details.
3. If the hyperlink URL includes [[hg-id: followed by a long string of letters and numbers, it was created using Link to Article or Category:
   
   Note the hg-id: in the URL; this URL uses the Link to Article or Category