Snippets

Snippets are chunks of reusable content that can be placed within articles, categories, and even your theme's HTML. The content of the snippet can be as simple as a single word or sentence, or as complex as a JavaScript function that performs an action on whatever page it is used.

For example, you could create a snippet that contains your company's copyright information. Wherever you want the copyright to appear, instead of typing it out again and again, you would use the snippet's merge code in its place. 

When the page displays, the snippet merge code is replaced with the snippet's content. When you need to update your copyright information, you can edit and update the snippet content, and the changes will be automatically reflected wherever the snippet was used.

Text within snippets is not indexed for search.

You can choose to create a snippet from scratch or to copy an existing snippet to use as a starting point.

To create a snippet from scratch:

1. Go to Library > Snippets.
2. Select the  + Create New Snippet button.
3. Give your snippet a Name. This is how the name will appear in the Snippet Library and in snippet look-ups. The Merge Code Name will auto-generate from the Snippet Name, but you can edit it if you'd like to.
4. Give your snippet a Description. This will help describe what your snippet does to other authors (and may help remind you if you forget!) Here, we've added a name and description for a copyright statement. Add a Snippet Name, Merge Code Name, and Snippet Description
5. If your snippet is used to display text (as our copyright is), type and format the text you want to display directly in the WYSIWYG. 
6. For code-based snippets containing scripts or style tags, select the dropdown next to Snippet Content to select the Code Editor, and add your code there.
   Toggle to the Code Editor
7. Once you've finished formatting your snippet, select the Create button in the upper right to finalize creation and save your snippet.

Your snippet will now display in the Snippet Library, as well as in the look-up field when someone tries to Insert Snippet into an article.

In order to copy an existing snippet to use as a starting point, go to Library > Snippets to view a list of your current snippets. In the top right of each of the snippet panels there is a little gear icon. Click on that and you will see the option to copy which will pop up a confirmation.

Copy Snippet

Snippets need to have unique unique merge code names, so we will automatically add "Copy" to the new snippet, but you can edit the name and merge code to whatever makes sense to you.

You can add snippets to:

• Individual articles
• Categories
• Custom HTML (adding snippets to Custom HTML > Body is great for adding footer content; you can add snippets to Custom HTML > Article to add them to all articles)

To add a snippet, you will need to add its Merge Code Value--this is a value in double curly brackets, with snippet.MergeCodeName after it.

For individual articles:

1. Select the Insert Snippet control (two gear cogs icon) to add a snippet:
   
   The Insert Snippet control in the editor
2. This will open a pop-up where you can search for your snippet.
3. Type a part of the snippet's name; the window will suggest snippets as you type.
4. Click on the suggestion that matches it. This will display the Description and Snippet body so you can be sure you've selected the correct snippet.
5. Once you're sure you've selected the correct snippet, select Insert Snippet.
   
6. You should now see your merge code value in the article, like this:
   
   Merge codes will display in the editor in double curly brackets
   
