Provide the ability to add `additional-js` files above `book.js` in `index.html` (to support custom language highlights)

[Robert Borghese]

At the current moment, one can add additional js files to be added to the generated index.html using the book.toml configuration (issue that inspired this):

[output.html]
additional-js = ["custom.js"]

The provided js files are placed at the bottom of the index.html:

...
<script src="clipboard.min.js" type="text/javascript" charset="utf-8"></script>
<script src="highlight.js" type="text/javascript" charset="utf-8"></script>
<script src="book.js" type="text/javascript" charset="utf-8"></script>

<!-- Custom JS scripts -->
<script type="text/javascript" src="custom.js"></script>

However, I am having an issue using highlight.js's ability to add custom languages due to the placement of these custom js scripts. hljs.registerLanguage works too late by running after book.js, because by that point (from what I can gather), it has already attempted to generate a code block using my language's id. This creates an error with highlight.js since the language has not been defined, so it defaults to plain text color. Simply placing the custom.js script above the book.js script makes everything work perfectly.

This isn't that big of a deal, as I can simply modify the index.html post build, but it would be nice if I could see color while developing using serve. Especially since using mdBook to document new programming languages (I would imagine) could be a pretty big use-case due to how amazing it looks with Rust, I feel adding a solution to this problem would be nice.

An alternative solution could be the ability to provide a custom version of highlight.js? Maybe this is already possible, but I haven't been able to find it. That would allow one to simply append the extra language registers to the bottom of the file and use it over the one mdBook provides.

[Tobbe]

If you just want to support a different set of languages for highlight.js, this feature is not required. Inspired by #1678 (comment), you can do the following:

1. Configure and download a custom version of highlight.js from https://highlightjs.org/download/ (see the "Custom package" section
2. Unzip and copy/move the included highlight.min.js to theme/highlight.js

[Robert Borghese]

Ahhh, don't know how I missed that theme folder feature. I think that provides the functionality I desired. Thanks!

[Samer]

Following suggestions in this thread leads to highlight.js warning to the console that it cannot find the language, but highlighting works.

1. I copied highlight.min.js to theme/highlight.js
2. I registered the custom language in an additional-js file (configured in book.toml)
3. I had to add hljs.initHighlightingOnLoad(); at the end of the additional-js file to reload highlight.js

highlighting works, but because highlight.js runs before applying the dirty hack.

How to solve this elegantly?

[Tobbe]

Following suggestions in this thread leads to highlight.js warning to the console that it cannot find the language, but highlighting works.

1. I copied highlight.min.js to theme/highlight.js
2. I registered the custom language in an additional-js file (configured in book.toml)
3. I had to add hljs.initHighlightingOnLoad(); at the end of the additional-js file to reload highlight.js

highlighting works, but because highlight.js runs before applying the dirty hack.

How to solve this elegantly?

I guess the difference between your and my situation is that you want to register a custom language while I only needed to enable one of the languages supported by upstream highlight.js, i.e. install a custom package. The steps I described only work like this for languages which are supported by the upstream highlight.js because it is easy to download a custom package from the highlight.js website which contains a highlight.min.js which already sets everything up properly.

You could try to incorporate your code into your custom highlight.js but I do not know how hard this would be. And this would definitely not be a clean solution.