Allow overriding of existing JS dependencies like prism

[jugeeya]

Doctave comes prepackaged with a version of prism that has a subset of languages for highlighting in code blocks. If we want to change the version of prism used, all we'd have to do is edit the prism.js file. (FWIW, I was interested in YAML and BASH highlighting). I'd expect if I:

• Add the custom prism.js file I wanted in docs/_include/assets
• Running doctave serve should reflect the change
• Running doctave build --release should reflect the change: the file should be copied to site/assets/prism.js

But neither of the above occurs.

This may be as simple as allowing any file in docs/_include/assets to be copied over at the latest possible step.

i.e., switching these two lines: https://github.com/Doctave/doctave/blob/4531be88b1d11eb68ffc6532f54cf2cbf63f4a53/src/site_generator.rs#L51-L52

[begleynk]

Thanks for reporting this. I'm a bit torn about this.

It doesn't sound unreasonable to be able to override the prism version, but it does feel like it's reaching a bit into the implementation details of Doctave. I'd really like to just have all language syntaxes available already so this is not a problem. The issue with that is the bundle size - each new language adds between ~0.5kb and ~6kb to the bundle, which has to be served on every request (modulo caching etc).

You can play around with the bundle here: https://prismjs.com/download.html

The currently supported languages are:

c, clike, clojure, cpp, csharp, css, diff, docker, elixir, elm, erb, erlang,
go, graphql, haskell, java, javascript, jsx, julia, lua, markup, markup-templating,
objectivec, perl, php, r, ruby, rust, sql, swift, toml

I guess there are a few options here:

• Just add the 2 languages into the included bundle (adds ~6kb)
  • Does not handle the general case.
  • What about the next language that gets asked about?
• Do what you suggest and allow overriding the library
  • I feel this goes a bit against the ethos of "batteries included" and is reaching into the implementation details of Doctave
• Figure out a way where we could only include the languages that are actually used on the page (?)
  • This would be the most powerful solution but also the most complicated

Perhaps there's a fourth option?

[begleynk]

Did a bit of reading and Prism does support an autoloading feature that lazily loads language definitions as needed: https://prismjs.com/plugins/autoloader/

This could be worth looking into.

[begleynk]

I'm going to close this issue in favor of #24. I don't think Doctave should allow overriding the JS dependencies, but language support should be expanded.