Advanced syntax highlighting for HuGo templates

Did you ever wonder why hugo templates seem to be randomly highlighted in Discourse. The answer is dead simple: Discourse uses Highlight.js for syntax highlighting which does not support Go and Hugo templates.

It could look so nice

Introduction

To achieve that, we implemented

• Highlight.js grammars
• Discourse theme components.

Both supporting the full set of Hugo’s template keywords, built-in functions and aliases.

Grab plugins from our Releases page or read more in the Documentation.

Provided plugins

Each module is available in two variants:

• HTML - Uses the standard XML grammar for highlighting surrounding Html code.

• TEXT - This will keep surrounding text unstyled.

Download

Ready to use modules are available as artifacts on our Releases Page.

Usage and documentation

Follow the instructions included in each artifact’s README.md. To read before downloading, check out our Documentation

Build

For standard use cases see Download above.

Custom Highlight.js build

To build your own customized Highlight.js installation grab the highlightjs-hugo artifact and place it in the extra folder of your Highlight.js clone. Build that just as any other Highlight.js grammar or a customized build.

With a customized build, we add the Hugo keyword tables to the Highlight.js core so these will get packed only once. The result is an unpacked saving of 10KB for the final engine.

Build our sources

We build our stuff using custom scripts; a combination of powershell, node and Hugo. These scripts work fine for us. May work for you but no guarantee. Listed Version numbers are the on we use, might work with others.

We are on Windows 11 Professional. Could be working for unix like systems, but that is untested. Have a look at our CI workflow script for the bare commands on a GitHub Ubuntu runner.

• Components that have to be there

  • Hugo - 159.1+
  • Go 1.26.1+
  • Node 22.14.0 (highlight.js requirement)

• Components automatically provided by the build scripts

  • Highlight.js 11.11.1
  • hugoDocs (as a hugo module)

• Build all

  git clone https://github.com/irkode/highlightjs-hugo/ highlightjs-hugo
  set-location highlightjs-hugo
  .\build.ps1 -Verbose
  

• grab the results from release folder

The Powershell script provides a Get-Help.

Be aware that that is in no way a general purpose build script. It just provides shorthands for our local development process. For special Highlight.js build configurations you will need to directly use the standard Node and npm scripts.

Contributing and Issues

Never say never, but currently it’s our working playground, nothing where one could do stable contributions right now.

Use the Issue tracker for reporting bugs, asking question or raise ideas.

Hugo as a generator

Hugo is a powerful templating engine, and we utilize it to generate and assemble our grammars and discourse plugins.

• fetch function and aliases from hugoDocs

• generate keyword tables for the plugins

• generate the hugo-lib module (grammar and keyword Javascript module)

• generate Javascript code and supplementary files

• create READMEs

• generate tests

• create source structure for our release assets

• generate Discourse plugins based on the build results

• and ofc for the standard use case - the documentation pages

Take it as a nifty showcase to use Hugo as a generic templating and publishing engine – beyond web sites.

If you want to dig in, you can find that here

License

This package is released under the MIT License. See LICENSE file for details.

Author & Maintainer

• Irkode irkode@rikode.de

Links

• highlightjs-hugo : The main repository with additional grammars and plugins. Have a look
• Documentation : All about Highlight 4 Hugo
• Highlight.js : The Internet’s favorite JavaScript syntax highlighter supporting Node.js and the web
• Hugo : The world’s fastest framework for building websites
• Go HTML template : Go’s html template package
• Go TEXT template : Go’s text template package