Reuse, link, and recommend articles

Learn how to link between articles, share a whole article's content, and set up related articles and page recommendations.

Share articles between categories and knowledge bases

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.

Reuse an article within another article

You can set an internal 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.

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.

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.

If you're looking for a solution that's not searchable on its own, but still has this reusable element, consider using snippets instead!

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.

Create a topic article

You can make any article into a topic article by checking the Internal Flag box for Topic - Embed this content within other articles in the article editor. Be sure to click Save to save your changes.

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. 
    Inserting a topic article
  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.

Related articles section

You can specify which articles or categories KnowledgeOwl displays as related articles within an article:

  1. Open the article or category in edit mode.
  2. Select Add Related Article:
    Add Related Article button
  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.
    Example of adding a Related Article
  5. Save the article.

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

Pages to recommend on (Contextual Help)

Pages to Recommend On allows you to provide contextual help to your readers through the embeddable contact form widget 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 embeddable contact form loads on this 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.

The exact display is different depending on which widget type you've selected.

If you're using the Modern widget, this impacts the Suggested Articles header section (note: in Settings > Widget, you can designate a different name for this section, so it may be called something else):

Screenshot showing the Modern Widget, with callout to the Suggested For You sectionSample Modern widget, Suggested For You section

If you're using Widget 2.0, this will update the Recommended tab list:

Screenshot showing Widget 2.0 opened to the Recommended tabWidget 2.0, Recommended tab

Setting up pages to recommend on

You need to know the relative URL of the pages in the application or website that you are calling the widget or API from. If we are configuring articles for, we will only take the portion of the URL that comes after that URL. For example, becomes "/pricing". Specifically, the pathname of the URL is sent. The fragment and query string are not sent. 

Once you have the relative URL for pages you want to specify recommended articles for, open one of those articles in the article editor in KnowledgeOwl.

Add the relative URL to the Recommend On Pages section, then select Save.

If you want this article to be recommended on multiple pages in your application or website, add each relative URL on a separate line:

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:

Note: {id} only works with numeric and hexadecimal IDs. For IDs that don't match either of those patterns, you would need to use the {custom} option via regex.

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 article.

The default behavior to send the URL of the page for recommendations can be overridden. This is important in cases where the page doesn't change like in a single page application or if the URLs themselves do not fit well within this framework. We have a guide for implementing this in single page applications. 

Link to article

The link to article 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 Link to Article in the Legacy editor).
  2. This will open the Add Link to Article pop-up. Start typing in the article 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.
  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 Article 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 was created using Link to Article?

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:
    Note the hg-id: in the URL; this URL uses the Link to Article