How to Enable Syntax Highlighting in Code Examples - Fluid Topics

Business need

Code samples in technical documentation are easier to read if syntax is correctly highlighted.

Overview of the solution

Automatically highlighting codeblocks on Fluid Topics depends on the publication format.

PORTAL_ADMIN and ADMIN users can style:

Markdown codeblocks with CSS.
Codeblocks in other formats with the HighlightJS library.

Adding custom JavaScript code requires technical skills, and remains under the responsibility of the customer. Antidot does not accept responsibility for any service malfunction related to JavaScript customization.

Procedure

Markdown

Fluid Topics automatically applies classes to distinct sections of code within fenced code blocks in Markdown content.

Users can then style the classes to match the look of their portal.

Copy the following codeblock:

/* Color variables */
@hl-primary-color: #a31515;
@hl-secondary-color: #0000ff;
@hl-background: #ffffff;
@hl-comments: #008000;

.highlight .hll { background-color: @hl-background }
.highlight { background: @hl-background; }
.highlight .c { color: @hl-comments } /* Comment */
.highlight .k { color: @hl-secondary-color } /* Keyword */
.highlight .ch { color: @hl-comments } /* Comment.Hashbang */
.highlight .cm { color: @hl-comments } /* Comment.Multiline */
.highlight .cp { color: @hl-secondary-color } /* Comment.Preproc */
.highlight .cpf { color: @hl-comments } /* Comment.PreprocFile */
.highlight .c1 { color: @hl-comments } /* Comment.Single */
.highlight .cs { color: @hl-comments } /* Comment.Special */
.highlight .ge { font-style: italic } /* Generic.Emph */
.highlight .gh { font-weight: bold } /* Generic.Heading */
.highlight .gp { font-weight: bold } /* Generic.Prompt */
.highlight .gs { font-weight: bold } /* Generic.Strong */
.highlight .gu { font-weight: bold } /* Generic.Subheading */
.highlight .kc { color: @hl-secondary-color } /* Keyword.Constant */
.highlight .kd { color: @hl-secondary-color } /* Keyword.Declaration */
.highlight .kn { color: @hl-secondary-color } /* Keyword.Namespace */
.highlight .kp { color: @hl-secondary-color } /* Keyword.Pseudo */
.highlight .kr { color: @hl-secondary-color } /* Keyword.Reserved */
.highlight .kt { color: #2b91af } /* Keyword.Type */
.highlight .s { color: #a31515 } /* Literal.String */
.highlight .nc { color: #2b91af } /* Name.Class */
.highlight .ow { color: @hl-secondary-color } /* Operator.Word */
.highlight .sa { color: @hl-primary-color } /* Literal.String.Affix */
.highlight .sb { color: @hl-primary-color } /* Literal.String.Backtick */
.highlight .sc { color: @hl-primary-color } /* Literal.String.Char */
.highlight .dl { color: @hl-primary-color } /* Literal.String.Delimiter */
.highlight .sd { color: @hl-primary-color } /* Literal.String.Doc */
.highlight .s2 { color: @hl-primary-color } /* Literal.String.Double */
.highlight .se { color: @hl-primary-color } /* Literal.String.Escape */
.highlight .sh { color: @hl-primary-color } /* Literal.String.Heredoc */
.highlight .si { color: @hl-primary-color } /* Literal.String.Interpol */
.highlight .sx { color: @hl-primary-color } /* Literal.String.Other */
.highlight .sr { color: @hl-primary-color } /* Literal.String.Regex */
.highlight .s1 { color: @hl-primary-color } /* Literal.String.Single */
.highlight .ss { color: @hl-primary-color } /* Literal.String.Symbol */
.highlight .mi { color: @tertiary } /* Numbers */

Other predefined styles are available in the pygments-css GitHub repository.

Go to Administration, Portal, and open the Content styles menu.
In the Topic Styles field, paste the CSS styles.
Adapt the styles to the portal's appearance.
Select Save.

In a Markdown file, add a fenced codeblock, and specify a language.

For example:

```json
{
  "message": "This is my feedback message",
  "from": "jdoe@example.com"
}
```

Publish the document.

The resulting codeblock is the following:

{
  "message": "This is my feedback message",
  "from": "jdoe@example.com"
}

JavaScript

Highlighting code is possible by using the HighlightJS library.

Copy the following codeblock:

const initHighlightJS = () => {
  // Highlight JS
  let hljsScriptLoaded = false;
  document.addEventListener('ft:reader:topicsloaded', () => {
    if (!hljsScriptLoaded) {
      var hljsScript = document.createElement('script');
      hljsScript.src = 'https://cdnjs.cloudflare.com/ajax/libs/highlight.js/11.8.0/highlight.min.js';
      hljsScript.async = true;
      document.head.appendChild(hljsScript);

      var hljsStyle = document.createElement('link');
      hljsStyle.href = 'https://cdnjs.cloudflare.com/ajax/libs/highlight.js/11.8.0/styles/default.min.css';
      hljsStyle.rel = "stylesheet";
      document.head.appendChild(hljsStyle);
      hljsScriptLoaded = true;
    }

    document.querySelectorAll('pre.codeblock p, pre.codeblock, div.highlight pre').forEach((block) => {
      hljs.highlightBlock(block);
    });
  });
}

initHighlightJS();

The purpose of the document.querySelectorAll method is to match the HTML elements, IDs, and classes of codeblocks to highlight. Those elements, IDs, and classes may differ depending on the publication format. PORTAL_ADMIN and ADMIN users must adapt the content of document.querySelectorAll to match the codeblocks on a portal.

Go to Administration, Portal, and open the Custom JavaScript menu.
In the Topic Styles field, paste the JavaScript code.
Select Save.

Code blocks are now correctly highlighted.

Example

The HighlightJS library offers a demo where users can insert code, and see how the library would highlight it.