Tags

A tag is a word or short phrase that "describes" the article. An article may have as many tags as you like. They can be a great way to add organization and navigation to your knowledge base.

The easiest way to think about tags is to consider them like filters for your content. These filters can be used:

• By your readers using a tag search (which begins with ":" followed by the tag name)
• As custom filters in Knowledge Base > Manage: if you're using tags for these kinds of internal filters only, you can mark tags as "hidden" so they won't show up to readers

For readers, tags will display:

• In search results, in a Tags section between the Last Updated and the article blurb
  
• In the search autocomplete after they've begun a search phrase with a colon (":")
  
• If you've added the article-tags template to Settings > Style, Custom HTML > Article, tags will display in the article wherever you've added that template. (These are not included by default in the article layout, though.)

You can create tags in three ways:

• In Library > Tags using the Create link.
• In any article or category editor view, by typing into the Tags box and hitting Enter
• In any article or category editor view, by pasting a comma-separated list of tags into the box and hitting Enter or tab. (example: alpha,bravo,charlie pasted in will create three tags: alpha, bravo, and charlie)

Our default Editor and Writer roles have permission to create tags. If you're using a custom author role, that role must have the Tag Permission to Add new tags to create tags.

Create tags in Tag Library

Creating tags in the Tag Library can be great if you:

• Need to create a lot of tags at once
• Want to be able to see tags that already exist while you create tags
• Want to be able to create the tag and mark it as internal/hidden from readers

To do so:

1. Go to Library > Tags.
2. Click the Create  link near the upper left of the screen.
   
3. This will open the Create tag pop-up. Add the Name you'd like displayed for the tag. If you'd like to use this tag only within app.knowledgeowl.com, check the box under Visibility to "Hide tag from readers". If you don't hide from readers, the tag will be visible in search and, potentially, in your article itself, depending on your configuration. See What are tags? for more information.
   Here, I've created an "announcement" tag that will be visible to all readers:
4. Once you've finished editing the tag, click the Create Tag button. The tag will be added to your library and immediately available for use.

Create tags in the editor individually

You can also create tags on the fly while you're editing an article, topic display category, or custom content category. 

To do so:

1. In the article editor and in select category editors (topic display and custom content), click in the Tags input box below the editor.
2. To add one tag at a time, type the name of your new tag.
3. Then hit Enter, tab, or comma, or click outside of the box.
   Sample tag creation in Article Editor
4. The tag(s) will be created in the Tag Library and added to this article.
5. Be sure to Save your article once you're done.

Create tags in the editor in bulk

You can add a list of tags separated by commas while you're editing an article, topic display category, or custom content category. This can be a great way to create or add tags in bulk.

To do so:

1. In the article editor and in select category editors (topic display and custom content), click in the Tags input box below the editor.
2. Type or paste in the list with each tag separated by a comma. For example: alpha,bravo,charlie,delta
   Sample paste of comma-separated list of tags in Article Editor
   
3. Hit Enter or tab, or click outside of the box.
4. The tags will be created in the Tag Library and added to this article.
5. Be sure to Save your article once you're done.

Once a tag has been created, you can edit it to update the name or change whether it's shown or hidden to readers.

Our default Editor and Writer roles have permission to edit tags. If you're using a custom author role, that role must have the Tag Permission to Edit exiting tags to edit tags.

To do so:

1. Go to Library > Tags.
2. Click on the tag you'd like to edit. (If you have a lot of tags, you may need to search to find the tag you want.)
3. Once you've clicked on a tag, the Edit link will activate. Click that link.
   
4. This will open the Edit Tag pop-up, where you can edit the name of the tag or check the box to hide it from readers (use it only in app.knowledgeowl.com).
5. Once you've finished making the changes to your tag, click the Edit Tag button in the lower right to save your changes.
   Click Edit Tag to save your changes to the tag
6. All articles with this tag will now display the updated name.

Once a tag has been created, you can delete it from the Tag Library. This will remove the tag from all articles or categories where it's been used.

