daveaglick
commented
4 years ago There’s essentially two ways a static generator can highlight code blocks:
- The generator can take the code and insert
<span>elements in the appropriate places with the right styles at generation time. This has the benefit of “baking” the highlighted code right into the page without requiring client-side dependencies but results in bloat to HTML files and is somewhat limited because the style and grammars have to be available at generation-time. This is what Wyam.Highlight is intended to do. - The code block can be rendered by the generator with a style or attribute that says “hey client, here’s some code and you should use that fancy code highlighting client library I loaded to rewrite it and render it”. In this case the code usually gets placed within a
<pre>by the generator and then left alone. The client and JS libraries are then responsible for the highlighting. This is generally more common and is more flexible IMO. A number of good JS highlighting libraries exist that can do this. Wyam/Statiq isn’t directly involved in this case - it’s up to the layout or theme to load the JS library and call it in the client code. This is how several of the Wyam themes apply highlighting.
Either approach is fine and there’s trade offs to each. In Statiq going forward I’m thinking this should be entirely theme driven. Some themes will use the latter model and highlight on the client. Other themes may want to manipulate the generation pipelines at highlight at generation-time (which is a capability that’s new to Statiq - Wyam doesn’t have a good way for a theme to manipulate pipelines).
TL;DR: I’m hopeful Statiq (and more specifically Statiq themes) will be an improvement in regards to code highlighting.
Would it be possible to improve syntax highlighting in wyam (or statiq) and use something similar to what docfx uses to render code ? I don't know what it is and if it's usabled from outside docfx but code is really nice to read on docs.microsoft.com pages.
With Wyam.Highlight we have syntax highlighting but code is not really easy to read, I sometimes prefer using Github gists where the syntax highlighting is better but that means the code lives outside the blog post and I have to pay attention not to delete the gists.