mdBook icon indicating copy to clipboard operation
mdBook copied to clipboard

Add documentation on how to add a highlight.js for additional syntax highlighting support

Open DrTobe opened this issue 2 years ago • 4 comments

This adds a few lines on how a custom version of highlight.js can be obtained and made available to mdbook. With that information available, all issues about adding support for a specific language should be safe to be closed because mdbook in its default setup probably does not need to support every possible language.

I have seen that there are ongoing efforts to move away from highlight.js but I guess this information may nevertheless be useful in the meantime.

DrTobe avatar Jan 02 '23 14:01 DrTobe

Would be good to merge this!

max-sixty avatar May 07 '23 22:05 max-sixty

Unfortunately I don't think just using the highlight.js website will completely work. mdBook is incompatible with newer versions of highlight.js (such as #1622). https://github.com/rust-lang/mdBook/blob/master/CONTRIBUTING.md#updating-highlightjs contains some instructions for building it from source, where you can check out a version from the 10.x series.

ehuss avatar May 08 '23 01:05 ehuss

I just proposed to add this because it took me quite some time to figure this out and it solved our specific problem. So I still think some kind of documentation like this might be valuable but you are right that we should not include it like that if it is not 100% correct. So what specific approach do you propose?

DrTobe avatar May 08 '23 12:05 DrTobe

I'm not sure, but one suggestion might be to copy the first four steps from the contributing guide to this page instead of recommending going to the website.

ehuss avatar May 08 '23 16:05 ehuss