Our default Editor and Writer roles have permission to delete tags. If you're using a custom author role, that role must have the Tag Permission to Delete tags.

To do so:

1. Go to Library > Tags.
2. Click on the tag or tags you'd like to delete. (If you have a lot of tags, you may need to search to find the tags you want.)
3. Once you've clicked on one or more tags, the Delete link will activate. Click that link.
   Select the tag(s) you'd like to delete and click the Delete link
4. This will open a confirmation pop-up to be sure you want to delete these tags. Click OK to delete them.
   Click OK to confirm the deletion of the tags you selected
5. All the tags you selected will be deleted and removed from any articles or categories that referenced them.

Creating a new tag is not always the same thing as adding a tag to an article.

Our default Editor and Writer roles have permission to add existing tags to articles and to create new tags. If you're using a custom author role, that role must have the Tag Permission to Add existing tags to articles but might not have the ability to Add new tags. (If you have both permissions, you can start typing and then create a new tag or select an existing; if you only have the ability to add existing tags to articles, you can only start typing and select from existing tags.)

To add an existing tag to an article:

1. In the article editor and in select category editors (topic display and custom content), click in the Tags input box below the editor.
2. Start typing the name of the tag. As you type, you'll get a list of autosuggested matching tags. You can use the arrow keys + Enter or click with your mouse to select the tag you'd like to add.
   Find existing tags by typing part of the tag and selecting the tag you'd like to add
3. Once you've finished adding tags, be sure to Save the article or category you're working in.

Removing a tag from an article simply removes it from the article--it doesn't delete the tag from your knowledge base. If you'd like to delete a tag from your knowledge base completely, see Delete a tag.

Our default Editor and Writer roles have permission to remove existing tags from articles (and to delete tags completely). If you're using a custom author role, that role must have the Tag Permission to Remove tags from articles but might not have the ability to Delete tags.

To remove a tag from an article:

1. In the article editor and in select category editors (topic display and custom content), scroll to the Tags input box.
2. Click the x next to the tag you'd like to remove.
   Click the X on the tag you'd like to remove
3. Be sure to Save the article or category.

Tags are displayed in search to give the reader additional context as to what the article is about and what it relates to. A reader can click on a tag to navigate to a list of all articles with that tag. 

Sample search results with tags displayed

Clicking on a tag performs a special operation in the search that bypasses the regular search and returns a list of all articles with the same tag. You can manually perform a tag search by putting a colon in front of the tag name, like this:

See Tag Searches for more information on how tag search works.

Listing articles by tag

If you like, you could get really fancy and create a link that lists all articles with a certain tag. The link would look something like this, replacing "flying" with your tag. 

/help/search?phrase=:flying

You may also need to replace "help" with "home" if that's how your knowledge base is set up.

For example, this link will search for the "subscription" tag referenced in the above screenshots: https://support.knowledgeowl.com/help/search?phrase=:subscription

KnowledgeOwl search results will automatically display all tags assigned to a given article :

Sample of Tags showing in Search Results

However, if you're using tags for custom filters in the Manage Articles interface, you might not want those internal tags to be shown in search results.

You can mark tags like this as hidden from readers. Hiding a tag from readers:

• Keeps it visible in the article editor and category editor
• Allows it to be used as a filter in Manage Articles custom filters
• Prevents the tag from appearing in search results in your knowledge base
• Prevents the tag from appearing in the typeahead suggestions when a reader types ":" to begin a tag search

To hide an existing tag from readers:

1. Go to Library > Tags.
2. Click to select the tag you'd like to hide from readers.
3. Click on the Edit link.
   Select the tag you'd like to hide and click Edit
4. In the edit pop-up that appears, under Visibility, check the box next to "Hide tag from readers."
5. Click the Edit Tag button to finalize your changes.
   Check the box to Hide tag from readers, then click Edit Tag to finalize your changes
6. Regular tags will have a normal tag icon in the Tags Library; tags hidden from readers will have a padlock icon. Here, "javascript" is a tag readers can see, and "tipsandtricks" is hidden from readers:
   Sample tags; the tag on the left with the tag icon is viewable to readers; the tag on the right with the padlock is not
   

