Highlightjs Hugo - Advanced syntax highlighting for Hugo templates using Highlight.js

Every time a read a Discourse topic I wondered about the random look of highlighted template code. Highlight.js has no support for Go and Hugo templates.

But it could look so nice

Introduction

To improve that the first was to implement standard Highlight.js plugins. I digged in Highlight.JS and came up with two syntax modules for text and html templates.

Our keyword tables are huge cause we support to style Hugo functions as built-in. Both plugins hugo-html and hugo-text are 9.5KB minified. We also provide patched plugins that includes both variants but only define the keyword tables once. The result is an also 9.5KB plugin (+300 bytes).

Bringing that to Discourse was a different story. Our theme plugin supports both language variants also with 10 KB in size.

Disclaimer

Keep in mind that we are on a 0.0.x version for now.

Expect things to change between tags -- also with breaking changes or even incompatible ways.

All we push to our dist folder is work in progress. Also we try to only push working changes, there might be something we missed out and it will break.

Provided plugins

Here's the list of our provided plugins. browse the folders to dig into details.

Standard Highlight.js plugins

These can be used as any other extra plugins. You may include that in your custom Hhighlight.js build.

• hugo-html

  Highlight template code using our plugin and style surrounding HTML using [Highligh.js][] standard xml

• hugo-text

  Highlight template code using our plugin and just dump out surrounding text unstyled.

• hugo-html

  highlight template code using our plugin and style surrounding HTML using [Highligh.js][] standard xml This plugin defines hugo-html and hugo-text as aliases. to style hugo-textwithout highlighting you need to apply CSS rules. Somthing like:

  /* change these to match your 'standard' for non-highlighted code */
  code.hugo-text span.language-xml {
    text-decoration: none;
  }
  code.hugo-text span.language-xml * {
    font-style: none;
    font-weight: normal;
    background: darkgray;
    color: #444;
  }

Downsized special Highlight.js plugins

These have to be used as is. They are generated and patched for smaller size. There's no aliasing but it's two languages, no CSS tricks neccessary.

• hugo-highlightjs-plugin

  downsized variant as a standalone plugin -- supporting hugo_html and hugo-text.

• hugo-discourse-plugin

  downsized variant bundled as Discourse theme plugin -- supporting hugo_html and hugo-text.

Download

The module has not been published to any CDN right now. You will have to clone or download the stuff you need.

• latest version from the [dist folder][dist/]
• a released package from our releases page.

Usage

Please refer to the respective modules README.md.

Build your own

The two language modules work with the standard Highlight.js custom build system. Check out their docs for details.bundling these (or just one) and other languages you need.

The other two are patched variants of the both above. We generate these based on a standard build results. The build process works, but it heavily depends on undocumented internals.

Contributing and Issues

I would never say never, but currently it's our working playground so it's nothing where one could do stable contributions right now.

If you found a bug, have a question or an idea, please use the Issue tracker.

Hugo as a generator

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

• fetch function names from hugoDocs pages
• generate keyword tables for the plugins
• generate plugin javascript code
• generate supplementary files needed for the Highlight.js build system
• generate tests
• generate README

Take it as a hacky showcase how to use Hugo to generate any files from content templates.

If you want to dig in, you'll find the site source at build\hugen

License

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

Author & Maintainer

• Irkode [email protected]

Links

• highlightjs-hugo : The main repository with additional grammars and plugins. Have a look
• 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