search

rust-lang / mdBook

Create book from markdown files. Like Gitbook but implemented in Rust
https://rust-lang.github.io/mdBook/
Mozilla Public License 2.0
18.04k stars 1.63k forks source link

Custom Language Syntax Highlighting #657

Open brendanzab opened 6 years ago

brendanzab commented 6 years ago

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 commented 6 years ago

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

Marwes commented 6 years ago

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 commented 6 years ago

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 commented 6 years ago

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

Michael-F-Bryan commented 6 years ago

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 commented 6 years ago

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 commented 6 years ago

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 commented 6 years ago

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 commented 5 years ago

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

raviqqe commented 3 years ago

I found a quick and dirty way. We can just reload highlight.js again after language registration. https://github.com/pen-lang/pen/pull/395

Atreyagaurav commented 3 weeks ago

@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?