Like your product, company, and policies, tags might change over time. And without clear style guidelines (and even sometimes with them!), different authors might create differently-structured tags. Linus has faced this problem several times in our documentation, for example, some content was tagged with SSL cert and some was tagged with ssl certificate. What's an owl to do?

Users with our default Editor or Writer roles, or those with custom roles who have permission to both edit and delete tags have the option to merge two tags together.

Merging allows you to replace one tag with the other and delete the now unneeded tag. It's fast and much easier than auditing articles through a Manage filter.

To merge tags:

1. Go to Library > Tags.
2. Click on the tag you'd like to merge into another tag. This will be the tag that gets removed. Here, we'll use SSL cert and merge it into ssl certificate.
3. With the tag selected, the Edit and Delete links will become activated. Click on the Edit link.
   
   Click the tag you'd like to merge and then click the Edit link
4. This will open the Edit Tag pop-up. If you have the proper permissions to merge tags, you'll see a Merge into different tag option in the lower left. Click on this link.
   
   Click the Merge into different tag link to begin the merge process
5. On the next screen, you'll be able to search for the "new" tag you'd like to merge this tag into. Start typing the name of the New tag you'd like to merge this tag into and select the correct name. Here, I'm using our ssl certificate tag as the new tag.
   
   Add the tag you'd like to merge the current tag into
   During the merge:
   • The "new tag" will be added to all of the current tag's articles. For example, all articles with "SSL cert" will get the "ssl certificate" tag added as part of the merge. It will also remain in your Tag Library moving forward.
   • The "current" tag will be deleted from your Tag Library and all articles when the merge is complete. Any Manage filters including this tag will have the tag removed.
6. Once you've added the "New tag" you'd like to keep, click the Merge Tags button to begin the merge.
   
   Click the Merge Tags button to begin the merge
7. You'll see a confirmation message to be sure you want to merge these tags. Tag merges cannot be undone. Click OK to complete the merge.
   
8. When the merge is complete, you'll be directed back to the main Tag Library screen.

In each tag merge, there are two tags:

• The current tag (the tag you began the merge from)
• The new tag (the tag that will remain when the merge is complete)

Merging will:

• Add the new tag to all articles that have the current tag
• Remove the current tag from all articles
• Delete the current tag from the Tag Library

Let's assume I'm using this scenario in my merge:

A sample tag merge scenario

SSL cert is the tag I began the edit and merge with.

When I complete the merge:

• That SSL cert tag won't exist anymore
• All articles that had SSL cert as a tag will have the ssl certificate tag
• Articles that had both tags will just get the SSL cert tag removed
• Any Manage filters that used SSL cert tag as a filter will have the tag removed--you'll need to manually update them to add the ssl certificate tag

In the Tags Library, you can generate a Tags Usage Report to help you audit your tags.

This report comes in CSV format, with three columns:

• Tag Name: the text of the tag as it appears in your knowledge base
• Article Usage: a count of all the non-deleted articles that use this tag
• Category Usage: a count of all the topic display and custom content categories that use this tag

How do I generate a report?

To generate a tags usage report:

1. Go to Library > Tags.
2. Select the link to Generate Usage Report.
   
3. You'll see a progress spinner while the usage report is being generated.
4. Once it finishes, the text will change to a link prompting you to Download Usage Report.
   
5. Click that link to download the CSV.

Additional actions will depend on which browser you're using.

How can I use this report?

The tag usage report is great for tag audits. It can help you identify tags:

• That aren't used anywhere (have 0 Article Usage and 0 Category Usage), which are "safe" to delete: Sort by the Article Usage column and review
• That are slight variations or duplicates of each other so they can be merged: Sort by the Tag Name column and review
• With low usage overall that might be candidates for deletion, merging, or editing: Sort by the Article Usage or Category Usage columns and review
• Identify tags that are misspelled or improperly formatted for editing: Sort by the Tag Name column and review

What does it look like?

Here's a sample of the top of our tag usage report, sorted by the Article Usage column: