[WIP] Syntax highlighting for code blocks

[andrei-cacio]

Added syntax highlighting for code blocks using pirmsjs with the a11y-syntax-highlighting light theme.

Fixes #349

How it works

In layout.hbs I loaded the prism.min.js from a CDN and it looks for <code class="language-rust"></code> nodes and it decorates them with the proper HTMl for the CSS to work. I used Prism just for the actual Rust code blocks. For the other code blocks which contain bash samples or simple textual outputs I updated the app.scss file with the same background and text colors as the ay11 theme.

Accessibility Audit

Ran Lighthouse on the new code blocks and it passes background ratio audit.
(there is one more error left for it to be 100% passed, there is a duplicate id in the language select input. I will try to fix that as well)

Future improvements

Right now the highlight is done on the browser via JS. Maybe we can consider to move this into the compile step and have the code blocks in separate files and inject them in the templates.

Future nice-to-haves

Maybe add better bash highlighting for blocks like: curl https://sh.rustup.rs -sSf | sh

[mitsuhiko]

Not sure if this is known, but there is a crate (now?) for syntax highlighting that could be run on the server: https://crates.io/crates/syntect

[chriskrycho]

Thanks for taking this on! I had one question about this specific implementation and a possibly-lighter-payload alternative.

I also have one meta-comment: while we definitely can potentially pre-process these snippets with Syntect, this is actually a perfect example of progressive enhancement: the page will work perfectly with JS completely disabled or the particular import blocked by a content blocker, but it is made nicer via JS. Syntect can actually generate heavier pages than just loading the JS and CSS (and being able to cache it) once, because it puts all the styles directly inline—and making it generate just the correct classes to target with CSS instead is non-trivial.

[chriskrycho]

One quick question here – can you check the size of these two loads vs. using a custom build of highlight.js with only Rust support baked in? (I have no idea what the difference is there; this may still come out ahead!) If a custom highlight.js build is indeed smaller, we should use that and vendor it in here. In that case, we may have to pick a different theme, or we may be able to find a variant of this one tailored for that purpose.

[andrei-cacio]

The total size of the added JS is about 5.4kb gzipped. So it is a bit of an overhead just for a few markup. I think that pre-processing the highlight on the serverside would be a better approach.

I can try to integrate Syntect and see how it feels.

[andrei-cacio]

after briefly looking over Syntect I can say that the integration will take me a long time because of my lack of Rust skills. I will take a look over highlight.js and see how we can use that.

[andrei-cacio]

@chriskrycho I have pushed a new version with the custom highlight.js bundle which contains only the Rust logic. It is about 10.5 kb of minified JS.

It works fine but there are some discussions on the Github issue about how the light theme will blend with the existing design.

[chriskrycho]

Thank you! (I've been following both, gladly.) It looks like prism, even without the custom bundle, was smaller?

[andrei-cacio]

@chriskrycho
Prism: ~ 13Kb
Highlight: ~10.5Kb

[chriskrycho]

Cool! I'll pull this down and give it a spin and the old a11y validation, and hopefully we can land it shortly!

[andrei-cacio]

@chriskrycho how do you think we should tackle the problem? Should we use a dark theme on the red background? Or should we go with the light theme and wait for some more feedback?

[chriskrycho]

I think we should use the light theme and go forward. I'll have some time to test this on Monday!

[skade]

@chriskrycho is there anything blocking this (aside from the conflicts?)

[chriskrycho]

I don’t think so! Apologies that it lingered so long—it just totally fell off my mental radar as I switched jobs early this year.

[skade]

@chriskrycho Okay, I'll see if I can resolve and merge later today.

[skade]

See #764 for cleaned up PR.

[skade]

Superseded, as above.