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.

Adding a glossary term

To add a single glossary term:

1. Go to Knowledge Base > Glossary.
2. Click the + Add Term button.
   
   Click the + Add Term button
3. This will expand an area where you can add the details for your glossary term.
4. The term is the word that you want to appear in the glossary or your documentation (if you're using highlighting). The definition is the definition you'd like displayed with that term. The display title will display on the Glossary page instead of the term--it can be a great way to incorporate an acronym or alternate term without impacting highlighting. The definition can contain basic HTML, including hyperlinks and text formatting.
   
5. Once you've added your term and definition, click the Add Term button.
   
6. Your term will now appear in the glossary.

Adding glossary terms in bulk

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. You can choose to Update existing terms with the new definitions (this will overwrite the existing definition with the term's definition in your CSV file) or Skip existing terms (which will keep the existing definition you have for the term). 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 choose to display glossary terms and their definitions at the top of relevant search results.

If you're using Glossary, you can choose to display glossary terms that match the search phrase at the top of search results. Here's how it works:

• If your reader searches a phrase that exactly matches a glossary term, the term and its definition will be displayed in a box at the top of the search results.
• The glossary search result also includes a link to the specific letter in the Glossary that this term falls under.
• You can add custom CSS to style this box however you'd like.

To enable the setting:

1. Go to Settings > Search.
2. In the Glossary snippets section, check the box next to "Display glossary definition for matching term."
   
3. Save your changes.

You can now run a search for a glossary term and see it appear at the top of search results:

Sample search showing a matching glossary term at the top

If you're using Contextual Help Widget (2.0), these search results will also be displayed in widget searches:

With glossary snippets enabled, see Style the glossary snippet search results to give these results the look and feel you want! Don't like the word "Glossary"? Use the Search section of the Customize Text tool to change the text that appears there!

By default, your glossary page doesn't show up in search results. This means that if a reader types "glossary" in search, they won't get any results, or at least won't get the glossary page as a result.

But you can set it so that someone searching for "glossary" will get the glossary page as a result.

To enable this option:

1. Go to Settings > Search.
2. In the Glossary snippets section, check the box next to Display link to glossary when "glossary" is searched for.
   
3. Save your settings.

Now, when a reader searches for "glossary", they'll see an option to View Glossary at the top of the search results:

You can change the look and feel of that section using the Style the glossary snippet search results options, too!

Don't like the wording for "View Glossary"? Never fear--use the Search section of the Customize Text tool to change it. 😉

Have you used the Customize Text tool to change the word "Glossary" to something else on the Glossary page itself? Never fear! This setting will apply to both the word "glossary" and whatever custom text string you've used!

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, home page, or articles using the link "/help/glossary".

Once you have set up glossary terms, you can automatically provide hover-over definitions for these terms in your articles.  To turn on this option:

1. Go to Settings > Basic.
2. Scroll to the Website Settings section.
3. In Glossary Terms, check the box next to "For each glossary term that appears in an article..."
   Check the box next to Glossary Terms and use the numeric dropdown to set the number of highlights
4. Set the numeric dropdown at the end of that row to set the number of times you want each term to be automatically highlighted in each article. To prevent readers from being overwhelmed by tons of underlines, we limit you to 10 automatically highlighted terms per article. We will highlight terms starting from the top of the article and working down, so if you choose 3 here, we will highlight the first 3 appearances of each glossary term in the article.
5. 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 abbrevations, plurals, etc.), you can manually create a link to the glossary definition.

See Website Settings for more information on other settings available in Settings > Basic.

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.

If you'd like to rename the Glossary to something else (like Dictionary), there are a few places in the Customize Text tool you should update:

• Miscellaneous: Update the Glossary page title text string. See Section breakdown: Miscellaneous for more information.
  • If Settings > Search has the option to Display link to glossary when "glossary" (including customized text term) is searched for enabled, 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. See the Search settings below on how to update the text there!
• Table of Contents: If Settings > Basic has the option to Add a glossary link to the top of the table of contents enabled, update the Table of contents glossary link text string. See Section breakdown: Table of Contents for more information.
• Search:
  • If Settings > Search has the option to Add the glossary page to your search results enabled, update the Glossary snippet link to Glossary text string
  • If Settings > Search has the option to Display glossary definition for matching term enabled, update the Glossary snippet search result link to Glossary text string
  • See Section breakdown: Search for more information