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).
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:
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.
Glossary terms may contain:
- Alpha-numeric characters
- Spaces ( )
- Dashes (- and --)
- Underscores ( _ )
- Apostrophes ( ' )
Other characters (like parentheses and quotation marks) will be removed.
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.
Display titles are used for the glossary page display only and have no impact on automatic highlighting.
You can style text in glossary definitions using HTML:
- Paragraph breaks
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.
You can add glossary terms and definitions individually or in bulk.
Adding a glossary term
To add a single glossary term:
- Go to Knowledge Base > Glossary.
- Click the + Add Term button.
- This will expand an area where you can add the details for your glossary term.
- 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.
- Once you've added your term and definition, click the Add Term button.
- Your term will now appear in the glossary.
Adding glossary terms in bulk
To add multiple glossary terms at once:
- Go to Knowledge Base > Glossary.
- Click the ^ Import Terms button.
- Click the Example Glossary CSV link in the lower left to download a sample CSV file you can use as a template.
- 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.
- 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!)
- 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:
- Once you've made your selections, click the Import Terms button.
- 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, 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:
- Go to Settings > Search.
- In the Glossary snippets section, check the box next to "Display glossary definition for matching term."
- Save your changes.
You can now run a search for a glossary term and see it appear at the top of search results:
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!
By default, your glossary page doesn't show up in search results. This means that if a user 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:
- Go to Settings > Search.
- In the Glossary snippets section, check the box next to Display link to glossary when "glossary" is searched for.
- 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!
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:
- Go to Settings > Basic.
- Look for the Website Settings.
- In the Table of contents section, check the box next to "Add a glossary link to the top of the table of contents".
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:
- Go to Settings > Basic.
- Scroll to the Website Settings section.
- In Glossary Terms, check the box next to "For each glossary term that appears in an article..."
- 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.
- 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.
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:
- Make sure the glossary term and definition exist in the glossary.
- In the article editor, highlight the word or phrase you want to provide a definition for.
- Click on the Add Glossary Term icon in the editor.
- This will open a pop-up where you can search for and select the glossary term.
- 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.
- Once you've selected the term you want, click the Insert Glossary Term button to finish inserting the definition into your article.
- 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!
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.
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.