Install a new language for Highlight.JS on a hosted discourse

Warning: This is a crazy hack!

I’m just sharing because (1) it maybe helpful to someone and (2) hopefully you will teach me a better way.

I hired a “Discourse as a Service” instance, so I don’t control the source code, nor can install plugins.

I wanted my forum to highlight the Beancount language.

First I wrote the syntax definition and sent it to upstream, but I didn’t want to wait for a Highlight.JS and Discourse release, and for my host to upgrade my instance.

Then I went to Admin -> Customize -> CSS/HTML -> </head> and added this hack to inject the Beancount language into Discourse’s Highlight.JS.

// Crazy hack to install Beancount syntax.
function waitForHighlightJS() {
    if(typeof hljs !== "undefined"){
        console.debug('HighlightJS ready... installing Beancount syntax.');
        // Install Beancount syntax.
        //Got this building highlight.js with: node tools/build.js -t cdn
        hljs.registerLanguage("beancount",function(e){var c="[A-Z][A-Za-z0-9-]*",a="[0-9]{4}[-|/][0-9]{2}[-|/][0-9]{2}",b="(balance|commodity|custom|document|event|note|open|pad|price|query)",t={cN:"literal",b:/([\-|\+]?)([\d]+[\.]?[\d]*)/,r:0},n={cN:"string",b:'"',e:'"',r:0,c:[e.BE]},s={cN:"name",b:"\\{",e:"\\}",c:[{cN:"literal",b:a},t,n,{cN:"subst",b:"[A-Z][A-Z0-9'._-]{0,22}[A-Z0-9]"}]};return{aliases:["beancount","bean","ledger"],c:[{cN:"built_in",b:"^(include|option|plugin|popmeta|poptag|pushmeta|pushtag)",r:0},{b:"^"+a+"\\s+"+b,rB:!0,r:10,c:[{cN:"type",b:a,e:/\s+/,eE:!0},{cN:"keyword",b:b}]},{b:"^"+a+"\\s+.\\s",rB:!0,r:10,c:[{cN:"type",b:a,e:"\\s+",eE:!0},{cN:"variable",b:".",endsParent:!0}]},e.C(";","$"),{cN:"meta",b:/^\s{2,}[a-z][A-Za-z0-9\-_]+:/},s,{cN:"name",b:"@"},{cN:"type",b:c+":",r:0,c:[{cN:"subst",b:c+"(:"+c+")?"}]},{cN:"section",b:/^\*\s+?.*/},{cN:"link",b:/\^[A-Za-z0-9\-_\/.]+/},{cN:["emphasis"],b:/#[A-Za-z0-9\-_\/.]+/},n,t]}});
        // Realod syntax for codeblocks.
        $("pre code[class]").each(function(i, e){
        console.debug('HighlightJS updated. Everything should look good.');
        console.debug('HighlightJS not ready yet.')
        setTimeout(waitForHighlightJS, 250);
setTimeout(waitForHighlightJS, 250);

Works for me. If you have any suggestions I would be glad to hear. Mainly if you know how it can be done without the setTimeout.



Ideally I would prefer simply to upgrade highlight and make the brand new languages an option. This hack is very very very hacky.


Me too! :smiley: Unfortunately this is not under my control.

I was wandering… Discourse’s HLJS plugin already allow some customization on init. Maybe it would be useful to not limit this customization to languages. Maybe passing an object that would be merged with the config object could do this trick and more.

However, I don’t think ppl need this very much. I’ll stick with my hack until (1) HLJS is released and (2) Discourse updated.

How do you indiciate which syntax highlighter to use when you insert code into a post?

AFAIK HighlightJS uses the first language that match.

However, every language has a “registration name”.


So if you want to explicitly define the language, inform the name after the triple ```.

``` python
Some code

Thanks - I had seen the registration name but it wasn’t clear how to specify that name when posting code.

I’ve just added a hook to our HighlightJS code so now you can use the plugin API to add a custom language for Highlight.JS.

Example (using the beancount language from the OP):

<script type="text/discourse-plugin" version="0.8.27">
  // add Beancount language to HighlightJS
  // Must build highlight.js with "node tools/build.js -t cdn"
  const beancountLang = function(e){var c="[A-Z][A-Za-z0-9-]*",a="[0-9]{4}[-|/][0-9]{2}[-|/][0-9]{2}",b="(balance|commodity|custom|document|event|note|open|pad|price|query)",t={cN:"literal",b:/([\-|\+]?)([\d]+[\.]?[\d]*)/,r:0},n={cN:"string",b:'"',e:'"',r:0,c:[e.BE]},s={cN:"name",b:"\\{",e:"\\}",c:[{cN:"literal",b:a},t,n,{cN:"subst",b:"[A-Z][A-Z0-9'._-]{0,22}[A-Z0-9]"}]};return{aliases:["beancount","bean","ledger"],c:[{cN:"built_in",b:"^(include|option|plugin|popmeta|poptag|pushmeta|pushtag)",r:0},{b:"^"+a+"\\s+"+b,rB:!0,r:10,c:[{cN:"type",b:a,e:/\s+/,eE:!0},{cN:"keyword",b:b}]},{b:"^"+a+"\\s+.\\s",rB:!0,r:10,c:[{cN:"type",b:a,e:"\\s+",eE:!0},{cN:"variable",b:".",endsParent:!0}]},e.C(";","$"),{cN:"meta",b:/^\s{2,}[a-z][A-Za-z0-9\-_]+:/},s,{cN:"name",b:"@"},{cN:"type",b:c+":",r:0,c:[{cN:"subst",b:c+"(:"+c+")?"}]},{cN:"section",b:/^\*\s+?.*/},{cN:"link",b:/\^[A-Za-z0-9\-_\/.]+/},{cN:["emphasis"],b:/#[A-Za-z0-9\-_\/.]+/},n,t]}}
  api.registerHighlightJSLanguage("beancount", beancountLang);

I came across this article while looking into how to add support for Chapel syntax highlighting on our Chapel Language Discourse site using a third-party highlight.js extension for Chapel.

In @pmusaraj’s example above, I understand how I would update it to replace beancount with chapel. But I’m sufficiently new to Discourse that it’s not clear to me what I’d then do with the script block to enable it for our Discourse site. Could someone provide additional pointers for noobs like me?


You’d create a new theme component under Admin > Customize > Themes, then paste that code in the </head> section. From there modify and tweak as needed.

More information:

Beginner’s guide to using Discourse Themes
Developer’s guide to Discourse Themes


Thanks @justin , this is exactly what I was missing (and I would’ve never gotten there myself before giving up)! Our Discourse now renders Chapel properly (or, at least, as properly as my highlight.js script does, which is a great start…).

A few things that remained unclear to me even after some trial and error:

  1. Is it correct that the language tag on a triply quoted block, like:


    is only matched against the (first) argument to the registerHighlightJSLanguage() call? Or is it also matched against the aliases defined within the language highlighter’s highlight.js-based definition? If the former, is there any reason to avoid registering a language definition multiple times under various aliases to support multiple forms (say ```chapel vs. ```chpl)?

  2. Is it correct that the language must be added to the site’s highlighted languages setting as well in order for the code blocks to be recognized? And that this name must match the string passed to registerHighlightJSLanguage()?

Thanks again.

I created new syntax highlighting for Jai: GitHub - Jai-Community/discourse-highlightjs-jai: Discourse theme component to highlight Jai syntax

However, when I install it and enter the theme preview mode, and then create a new topic and add some code, like this:

#run {}

… it does detect the language (see the class attribute), but it does not parse anything:

<pre><code class="lang-jai hljs">#run {}

whereas running the same language definition with a local setup does highlight jai syntax successfully:

Try yourself by opening _dev/test-syntax-highlight.html in your browser.


Turns out Discourse is using the previous major version of Highlight.js, which is incompatible with the current one. So I had to fix my language definition, and it worked like a charm.

For anyone interested in a complete Theme Component repo example for syntax highlighting, here it is: