Glossary

Overview

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

Screenshot showing a sample glossary term with double underline and on-hover definitionSample 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.

Glossary formatting

To use the glossary, you'll need to create glossary terms and give each term a definition. You can also include an optional alternate 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, the alternate title is used on that page 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.

Alternate titles

Use alternate titles to display a different title for the term on the built-in glossary page. These titles are automatically formatted in bold. They can include parentheses and quotation marks, which are prohibited in the terms.

Alternate titles are used for the glossary page display only and have no impact on automatic highlighting.

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.

If you're not familiar with HTML, you can also format the text you want in an article editor, switch to the Code View or Source, copy the HTML from there, and paste it into your glossary definition.

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.

Populate the glossary

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 alternate 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.
  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, alternate 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. 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. Once it directs you back to the Glossary page, your terms have been imported.

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

When should I use alternate titles?

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 title in the Glossary page itself.

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 alternate title is for: it's basically the version of the term you'd like to appear on the glossary page.

If no alternate title is specified, then the term itself is used. If an alternate 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 alternate title is what's used on the glossary page, but IdP is still used in the autohighlighting of glossary terms.

Alternate titles can be great for:

  • Displaying the full term with an acronym in parentheses (e.g. term = We Love Owls and alternate title = We Love Owls (WLO))
  • Displaying a term with a list of additional terms (e.g.  term = Identity Provider and alternate 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 alternate title = Human Resources Department)

View the glossary

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 

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

Automatically highlight definitions in articles

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.

Add glossary definitions in articles manually

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

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.

When one glossary term contains another glossary term

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.

In these situations, the automatic highlighting will always highlight the shorter term (check) and won't highlight the longer term (price check).

If you run into this situation, we recommend manually adding the correct multi-word glossary term 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).

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.

Customize how glossary terms look

The default highlighting of a glossary term looks like this: test

You can customize this a bit using custom CSS.

Terms

You can customize the look and feel of your glossary terms (the double underline) to change the thickness of the lines, the color, and the line style. To do so:

  1. Go to Settings > Style.
  2. Under the preview pane, select Custom CSS.
  3. Copy the code below and paste it into the Custom CSS window.
    /* Change glossary term underlining look */
    .ko-glossary-term {
      border-bottom: 3px #bbb double;
    }
  4. You can make changes to the look by editing:
    • The thickness of the underlines: change 3px to the thickness you'd like to use. Lower pixels are thinner; higher are thicker
    • The color of the underlines: change #bbb to the color of your choice
    • The style of the line: change "double" to the style of your choice, using standard border-style options (double, dashed, dotted, etc.). If you're unfamiliar with border-style, see this quick reference for the available options.
  5. Once you've made your changes, Save your Style Settings. All glossary terms are now updated with the changes you've made.

In this sample, we've change the line width to 2px, made it a darker grey, and shifted it to a single dotted line instead:

Sample code

Which will produce this treatment:

Glossary term underlining based on the sample above

Definitions

The hover-over definition can also be customized. 

  1. Go to Settings > Style.
  2. Under the preview pane, select Custom CSS.
  3. Copy the code below and paste it into the Custom CSS window.
    /* Change on-hover glossary definition display */
    span.ko-glossary-term + .popover {
      font-size: 14px;
      font-weight: normal;
      line-height: 1.2;
    }
  4. You can change the font size and weight (bold vs. normal) by editing appropriately. The popover is done using Bootstrap. See their popover documentation for more options.
  5. Once you've made your changes, Save your Style Settings. All glossary definitions are now updated with the changes you've made.

Keep glossary header visible when scrolling

By default, when you view the Glossary, the title and the quick-links to each letter will disappear as you scroll the page.

Default glossary behavior

If you have a lot of glossary terms and you're linking to your glossary in your table of contents or navigation, you may want to keep the Glossary header visible while scrolling.

Sticky glossary header

