Update download page URL to match selected languages

[tammersaleh]

Upgrading the library is difficult when we've selected extra languages in the download page, as there's no good way of downloading the same bundle in the future.

Prism.js solves this by updating the URL to match the selected checkboxes, and embedding that URL in the resulting download as a comment. See https://prismjs.com/download.html#themes=prism-okaidia&languages=markup+css+clike+javascript, which includes markup, css, clike, and javascript. Having such a feature on our downloads page would be really wonderful.

Similar to highlightjs/highlight.js#1035

[tammersaleh]

Looks like this is identical to highlightjs/highlight.js#1109. Now that the website is OSS'd, can we revisit?

[joshgoebel]

We're currently working on a new static website and what to do about handling downloads is an open question. Thanks for raising this question again though. It's worth considering.

CC @allejo

[allejo]

So glad someone brought this up! What's your workflow like @tammersaleh? Josh and I have been debating on how to handle custom builds from the website.

1. Are you manually visiting the website and downloading a new JS bundle?
2. Are you making a cURL request to download the bundle?
3. None of the above. What are you doing instead?

Prism's website appears to have the download functionality be client-side meaning using cURL would not work because it'll just download the HTML instead since it doesn't run any JS.

[tammersaleh]

Currently, I'm manually visiting the website and downloading a new version whenever I notice something's odd with our current styling (hoping the new version fixes it).

I'd probably use a curl-based approach if it existed, but it'd be a nice-to-have. I'd still have to review your CHANGELOG, etc, to make sure I'm upgrading properly.

[tammersaleh]

oh, and I don't use any JS tooling. it's just a bare bones (ruby-based) static website.

[allejo]

It's technically possible to do a cURL request right now and get a bundle. However, we're looking to see whether we can sunset that option and just have a client-side option only.

Our reasoning behind sunsetting this option is that we can't distribute updates to users easily. npm allows for easy security advisories. CDNs have version numbers in their URLs, you could theoretically scan them for known vulnerabilities (if anyone's built a tool like that). But with manually downloaded bundles, users are on their own.

Would you prefer having a cURL option? Oops, you already answered that! I clearly cannot read 😅

[joshgoebel]

Would you prefer having a cURL option?

Didn't they answer that already: ;-)

I'd probably use a curl-based approach if it existed, but it'd be a nice-to-have.

[tammersaleh]

Just a quick further comment. I think after highlightjs/highlight.js#1035, y'all added a cookie-based approach that saved the current checkboxes. That really doesn't work when the cookies get deleted or the project is team-wide. Having a URL is much better, especially if it's embedded in the downloadable in some way.

[joshgoebel]

or the project is team-wide.

Side note: For larger teams and 100% reproducible builds we recommend building from source (or importing via NPM), not using the website - as the website is subject to change versions at an time without warning - making it a poor choice for reliable builds.

[tammersaleh]

Just pinging this thread as I've hit this issue again. I'd like to add a single language to our highlight.js configuration, but I'd have to figure out all of the languages I'm currently using and click the checkbox for each one before downloading the new library. It's pretty painful 😢

[joshgoebel]

Thanks for the ping. Just a reminder for all that this is trivial when building directly from source - and this is what we currently recommend for anyone who needs easy to reproduce custom builds across versions.

./tools/build -t browser :common [all my languages here]

Such as:

./tools/build -t browser :common basic pascal fortran zulu

[RandTrawick]

@joshgoebel building from source is a great solution to this problem and worked well for me.
I recommend updating the download page with a note about repeatable custom language builds and linking to the
https://highlightjs.readthedocs.io/en/latest/building-testing.html#building so that people can more easily find the answer in the future.