Custom Language Syntax Highlighting

[brendanzab]

I'm currently using mdBook for the documentation of my Pikelet language. I want to be able to add my own, custom language to highlight.js.

What would be the best way to do this? At the moment the languages seem to be minified into the highlight.js code. Will I need to provide a custom rebuild of highlight.js instead? Would we be able to have support for custom languages in the future?

[brendanzab]

cc. @Marwes - I know you're starting to use mdBook for Gluon as well.

[Marwes]

I tried to use highlight.js to get syntax highlighting on http://gluon-lang.org/try/ a couple of weeks ago by dynamically adding the necessary definitions. Unfortunately all the distributions of highlight.js are minified so it weren't feasible. Not sure how mdbook does it now, but to get highlighting for custom languages I think a full custom build of highlight.js may be needed.

[brendanzab]

Yeah, I'm thinking that it might require you to use a custom fork, which is a little disappointing. Might have to include it as a submodule. 😭

[brendanzab]

I'm guessing this would also be a problem for LALRPOP too.

[Michael-F-Bryan]

I've actually wanted this in the past when documenting some legacy code at work, but I'm not sure how we'd actually do it. A while back we threw around the idea of using a build system for our frontend code, but decided against it (@mattico, should we revisit this?).

---

Not sure how mdbook does it now, but to get highlighting for custom languages I think a full custom build of highlight.js may be needed.

Looking at the highlight JS README, it seems like you can just include a link to your pre-compiled language and it should be picked up automatically.

The CDN-hosted package doesn't have all the languages. Otherwise it'd be too big. If you don't see the language you need in the "Common" section, it can be added manually:

<script src="//cdnjs.cloudflare.com/ajax/libs/highlight.js/9.4.0/languages/go.min.js"></script>

[brendanzab]

Hmm, maybe if you built it with the node tools/build.js -t cdn option it would give you the separate minified language files… 🤔 - would still need to include a fork of the repo as a submodule though, it doesn't really seem set up all that well to be extensible.

For now I've gone with the hacky approach! See brendanzab/pikelet#21.

[Michael-F-Bryan]

It's annoying, but that ci/build-highlight-js script of yours is probably going to be the best solution. Unless highlight.js publish their tools/build.js script to NPM so we can generate custom highlighting packs locally.

[brendanzab]

I mean, if we really wanted to head down the rabbit hole we could always fork highlight.js and update it to modern JS 😱

[XVilka]

What about using https://github.com/trishume/syntect instead? And don't force the readers to run more JS than is necessary.

[raviqqe]

I found a quick and dirty way. We can just reload highlight.js again after language registration. pen-lang/pen#395

[Atreyagaurav]

@raviqqe Thank you for sharing your fix. This was the only thing I was able to find that worked for custom highlight.

But since that is not mentioned in mdbook or highlight.js, isn't there a high chance that the custom highlight code will break when the highlight.js version change happens? Do you think we should make an issue upstream so that they don't change the API too much, or give a way to register custom languages like this?