Glossary

One of the challenges facing content creators is making sure that readers understand common terms, acronyms, and abbreviations without disrupting the flow of content. At its worst, editors are left defining a term once and linking back to that, or repeatedly manually adding definitions into the body of their articles by copying and pasting or retyping, which is either redundant work or potentially inconsistent work.

That's why KnowledgeOwl has a built-in Glossary (Knowledge Base > Glossary).

Sample glossary

Here, you can define the terms, acronyms, and abbreviations used in your documentation. They're sorted and displayed alphabetically automatically. If you have terms beginning with numbers, these will be sorted and displayed first. Readers can view your full glossary and you can add a link to it to your table of contents. You can opt to automatically highlight glossary terms a set number of times in articles, or to manually insert definitions as you create content.

Highlighted glossary terms get a double underline in articles and the definition will appear in a pop-up when readers hover over that term:

Sample glossary term underlining and on-hover definition

The glossary highlighting feature is a great way to improve consistency in your documentation while minimizing redundant work and keeping your docs looking clean.

To use the glossary, you'll need to create glossary terms and give each term a definition. You can also include an optional display title.

The term is the word that you expect someone to see in your documentation; the definition is the definition you'd like displayed for that term. If you're using the built-in glossary page or are showing glossary terms in search results, the display title is used in those places instead of the term, which allows you to include an acronym alongside the term, etc.

Sample glossary term + definition

Terms

Glossary terms may contain:

