Share:
ClickHelp Documentation

ClickHelp - Author, host and deliver documentation across platforms and devices!    Explore 200+ Features

When writing API Documentation or any developer documentation, technical writers need to include code samples in the content. Those samples are easier to read when the code is formatted similar to what the relevant IDE does.

In ClickHelp, you can use third-party code highlighting libraries, which are provided as client-side JavaScript files. One good example is the Highlight.js library. You can learn more about it here:  https://highlightjs.org/

In this topic, we will learn how to add and use Highlight.js in your ClickHelp documentation portal. The process contains five steps:

Four of those steps are needed only once. Let's get started!

Download Highlight.js

Highlight.js supports more than a hundred of programming languages. Most probably, you don't need all of them for your project. To minimize the JavaScript file size, you can create a custom package with only the languages you need. To do this, go to the Highligh.js download page: https://highlightjs.org/download/

On that page, enable the check boxes near the languages you need, and click the Download button below the languages list. You will get a ZIP archive with some files. You will need to extract two files from the archive:

  • highlight.pack.js - this is the JavaScript library itself, with only the languages you selected;
  • one CSS file from the "\styles" folder - this will define the colors and style of code highlighting; you can take any of the files at this stage - you can use a different one later.

So, at the end of this step, you have those two files.

Upload JavaScript and CSS Files into Your Portal

  • Log in to your ClickHelp documentation portal.
  • Open File Manager from the main menu.

  • Switch to the Styles tab and upload the CSS file using drag & drop or by clicking Browse below the files list.
     
  • Switch to the Scripts tab and upload the JS file.

  • Click Close in the File Manager dialog.

Great, we have uploaded both files and we are ready to proceed!

Add the JS and CSS Files into Your Project Settings

  • Switch to the Portal Dashboard page of your documentation portal and select your project in the list.
     
  • Click the three vertical dots button as it's shown on the screenshot below. Then click Settings.
     
  • The Basic Settings category will be opened, this is the place where we can configure project style and script files. Those files will be loaded every time some topic of that project is opened.
  • First, we will add the style file to the list of project styles by selecting the file from the combo-box.
     
  • Then we will scroll down and add the script file to the project.
     

Done, we have added the two files to our project, so they are used for the project content. It's time to move on!

Add Highlight.js Initialization to Topics

Adding the script file is not enough for the code highlighting to work. The highlighting logic needs to be called from somewhere after the topic content is loaded. The most straightforward way is to embed the required JavaScript call into the footer snippet of a project. To learn more on using snippets, read Content Snippets.

  • Click the three vertical dots button as it's shown on the screenshot below. Then click Settings

  • Go to Topic Template > Topic Master Page.
  • Add the following HTML code line without changes at Topic footer:
    <script type="text/javascript">hljs.initHighlightingOnLoad();</script>
    
    
    This is what this will look like:
     
  • Click Save Changes.

That's it - just one code line in the footer! Now, every topic of your project will automatically trigger the code highlighting logic when the topic is opened.

Write the Code Examples

Highlight.js requires the following HTML structure for the code samples:

<pre><code class="hljs javascript">
  function SampleFunction()
  {
    alert("Some alert...")
  }
</code></pre>

That is, your code sample must be wrapped with PRE and CODE tags, and the CODE tag will have the class name that matches the programming language name to use for highlighting.

When adding code samples to your topics, do the following:

  • Remember that you are pasting the content into the HTML source - some characters may be perceived as a part of the HTML markup, like angle brackets. To avoid such problems, use any online HTML escaping web site to process your code sample and replace any forbidden characters with their HTML codes.
  • Locate the place where you need to insert the code example in the topic and place the text cursor there.
  • Switch to the Insert tab of the topic editor.
     
  • Click the Insert HTML item.

  • When the Insert HTML window appears, use the above HTML snippet as a template - paste the escaped code example, and wrap it with the PRE and CODE tags.
  • Note that code highlighting does not happen in the editing mode - scripts don't run in the Design View. To see the final result, just switch to the Preview tab of the topic editor, or switch to the viewing mode by clicking Unlock & View.

You can also add the code sample via the HTML source by switching to the Source mode of the WYSIWYG editor.

This is it - now you have code highlighting enabled in your ClickHelp documentation portal. You can play with the CSS style files to choose the one you like the most. Just upload several CSS files to your portal and test them with your project one by one by adding/deleting them from the project styles list.