To add this functionality to your knowledge base, you'll create a snippet to store the code and then add that snippet to the Custom HTML:

  1. Go to Library > Snippets.
  2. Click the + New Snippet button.
  3. Give your snippet a Name (Sticky glossary header, in our example).
  4. Give your snippet a Description, like "Make the glossary header "sticky" so it's always visible as people scroll."
  5. Click the dropdown next to Snippet Content to select Code Editor.
  6. Copy the script below and paste it into the code editor.
    <script>
      $(function(){
        // Adjust the pathname listed below depending on your KB settings. It might be 'help/glossary', '/home/glossary' or '/docs/glossary'
        if(window.location.pathname == '/help/glossary') {
          if($('.ko-content-cntr').length > 0)
            var articleCont = $('.ko-content-cntr');
          else 
            var articleCont = $('.documentation-article');
          var articleWidth = articleCont.width();
          var navTop = $('.hg-header').outerHeight(true);
          var topDiv = $('<div/>', {class: "ko-glossary-topdiv"});
          articleCont.prepend(topDiv);
          topDiv.append($('h1.page-header')).append($('div.glossary-jump-to'));
          var topOfJumpto = topDiv.offset().top;
          var jumptoHeight = topDiv.outerHeight(true);
          topDiv.affix({
            offset: {
              top: topOfJumpto - navTop,
            }
          });
          //add dynamic reusable styles
          $('<style>.ko-glossary-topdiv.affix{top:'+navTop+'px;width:'+articleWidth+'px;background:#fff;}.ko-glossary-topdiv.affix + .glossary-terms-wrapper{margin-top:'+jumptoHeight+'px}</style>').appendTo('head');
        }
      });
    </script>
    
    <style>
      /* Make sure that glossary header doesn't cover content when you jump to a letter */
      .hg-glossary-page a:not([href]) {
        display: block;
        height: 200px;
        margin-top: -200px;
        visibility: hidden;
      }
    </style>
  7. The code is used for knowledge bases with /help/ in their URLs. If you are using 'home' or 'docs' instead, you'll need to update the window.location.pathname in the fourth line based on your knowledge base's settings to '/home/glossary' or '/docs/glossary'.
  8. Click the Create button in the upper right. Here's what a completed snippet might look like:
    Sample sticky glossary header snippet
  9. Once it confirms your snippet is created, copy the Merge Code Value ({{snippet.stickyGlossaryHeader}} in our example).
  10. Go to Settings > Style.
  11. Below the preview pane, click on Custom HTML and select Body from the dropdown.
  12. Paste the snippet merge code value into the bottom of the window.
  13. Click Save.
    Sample Custom Body HTML with snippet merge code added

Your glossary's header should now stay at the top regardless of how far down your readers scroll.

Add search to the glossary page

You might want to add a search box to your glossary page if you:

  • Have a lot of glossary terms
  • Have readers who frequently reference your glossary
  • and/or have a link to your glossary in your table of contents

We've worked up a code snippet that:

  • Creates a search box at the top of the Glossary with "Search glossary" placeholder text
  • As you type to search, it will collapse glossary letters/sections with no matches and highlight terms that match your search phrase in yellow (you can change this color)

Here it is in action with the default settings:

Create the snippet and add it to your knowledge base

To add this search box to your glossary:

  1. Go to Library > Snippets.
  2. Click the + Create New Snippet button.
  3. This will open a Snippet details screen. Give your snippet a Name, like "Glossary Search".
  4. Give your snippet a Description, like "This snippet adds a search box to the glossary."
  5. In the Snippet Content section, click the dropdown to select the Code Editor.
  6. Copy the code below and paste it into the Code Editor window.
    <script>
    $(function(){
      //Glossary
      if($('.hg-glossary-page') && $('.hg-glossary-page').length >= 1) {
        $('.page-header').append('<input type="text" id="glossary-search" placeholder="Search glossary">');
        $('input[id=glossary-search]').keyup(function() 
                                             {
          $('.glossary-term').removeHighlight();
          var term = $(this).val().toLowerCase();
          $('.glossary-term').each(function()
                                   {    
            if ($(this).text().toLowerCase().indexOf(term) > -1) {
              $(this).show().highlight(term);
            }
            else {
              $(this).hide();
            }
          });
        });
      }
    });
    </script>
    
    
    <script src="//dyzz9obi78pm5.cloudfront.net/app/image/id/56fa0cfd91121cd0337b6d9d/n/jquery.highlight-5">
    </script>
    
    
    <style>
      /* Style the search box */
      #glossary-search {
        height: 28px;
        font-size: 14px;
        float: right;
        width: 300px;
        padding: 2px;
      }
      
      /* Highlight color for search term matches */
      .highlight { 
        background-color: yellow;
      }
    </style>
  7. Once you're done, click the Create button in the upper right.
  8. So a completed snippet might look like this:
  9. Once your snippet is created, copy the snippet Merge Code Value.
  10. Go to Settings > Style.
  11. Below the preview pane, click on Custom HTML and be sure the Body is selected.
  12. Paste your merge code in at the bottom of your Custom HTML Body (or between scripts), and save.
  13. You should now have a search box on your glossary page!

Common tweaks

Once the snippet is working, you can make changes to the snippet to adjust the style:

  • Change the placeholder text: In the first script, find this line:
    $('.page-header').append('<input type="text" id="glossary-search" placeholder="Search glossary">'); 
    and replace "Search glossary" with the placeholder text you'd like to use, for example:
    $('.page-header').append('<input type="text" id="glossary-search" placeholder="Start typing to search glossary...">');
  • Change the highlight color: in the style section, replace the .highlight background-color with a color of your choice, for example:
      /* Highlight color for search term matches */
      .highlight { 
        background-color: #80bd01;
      }
  • Change the style of the search box: you can change the height, font-size, width, etc. by updating the appropriate values in the style section's #glossary-search styles.

Glossary FAQs

Do glossary items show up in search?

Not right now but we do have a feature request to add the glossary to search results.   Contact us if you are interested in this feature and we can add you to the list!

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?

Each knowledge base has a single glossary that is used for the glossary page as well as providing contextual definitions. If you need multiple glossaries, you can alternatively create separate articles for the separate glossaries. We can make the page look and function like the glossary. Contact us and we can help you get it set up!

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.