all: highlight with shiki in production

[jo3-l]

• Syntax highlighting in codeblocks don't look as good as they could (compare to current GitBook docs)
• At some point, we would like to switch a highlighting style specialized to custom commands instead of using Go, but currently Hugo provides no facility to do so: Add support for chroma lexer overrides gohugoio/hugo#11496
• Alternatives: switch away from Chroma (Hugo's default highlighter) to a different syntax highlighter
  • However, most syntax highlighting libraries (notably, hljs and prism) render on client-side; Chroma runs at build time so the highlighted content is shipped directly to users
  • Can we do better?
• (This PR) experiments with a different build-time highlighter: https://shiki.style/
  • Shiki has additional benefits compared to all options above; see its website; it is also the highlighter that GitBook uses
• Downside: since Shiki is not built into Hugo, we need a second build step that runs after Hugo which post-processes the built HTML files directly (scripts/highlight.mjs)
  • Takes ~1s for 60 files on my machine, comparable to Hugo build time
• Downside 2: Shiki can't work with hot reload (npm run dev) since it is not built into Hugo, so the appearance of codeblocks is different in a production/dev env. That is, npm run dev will use built-in Doks highlighting (i.e., not Shiki.)
  • Can still preview appearance with Shiki by building npm run build (which automatically runs the post-processer), then npm run preview
• With that said, there is a (massive) upside:
  • Shiki is basically ~infinitely customizable, we are free from the Doks/Hugo shackles. Should be super straightforward to add a custom style for custom commands.

Terms

• I have read and understood this project's Contributing Guidelines

[jo3-l]

I yanked the copy button out of Doks internal in the latest commit, so we should be at feature parity now. Note that the copy button colors were designed for the Doks syntax highlighting theme so do not look as nice right now, but that is easily fixed in a follow-up. With that, then, I'll mark this PR as (tentatively) ready for review.

[l-zeuch]

Cool 👍