Hugo has its own syntax highlighting using Chroma, but I wanted to keep things consistent with typical AsciiDoc. The use of AsciiDoc markup in Hugo depends on AsciiDoctor, which supports a number of syntax highlighters:

  • highlight.js

  • CodeRay

  • Pygments

  • Rouge

All but highlight.js are build-time highlighters, which apply the highlighting when the site is generated. I chose Rouge because it supports a large number of languages, unlike CodeRay, and does not require Python, unlike Pygments.

There are two ways to implement Rouge:

  • Using a Rouge theme

  • Using a CSS file

In either case, you need to first install Rouge:

  1. Open a terminal in the root folder of your Hugo project and run the command gem install rouge.

  2. In the root folder, open the gemfile and add an entry for Rouge:

    gemfile
    1
2
3

    source 'https://rubygems.org'
gem 'asciidoctor'
gem 'rouge'

  3. Update the gemfile.lock file by running bundle. The file should then look something like this:

    gemfile.lock
    GEM
  remote: https://rubygems.org/
  specs:
    asciidoctor (2.0.17)
    rouge (3.28.0)

PLATFORMS
  x64-mingw32

DEPENDENCIES
  asciidoctor
  rouge

BUNDLED WITH
   2.2.33

Using a Rouge theme

This is the simpler approach:

  • Add the following entry to the /<root-folder>/config/_default/config.toml file:

    [markup.asciidocExt]
[markup.asciidocExt.attributes]
source-highlighter = "rouge" (1)
rouge-style = "base16.solarized" (2)
rouge-css = "style" (3)

    1. Activates the Rouge highlighter. This is equivalent to adding :source-highlighter: rouge to the top of each AsciiDoc file that you create in your Hugo content folders.

    2. This is the name of the theme you want to use. Use the Rouge Theme Preview Page to choose a style.

    3. This setting tells Rouge to use the specified theme. The default value is class.

Using CSS

This approach is a little more complicated, but it allows for tweaking the CSS to suit your site:

  1. Download the Rouge theme that you want to use.

  2. Run rougify style yourstyle > yourstyle.css to output the CSS to a text file.

  3. If your Hugo theme uses SCSS, use CSS to SCSS Converter to convert the file.

  4. Do one of the following:

    • Either:

      1. Add the .css or .scss file to the relevant templates folder in your Hugo theme. For example, I added my file to <root-folder>/themes/airspace-hugo/assets/scss/templates/

      2. Add an @import rule to the end of your style.scss file. For example, I added @import 'github.scss' to the end of <root-folder>/themes/airspace-hugo/assets/scss/style.scss

    • Or:

      1. Place the CSS into the default custom.scss (or custom.css) file below the top-level assets folder. In my case this was /<root-folder>/assets/scss/ustom.scss.

        The styles should now be included automatically.

  5. Add the following entry to the /<root-folder>/config/_default/config.toml file:

    [markup.asciidocExt]
[markup.asciidocExt.attributes]
source-highlighter = "rouge"
rouge-css = "class" (1)

    1. This line can be left out because class is the default setting.

Enabling line highlighting

Enabling line highlighting involves adding two CSS styles (provided in the AsciiDoctor documentation):

  • Copy the following into the default custom.scss (or custom.css) file below the top-level assets folder. In my case this was /<root-folder>/assets/scss/custom.scss.

    custom.scss
    pre.rouge .hll {
  background-color: #ffc;
}

pre.rouge .hll * {
  background-color: initial;
}

    Alternatively, if you added a CSS file for the Rouge syntax highlighting, add these styles to the end of that file.

Now you can highlight lines in the code:

[source%linenums,javascript,highlight=7..8]
----
function search(term)
  {
    var results = index.search(term);

    var target = document.querySelector("main");

    while (target.firstChild)
      target.removeChild(target.firstChild);
----

This results in:

1
2
3
4
5
6
7
8

function search(term)
  {
    var results = index.search(term);

    var target = document.querySelector("main");

    while (target.firstChild)
      target.removeChild(target.firstChild);