7.  Once you Save your changes, anyone viewing the knowledge base will see the body of the snippet (if it's text) or will see the results of the code in it. For example:

Snippets don't save a full revision history like articles do, but you do have the option to Revert to previous save. This feature tracks the last three saves of the snippet so you can roll back changes to one of those previous saves. (It works similarly to our Undo changes to Settings > Style feature.)

Reverting to a previous save will roll back any changes to:

• Snippet Name
• Merge Code Name (and, by extension, the Merge Code Value)
• Snippet Description
• Snippet Content (whether in Code Editor or WYSIWYG Editor)
• Visibility settings (Hide from PDFs and Include snippet content in article blurbs)
• Any Restrict to Reader Groups selections

To revert to a previous save, you must have an Editor or Writer role, or a custom author role with the Edit snippet permission:

1. Go to Library > Snippets.
2. Open the snippet you'd like to recover changes on for editing.
3. Click the link to Revert previous save in the upper right corner below the Save Changes and Back buttons to begin the process:
   
   1. If you don't see this link in the upper right, it means we don't have a record of any previous saves to revert to. This can happen if:
      1. The snippet was created before 30 December 2023 and has been saved 0-1 times since then.
      2. The snippet was created after 30 December 2023 and has only been saved once after creation.
4. Once you click the link to Revert previous save, a pop-up will open with the most recent save information and a dropdown of available Previous Saves you can restore to.
   • KnowledgeOwl will store up to three recent saves for each snippet. These saves will be identified by the date/timestamp of the save, with the author who saved the changes in parentheses:
     Sample Previous Saves dropdown
5. Select the save you'd like to go back to from the Previous Saves dropdown.
6. Once you've made your selection, click Revert.
7. All of the snippet's details will be updated to the reverted save. You must Save the snippet for these changes to go live.

All created snippets are stored in the Snippet Library. To access this library, go to Library > Snippets.

Sample snippet library layout

Within the Snippet Library, you can:

1. Create new snippets.
   
2. Search for existing snippets using words in the snippet title and description.
3. Select any snippet to open it in edit mode.
4. Copy or delete a snippet by clicking the gear cog icon in the upper right corner.

There are a number of great use cases for snippets:

• Footers or other statements that need to be used a lot of places, such as confidentiality statements
• Brand names or terms that may change frequently: make a snippet for that term, only reference the snippet instead of the full term in all your documentation. When the term needs updating, update only the snippet and all your documentation is updated!
• Specialized sections for articles, such as Article Table of Contents
• Code to handle unusual formatting, or to provide a set of styles for individual articles that differs from your general knowledge base styles
• Adding third-party scripts, embeds, or functionality

See Snippet best practices for more details on how to handle some of these use cases gracefully!

Snippets can be incredibly powerful. Here are some general best practices for making good use of them.

The most common use cases for snippets are:

• Code or CSS
• In-line text
• Reusable content

Below, we've captured some general guidance and best practices for each use case, as well as some examples to help guide you in your snippet journey. Contact us if you have questions about anything not detailed below!

Code or CSS

One of the best use cases for snippets is to add HTML, code, CSS, or any combination of those.

Why you might want to do this:

• The snippet editor will support complex HTML that the article editor strips out on-save.
• You control where snippets are added, so it's a great way to add functionality or styling to a very specific, manually-selected subset of your documentation.
• Snippet references are tracked, so you can see at a glance where this code or CSS has been used, which makes auditing much faster.

For straight HTML, you can use the Code Editor for total control, or use the WYSIWYG editor to construct the HTML you need.

Best practices for adding code or CSS to snippets:

1. In the Snippet Content section, be sure that Code Editor is selected, not WYSIWYG editor.
2. Don't ever toggle back to the WYSIWYG Editor view, as that toggle applies the same extra-vigilant HTML parsing that the article editor does.
3. To add scripts, be sure you include opening and closing <script> tags.
4. To add code from other systems for embeds, etc., copy whatever code they give you exactly and paste it in. You don't need to add <script> tags if they aren't already in the embed.
5. To add CSS styles, be sure you include opening and closing <style> tags.

Here are some examples of those best practices at work:

Script and style

Some snippets can contain both scripts that do things and a style section to do CSS, like this one:

HTML and script

We have a snippet to create a Subscribe button for our custom content categories. This includes HTML to add the button merge code in a paragraph, as well as a script to insert the button where we want it:

Third-party script and style

Some third-party tools will provide specially-formatted HTML to add functionality. The regular article editor will generally strip these out because they aren't part of the HTML spec. Using a snippet for that special script is great--and you can still tuck a style section in for some extra styling of that element or others. For example, we embed our Zapier integration in our documentation. Zapier provided us with a pre-built script for this, but we also use some CSS to hide the article title. So we use Zapier's code and also include a style section to add our custom CSS:

In-line text

To use a snippet to add in-line text (such as a text variable you want to use various places), follow these general best practices:

1. In the Snippet Content section, be sure that Code Editor is selected, not WYSIWYG editor.
2. Add your in-line text directly into that Code Editor, with no paragraph or other tags around it.
3. Don't ever toggle back to the WYSIWYG Editor view, as that toggle will apply some auto-formatting like the article editor, and your text will get wrapped in a paragraph.

Example

For example, we have a set limit on the size of files you can upload to KnowledgeOwl. Since that limit might change at some point in the future, we use a snippet to provide the text, so if we update it, we only have to update the snippet and every article referencing it will update too. The Snippet Content for this is in Code Editor and just entered directly with no HTML:

Reusable content

The last major use case for snippets is that they can contain content you might want to reuse. Snippets can have reader group restrictions different from the article where they're embedded, so this can sometimes be a way to show content to some folks but not others.

Best practices for using snippets for reusable content include:

1. Be sure a topic article wouldn't be a better choice.
2. Make sure it's content you don't expect to turn up in search; snippet content is NOT indexed for search (topic article content is, though!)
3. We recommend using the WYSIWYG Editor for the Snippet Content here, to be sure the content looks and is laid out exactly how you want it.

The best use cases for this include things like:

• Callouts or alerts that you want to standardize/reuse and don't need indexed for search
• Copyright statements or other disclaimers

To help with content auditing and visibility, KnowledgeOwl tracks when you save an article or a custom content category containing a snippet's merge code. We save this information in the snippet's References so you can quickly locate all the places where it's used.

When you have a snippet open for editing, the righthand menu displays this References section:

Sample References section

Select View details... to open a modal showing a full list of the articles and custom content categories that reference this snippet. Articles include a badge that shows the article's publishing status:

Sample References modal

The links open the article and custom content category for editing.