Reuse, link, and recommend articles

You can use a single article in multiple categories and across knowledge bases. 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. These are called shared content articles.

Updating the content of any of the articles updates the content of all of them.

To share an existing article in another category or knowledge base:

1. On the Articles page, navigate to the location where you wish to add the article.
2. Select + Add Article.
3. Select Share content from an existing article.
   
4. Additional options appear below. If you have multiple knowledge bases, the knowledge base you're currently in is selected, but you can select a different knowledge base's articles to search.
5. Next, in the Search for existing article field, start typing part of the article's name. This is an exact match search, and the dropdown will offer you articles that match your search.
   
6. Once the article you wish to share content with appears, select it.
7. This will copy the Article Title field at the top, based on the shared content article's title. You can change this if you wish.
8. Once you're done selecting the article and editing the title (if needed), click the Add and Edit button in the lower right to complete the content sharing.
   
9. This will open the new, shared content article. It will have all the content of the article you selected when you created it. It will open in Draft mode and will have a banner reminding you that this content is linked to an article in another location. Use the links in this banner to quickly navigate to the synced content article or the knowledge base where this is located.
   Sample warning message for a child shared content article
10. You are now free to make any other changes as necessary to the article. Remember that any changes to the article body will be updated in all shared content articles.

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. This will embed the body of the topic 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.

There are a few tricks to using topic articles:

• When a topic article is embedded within another article and a reader searches for text within the topic article, search results will only list the topic article, not the article(s) it's embedded in.
• Automatic highlighting of glossary terms won't work in embedded topic articles; use manually inserted glossary definitions instead
• 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, you could consider using a snippet in place of one of these topic articles.
• Also of note: if you use versions in your topic article, you cannot mark these as ready for review and see them within the article where the topic article has been embedded--you can only review them within the topic article itself.
• If you are using reader group restrictions on your topic articles: in your live knowledge base, the topic article will only be visible to readers who belong to the reader group(s).
• Topic articles + 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.

Create a topic article

You can make any article into a topic article by checking the Reuse Flags box for Topic Article in the article editor. Be sure to click Save 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, you can insert them in other articles.

1. In the article you want to display the topic article in, click the Insert Topic Article icon in the editor: 
2. This will open a pop-up where you can search for articles that have been flagged as topic articles.
3. Type in the name of the topic article you want to insert. The search will autosuggest as you type. Once you find the topic article you want to insert, click on it and click the Insert Topic Article button. 
   Sample gif showing a topic article insertion. Hover to play.
4. You'll see a [[kb-topic:xxxxx]] inserted.
5. Click Save to save your changes.

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

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.
3. Type the 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.
   
   Sample gif showing the above steps. Hover to play.
5. Be sure to Save the article.

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. You can provide a list of relevant articles based on the page the person opened the widget from, which may eliminate the need for them to search the knowledge base or contact you.

You can relate individual articles to pages in your knowledge base, website, or application so that they are suggested when the widget loads on the page, or you use the API to return articles for a particular page in your site. For example, if you associate articles with the "/pricing" page on your website, these articles appear when the contextual help widget is opened on that page. Alternatively, if you associate articles with the "/account" page in your application and use the API to pull articles for that page, these articles will be returned for your "/account" page.

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

Widget 2.0, Recommended tab

In order 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 Settings > Widget, check your widget's Admin Settings and 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.
The Suggested Content options in the Admin Settings section

Formatting your page paths

Always use relative URLs. If we are configuring articles for https://www.knowledgeowl.com, take the portion of the URL that comes after that URL. For example, https://www.knowledgeowl.com/pricing becomes "/pricing". Specifically, the pathname of the URL is sent. The fragment and query string are not sent (unless you've selected the option to use query strings! Then you'd want to use query strings here.)

If your website or application includes URLs that have a variable ID field in them, you can 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 are using a single page application or the URLs in your website/app don't fit well within this framework, you can call a function to send a path of your choice to the widget. See 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:

Recommending Articles

To set up an article as being recommended:

1. Open the article for editing.
2. Find the Recommend on Pages section in the righthand column.
3. Select Add page to begin adding a new page.
   
   Click the Add page button to begin adding a new page path to recommend this article on
4. This will open an "Adding new page" section. 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, click the Save button directly under it.
   
   Add your page path into the text box and click the Save button directly under it
6. The interface will update 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 article path

To update an existing Recommend On Pages path:

1. Open the article for editing.
2. In the Recommend On Pages section, click on 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
3. Once you click on the path, the interface adjusts to say "Edit page". You can now edit the path in the text box.
   
   The Edit page interface
4. Once you've finished making your edits, click the Save button 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 article path

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

1. Open the article for editing.
2. In the Recommend On Pages section, click the trashcan icon to the right of the page path you want to remove:
   
   Click the trashcan icon next to the page path to begin deletion
3. In the confirmation message that appears, confirm that the page path is the one you meant to delete.
4. If it's the correct page path, click OK to complete the deletion.
   
   Confirm the path is the one you wish to delete, then select OK
5. The interface updates to remove the path.
6. Once you're done making changes, be sure to Save your article!

Recommending Categories

To set up a category as being recommended:

1. Open the category for editing.
2. Find the Recommend on Pages section in the righthand column.
3. Add the relative URL to the Recommend On Pages section, then select Save.
   
   Add one path per line
4. If you want this article to be recommended on multiple pages in your application or website, add each relative URL on a separate line:
   
   Add each new page path on a new line
5. Be sure to Save the article. The next time someone opens the widget from one of those pages in your site or application, it will suggest this category.

Update an existing recommended category path

To update an existing Recommend On Pages path in a category:

1. Open the category for editing.
2. Find the Recommend on Pages section in the righthand column.
3. Click in the text box there and edit the page path you want to adjust.
4. Be sure to keep each page path on its own line in the box.
5. Once you're done making edits, be sure to Save the article.

Delete an existing recommended category path

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

1. Open the category for editing.
2. Find the Recommend on Pages section in the righthand column.
3. Click in the text box there and delete the page path you want to adjust.
4. Be sure the remaining page paths are all on their own lines in the box.
5. Once you're done making edits, be sure to Save the category.

Ordering 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 in by editing the article weights for that page in Widget > Reporting. See Recommended Article Weights for more information.

The link to article or category feature is helpful when referencing 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.

Modern Editor

Legacy Editor

To create a link to another article:

1. Select Insert Link to Article or Category (or Link to Article or Category in the Legacy editor).
2. This will open the Add Link to Article or Category pop-up. 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. Click on the article you'd like to link to.
   
   Sample gif showing the above steps. Hover to play.
3. Type in the Link Text you'd like to use. This is the text that KnowledgeOwl displays on the page for the link.
4. The Link Text, Link Name, and Link Title will automatically be set to the article or category's title. You can overwrite these if you want:
   • 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, or 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 now 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. You can set them to open in a new tab by checking the box next to Open in new browser tab.
6. Once you've finished editing the link, select Add Link to insert the link into your article.
   
   Click the Add Article Link button to insert your link

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

Here's a sample for a link to an article we have called "How do bulk edits/deletes work?" This inserts a link that looks like this: how bulk edits work.
Sample Add Link to Article configuration

How can I tell if a link to an article or category was created using Link to Article or Category?

Hyperlinks inserted this way don't use the normal article URL as the URL for 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. Click on the hyperlink.
2. Click the Edit Link icon.
   
   Click the Edit Link option for the hyperlink
3. This will open a pop-up with the link details. 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