The :highlight filter highlights code syntax.

Enable filter

The :highlight filter require a highlighting module.
Currently is supported the prismjs module, the highlight.js will be added later.

Why is prismjs supported in the first place?

  • the prismjs support 291 languages, the highlight.js support only 197 languages
  • the prismjs support the pug "from box", but the highlight.js require an additional "third-party" plugin for pug
  • the prismjs package size is only 2 MB, the highlight.js is 3.7 MB
By usage the :highlight filter install the npm module:
npm install -D prismjs

Defaults, the filter is disabled. If this filter is used, it must be enabled in webpack.config.js.

Use the Pug loader options in the webpack config:
{
  test: /.pug$/,
  loader: '@webdiscus/pug-loader',
  options: {
    // enable embedded filters
    embedFilters: {
      // enable :highlight filter
      highlight: {
        verbose: true,
        use: 'prismjs',
      },
    },
  },
},

The filter options:

  • verbose {boolean} Enable output process info in console. Use it in development mode only. Defaults is false.
  • use {string} The name of a highlighting npm module. The module must be installed. Currently, is supported the prismjs only.

Tipps

Inline nested tags

Pug has inline syntax. Nested tags can be inlined with : at the end of each previous inline element.
For example, following nested pre and code tags:
pre.language-pug
  code
    p Hello Pug!
can be inlined:
pre.language-pug: code
  p Hello Pug!

Use mixins

You can create the mixin code for the pre and code tags:
mixin code
  pre.language-: code
    block
Then use the mixin and filter easily in same line:
+code: :highlight(js)
  const arr = [1, 2, 'banana'];
Result:
const arr = [1, 2, 'banana'];

Highlight a file

For a large code example, it is recommended to save that code in a separate file and then include it. 
+code: include:highlight(pug) code-example.pug

Highlight an inline code

Use the nested inline filters: #[:code:highlight(lang) ...].

Note: For usage the [ and ] chars in pug inline filter, the chars must be encoded with their corresponding HTML entities [ and ]

For example:

Pug: #[:code:highlight(js) obj = { arr: [1, 2, 'banana'] };]
Result: const obj = { arr: [1, 2, 'banana'] };

Pug: #[:code:highlight(html) <div class="container">content</div>]
Result: <div class="container">content</div>

Highlight a code block

To highlight the code syntax of a language use the :highlight(lang) filter, where the lang is a language supported by a highlight module.
Note: A highlight module may require a specific class name by the <pre> tag.
E.g. the prismjs themes needs <pre class="language-"> for a background color.

For example, highlight the html code:
pre.language-: code: :highlight(html)
  <!-- Comment -->
  <div class="container">
    <p>Paragraph</p>
    <script>
      const body = document.querySelector("body");
    </script>
  </div>
Result:
<!-- Comment -->
<div class="container">
  <p>Paragraph</p>
  <script>
    const body = document.querySelector("body");
  </script>
</div>

Highlight a code in markdown

The embedded :markdown filter can self highlight code blocks.
How to enable and configure this filter see the :markdown page.
Usage example:
:markdown
  _HTML_
  ```html
  <!-- Comment -->
  <div class="container">
    <p>Paragraph</p>
  </div>
  ```

  _JavaScript_
  ```js
  const arr = [1, 2, 'banana'];
  ```
Result:

HTML

<!-- Comment -->
<div class="container">
  <p>Paragraph</p>
</div>

JavaScript

const arr = [1, 2, 'banana'];

⚠️ Old way (not recommended!)

Usage of the jstransformer-markdown-it npm module as :markdown-it filter is not recommended. This filter is no longer maintained and contains an outdated version of markdown-it module with security vulnerabilities.

To highlight a markdown use the nested filters :highlight:markdown-it. All code blocks in markdown will be automatically highlighted by a language defined at a code block.

Usage example:
:highlight:markdown-it
  ```html
  <p>Paragraph</p>
  ```

  ```js
  const arr = [1, 2, 'banana'];
  ```