Support `Var`s in syntax-highlighted snippets

[ptgott]

Fixes #186

Syntax highlighting in the docs engine works by using rehype-highlight, which is a wrapper for highlight.js. highlight.js applies syntax highlighting by replacing the contents of a <pre><code></code></pre> with <span> elements that include hljs-* class names.

The way highlight.js works poses difficulties for adding Var components to syntax-highlighted code snippets, since any content within a code snippet becomes subject to rewrites by highlight.js.

Without access to the highlight.js internals, we need to:

• Support a consistent Var experience inside and outside code snippets
• Prevent Vars from being overwritten

This change presents a solution that:

• Replaces Var components with UUIDs: This minimizes the chance that a Var component will be highlighted, since characters in [a-z0-9] are usually permissible within strings or identifiers. This also removes hyphens and begins the placeholder with a letter to help ensure the highlighter parses it as an identifier.
• Maintains a map of placeholder strings to AST nodes.
• After applying syntax highlighting to a page, replaces the placeholder strings with the corresponding AST node.

[vercel[bot]]

The latest updates on your projects. Learn more about Vercel for Git ↗︎

Name	Status	Preview	Comments	Updated (UTC)
docs	✅ Ready (Inspect)	Visit Preview	💬 Add feedback	Aug 9, 2023 6:39pm

[ptgott]

Converting to draft while I work out some issues:

• [x] Investigate/fix malformed Var element within a code snippet errors in this build. Update: It turns out this error happens when processing a VarList.
• [x] Make sure the overall build time isn't significantly greater because of this change