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.Library > Snippets menu option
2. Click the  + Create New Snippet button.
   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. Sample completed snippet
6. For code-based snippets, click 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, click the Create button. Click the Create button in the upper right

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, you can use the Add Snippet button to add a snippet: 

This will open a pop-up where you can search for your snippet. Type the name and 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. Once you're sure you've selected the correct snippet, click Insert Snippet.

You should now see your merge code value in the article, like this:

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:

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

Within the Snippet Library, you can:

1. Create new snippets
2. Search for existing snippets using words in the snippet title and description
3. Click on any snippet to open it in edit mode
4. Delete a snippet by clicking the X 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

When you're viewing a snippet in the editor, you'll see a References section in the lower right:

These references capture articles or custom content categories that you've added the snippet merge code to, to help you audit where the snippet is used. These references are generated when you save an article or custom content category with a snippet's merge code in it somewhere.

You can click the View details... link to open a pop-up showing a full list of the articles and custom content categories that reference this snippet:

Sample snippet references pop-up