• Alpha-numeric characters
• Spaces ( )
• Dashes (- and --)
• Underscores ( _ )
• Apostrophes ( ' )

Other characters (like parentheses and quotation marks) will be removed.

Display titles

Use display titles to display a different title for the term on:

• The built-in glossary page
• Glossary term search results, if used

These titles are automatically formatted in bold. They can include parentheses and quotation marks, which are prohibited in the terms.

When a display title is used, that title's spelling will be used for the glossary page alphabetical listing.

Definitions

You can style text in glossary definitions using HTML:

• Bold <b>
• Italics <i>
• Underline <u>
• Hyperlinks <a>
• Superscript <sup>
• Subscript <sub>
• Paragraph breaks <br>
• Strong <strong>
• Emphasis <em>

Use plain HTML format to add these.

You can add links to articles or other pages in glossary definitions using plain html:

This is the definition. For more information, see <a href="/help/amazing-article">this amazing article</a>.

Glossary definitions cannot contain images. They often don't format well in the pop-overs and can lead to broken HTML, so we don't allow them. We recommend inserting a link to the image in the definition, instead.

You can add glossary terms and definitions individually or in bulk.

To add a single glossary term:

1. In the left navigation, go to Glossary. The Glossary page opens.
2. Select the + Add Term button. An area expands just below the button where you can add the details for your glossary term:
   
   The new term entry section
   
3. Enter the word that you want to appear in the glossary as the Term. If you're using automatic highlighting, this term should be what you want the highlighting to match on.
4. Enter the definition you'd like displayed with that term. The definition can contain basic HTML, including hyperlinks and text formatting. Refer to Glossary formatting for more information.
5. Optional: If you want to display a longer or alternate version of the automatic highlighting term in your glossary, enter it as a Display Title. This won't impact the automatic highlighting, but does allow you to include an acronym after the without impacting highlighting. For example, if we have a term for SSO, we might set a display title of "Single Sign-On (SSO)" to explain the acronym. Refer to When should I use display titles? if you're unsure whether you need or want a display title.
6. Once you've added your term and definition, select the Add Term button.
   
7. Your term will now appear in the glossary. If you have automatic highlighting turned on, the term will also be highlighted.

If you already have a list of terms you'd like to add to your glossary, you can choose to import those terms in bulk, saving you time from having to create them each individually. To do so, you'll need the terms in a CSV file that includes columns for:

• The glossary term: the word or phrase you want to define
• An alternate title (in the interface, this is called the display title): If you want to display a phrase with an acronym or other prohibited punctuation, you'll need to use a display title. While you don't have to use a display title, the import won't succeed without having an alternate title column present.
• The term's definition

To add multiple glossary terms at once:

1. Go to Knowledge Base > Glossary.
2. Click the ^ Import Terms button.
   Click the Import Terms button
3. Click the Example Glossary CSV link in the lower left to download a sample CSV file you can use as a template.
   Example Glossary CSV
4. Use the template as a model; replace the terms, display titles, and definitions there with your own. Once your CSV has all your glossary terms in it, you can repeat the steps above and click Choose File to add your file.
   
5. If your CSV contains a header row, like our sample CSV file, check the box next to Skip the first row of the CSV. If your CSV file has no header row, leave this box unchecked.
   Be sure that the first two rows of your CSV are not empty. (If they are, the importer won't "see" any data and won't import anything!)
6. If this is your first time adding terms, you can choose either the Update or Skip option. If you already have glossary terms, you'll need to tell the importer what you want it to do if your CSV contains terms that match terms you already have:
   1.  Update existing terms with the new definitions will overwrite the existing definition with the term's definition in your CSV file
   2. Skip existing terms will keep the existing definition you have for the term
   3. Here's a sample upload with my file added, skipping the first row and updating existing terms:
      Sample upload
7. Once you've made your selections, click the Import Terms button.
8. If for some reason we are unable to import your glossary terms due to an invalid character, a message will be displayed with the rows that threw the error. See Troubleshooting glossary term imports if you run into this issue.
9. If we're able to import the CSV file, you'll see a progress bar while the import processes. Depending on the size of your glossary, this may appear for a split second or up to a minute.
10. Once the progress bar disappears and redirects you back to the Glossary page, your terms have been imported.

Glossary terms will automatically be displayed in alphabetical order, with terms beginning with numbers appearing first. When your glossary gets larger, you can use the search feature to quickly find a term.

You can display glossary terms and their definitions at the top of relevant search results.

If you're using the Glossary, you might want glossary term definitions to display when someone searches for a glossary term anywhere in your knowledge base. We call this adding a Glossary term callout to your search results:

Sample glossary callout for glossary term definition of IdP

Here's how it works:

• If your reader searches a phrase that exactly matches a glossary term, the term and its definition are displayed in a box at the top of the search results.
• The glossary callout also includes a link to the specific letter in the Glossary that this term falls under.
• If you're using Contextual Help Widget (2.0), these glossary callouts are also displayed at the top of widget full search results:
  
  Sample glossary term callout in the contextual help widget

To turn on this feature:

1. Go to KB settings > Search and synonyms. (Or, from the Glossary page, select Edit in settings next to "Definitions at the top of the search results.") The Search and synonyms page opens to the General settings tab.
2. In the Search page display section, under Glossary callouts, check the box to Display the glossary definition when a reader searches for a glossary term.
3. Be sure to Save your changes.

By default, your glossary page doesn't show up in search results. This means that if a reader enters "glossary" in search, the Glossary page won't be in their list of search results automatically. But don't worry--KnowledgeOwl has a setting for this so a link to the Glossary page displays in a box above all other search results:

Sample glossary page callout

To turn on this setting:

1. Go to KB settings > Search and synonyms. (Or, from the Glossary page, select Edit in settings next to "Definitions at the top of the search results.")
2. In the Search page display section, under Glossary callouts, check the box to Display a link to the full glossary page when a reader searches for the word "glossary".
3. Be sure to Save your settings.

If you're using the Glossary, you can add a link to the glossary to your table of contents. The link displays with a small book icon:

Sample Glossary link and icon in the table of contents

To add a glossary link to the top of your table of contents:

1. Go to Customize > Website. (Or, from the Glossary page, select Edit in settings next to Link in the table of contents.)
   
2. In the Links and behavior section, under Table of contents elements, check the box to Add a glossary link to the top of the table of contents.
3. Save. You should now see the glossary at the top of your TOC.

Refer to Website settings for more information on other settings available in Customize > Website.

All glossary term highlighting is driven by the glossary term itself. This term cannot contain parentheses, quotation marks, and other special characters.

This works well for highlighting, but it's not uncommon to want to display a more complete version of the term in the Glossary page itself or in the glossary term search results.

For example: in our glossary, we have a glossary term for IdP. This is the term that we use everywhere in our documentation, so we keep that as the term itself so our highlighting works properly.

But for our glossary page itself, we like to display the full title alongside the acronym. This is what the display title is for: it's basically the version of the term you'd like to appear on the glossary page.

If no display title is specified, then the term itself is used. If a display title is present, that's what's used.

So here's what the term's setup looks like in Knowledge Base > Glossary:

And here's how it displays in our glossary:

Note that the display title is what's used on the glossary page, but IdP is still used in the autohighlighting of glossary terms.

Display titles can be great for:

• Displaying the full term with an acronym in parentheses (e.g. term = We Love Owls and display title = We Love Owls (WLO))
• Displaying a term with a list of additional terms (e.g.  term = Identity Provider and display title = Identity Provider (a.k.a. Identity Service Provider; Identity Assertion Provider))
• If you use the glossary to provide contact details on departments or individuals, this could be the full department name or the person's name + title (e.g. term = HR Dept and display title = Human Resources Department)

The glossary is a default page in every knowledge base. Its permalink is always "glossary", so you can get to the glossary by going to "/help/glossary" in your knowledge base (or "/home/glossary" or "/docs/glossary" if you are using a different root path).

For example, here is the glossary page for our help and documentation (we haven't set ours up yet so you'll only see some test terms): https://support.knowledgeowl.com/help/glossary 

The Glossary page displays all alphabet letters at the top. When that letter has one or more glossary terms available, the letter is hyperlinked, and clicking on it will direct you to that letter's section in the Glossary.

If you are ready to share your glossary with your readers, you can add it to the table of contents:

1. Go to Settings > Basic.
2. Look for the Website Settings.
3. In the Table of contents section, check the box next to "Add a glossary link to the top of the table of contents".  Settings > Basic > Website Settings
4. Save.

You can also manually link to it from your top navigation, homepage, or articles using the link "/help/glossary".

If you'd like to rename the Glossary to something else (like Dictionary), update these settings in Customize > Default text:

• Miscellaneous: Update the Glossary page title text string. Refer to Section breakdown: Miscellaneous for more information.
  • If your search has the box to Add the glossary page to your search results checked, the custom text string you enter here will also return the glossary page when it's searched for. For example, if we use "Dictionary", someone will be able to search for "dictionary" and the glossary page will return in search results. Refer to the Search settings below on how to update the text there!
• Table of Contents: If Customize > Website has the box to Add a glossary link to the top of the table of contents checked, update the Table of contents glossary link text string. Refer to Section breakdown: Table of Contents for more information.
• Search:
  • If KB settings > Search and synonyms > General settings has the box to Add the glossary page to your search results checked, update the Glossary snippet link to Glossary text string.
  • If KB settings > Search and synonyms > General settings has the box to Display glossary definition for matching term checked, update the Glossary snippet search result link to Glossary text string.
  • Refer to Section breakdown: Search for more information

Once you've set up glossary terms, you can automatically provide hover-over definitions for these terms in your articles. This helps ensure terms are consistently highlighted without any extra work for your authors or anyone having to remember to insert them.

To turn on this option:

1. Go to Customize > Website. (Or, on the Glossary page, select Edit in settings next to Automatic article highlighting to jump there!)
2. In the Links and behavior section, under Glossary terms, check the box to For each glossary term that appears in an article, automatically highlight the term xx time(s).
3. Use the numeric dropdown to set the number of times you want each term to be automatically highlighted in each article. We'll highlight terms starting from the top of the article.
4. Save your changes.

For automatic highlighting to work, the terms in the articles must exactly match the terms in the glossary. If your article contains variations of a term (such as abbreviations, plurals, etc.), you can manually create a link to the glossary definition.

Refer to Website settings for more information on other settings available in Customize > Website.

In addition to automatically highlighting up to 10 glossary terms per article, you can also manually insert glossary definitions. Manually inserting definitions has several advantages:

• Since you are specifying when and where you want to define terms, it gives you the most control.
• Automatic highlighting requires an exact match; manually inserting definitions allows you to include definitions for variations of words, acronyms, and so on.
• It can help guarantee that a multi-word term is properly highlighted even when it includes another glossary term.
• You can see in the article editor which definition terms will be highlighted (with automatic highlighting, you have to preview or view the published article).
• Manually inserting definitions is the only way to highlight glossary terms within tables, embedded topic articles, and divs, including the Well, Alert Danger, Alert Info, Alert Success, and Alert Warning divs.

To manually insert a definition for a term in an article:

1. Make sure the glossary term and definition exist in the glossary.
2. In the article editor, highlight the word or phrase you want to provide a definition for.
3. Click on the Add Glossary Term icon in the editor.
   Add Glossary Term icon
4. This will open a pop-up where you can search for and select the glossary term.
5. Text to Display will display the text you had highlighted to begin this process. You can edit it here if you'd like to change it.
6. Once you've selected the term you want, click the Insert Glossary Term button to finish inserting the definition into your article.
   
7. Be sure to save your article with these changes.

Once you insert the glossary term, you will see a double underline in the editor. The hover-over definitions can be viewed in preview or using the article live.

Sometimes, you might have a glossary term that is contained in a longer glossary term. For example, I might have glossary terms defined for check and price check.

If you use these terms in the same article, the automatic highlighting won't always behave consistently. In some cases, it will highlight the shorter term (check) and won't highlight the longer term (price check). In other cases, it will highlight the longer term (price check) and won't highlight the shorter term (check). It depends a bit on the order the terms appear in, how you've configured your automatic highlighting (how many times it will autohighlight the same term), punctuation, and other formatting.

If you run into this situation, we recommend manually adding the glossary terms using the steps in Add glossary definitions in articles manually.

For example, nocturnal owl is a glossary term. So is "nocturnal". If you hover over the definition earlier in this sentence, you'll see only the definition for nocturnal is showing--not for the full multi-word term.

But I can force this to show the correct definition if I manually insert the nocturnal owl term and definition to ensure it highlights properly (which I've done in this sentence). I can also manually insert the nocturnal definition to ensure it shows properly.

This manual highlighting of multi-word glossary terms should only be necessary when you have other glossary terms that contain a portion of that term, or when you want to include highlighting for a term that doesn't match exactly, such as nocturnal owls.

See Glossary look and feel for a more detailed look at all the ways you can change the style of glossary terms, the glossary page itself, or glossary search results!

Sometimes, your CSV file might contain characters that our Glossary doesn't support. If this happens, after you click the button to import terms, you'll see an error message displayed near the top of the page, noting that we were unable to import the glossary terms due to non UTF-8 characters in the spreadsheet. We'll provide a list of the rows from the CSV that contained these characters.

Here's what the error message looks like:

Sample error message for failed glossary term import

Resolving this message can get a little tricky. If you open the CSV in Excel or another spreadsheet program, they will often hide or display nothing for non UTF-8 characters.

So here's what we recommend for trying to resolve your errors:

1. Find wherever you have the CSV File stored on your computer.
2. Right-click and select Open With.
3. Choose a text editor, such as Notepad, Notepad++, Visual Studio Code, or any other basic text editor you have installed on your computer to open the CSV.
4. Find the rows in the CSV that correspond to the rows in the warning message displayed in KnowledgeOwl.
5. Text editors generally either display the characters outright OR they'll display an icon when they're unable to display a character (such as �). Look for an icon like that, an unusual character, or any kind of weird code/characters.
6. Once you find what you think is the offending character(s), delete them from the CSV in the text editor.
7. Once you've edited all of the rows that threw errors, Save your CSV file.
8. You can now try re-importing this same CSV file. Hopefully those changes did the trick!

If you're continuing to get glossary import errors and you can't figure out why, please contact us and include a copy of the CSV file. Our support owls should be able to help get things sorted out.

Do glossary terms show up in search?

They can, yes! The Glossary snippets option to "Display glossary definition for matching term" in Settings > Search will display a glossary term that exactly matches the search phrase. See Glossary snippets for more details.

Does the Glossary page show up in search?

Not by default, but you can set it so that searching the word "glossary" will direct readers to your glossary. See Add the glossary page to your search results for more details.

Can you add synonyms for glossary terms?

You can add synonyms as part of a definition or add synonyms as separate terms with text like "See xyz". We recommend defining the most commonly used term and listing synonyms in the definition. You can always manually provide definitions for the synonyms in articles using the Add Glossary Term option.

Example:

This is a definition. Synonyms: this, that, the other thing

We do have a feature request to add a synonyms feature. Contact us if you are interested in this feature and we can add you to the list!

Can you link from one glossary term to another?

Not currently. You can alternatively use text like "See also: this, that, this other thing" or link to an article. Contact us if you are interested in this feature and we can add you to the list!

Can you have more than one glossary?

No. Each knowledge base has a single glossary that is used for the glossary page as well as for automatic highlighting. If you have a need for multiple glossaries, you might consider having separate knowledge bases for the content that requires different glossaries.

Can you share a glossary between multiple knowledge bases?

We don't currently have a way to share a single glossary across multiple knowledge base. However, you can create a glossary in one, export the terms, and import them into other kb. You will need to manage the glossary for each knowledge base independently. 

Can you insert the full definition into an article as plain text rather than a popover?

Not currently but we do have a feature request to create a merge code or snippet for glossary terms. Contact us if you are interested in this feature and we can add you to the list!

Can you prevent a term from being highlighted in a particular article?

If you want to prevent a glossary term from appearing highlighted in a particular place, go to the Code View and put a span tag around part of the word. For example, if you have a glossary term for an acronym like ARE but you want to prevent highlighting on something like: "These are the instructions":

These a<span>re</span> the instructions

This will prevent the glossary term highlighting.