💄✨：highlight code where it is built

.remarkrc.mjs

@@ -52,6 +52,7 @@ const infoStrings = [
   'scheme',
   'tex',
   'text',
+  'ts',
   'typescript',
   'yaml',
 ];

_assets/styles/_code.scss

@@ -0,0 +1,71 @@
+@use 'sass:color';
+
+// Token colors for the highlighting Prism does at build time. Code sits on
+// $secondary rather than on the page, so every color here is chosen against
+// that and not against parchment. The palette is the site's own, shaded for contrast rather than widened:
+// warm red for the words a language reserves, teal for the values written
+// literally, and the body's own muted ink for everything structural. Nothing
+// here invents a hue the rest of the site does not use.
+
+$code-structural: color.mix($body-color, $secondary, 74%);
+$code-comment: color.mix($body-color, $secondary, 72%);
+$code-keyword: shade-color($quaternary, 22%);
+$code-literal: shade-color($primary, 22%);
+$code-callable: shade-color($primary, 48%);
+
+.doc-page .doc-prose pre code .token.comment,
+.doc-page .doc-prose pre code .token.prolog,
+.doc-page .doc-prose pre code .token.cdata {
+  font-style: italic;
+  color: $code-comment;
+}
+
+.doc-page .doc-prose pre code .token.punctuation,
+.doc-page .doc-prose pre code .token.operator,
+.doc-page .doc-prose pre code .token.entity,
+.doc-page .doc-prose pre code .token.url {
+  color: $code-structural;
+}
+
+.doc-page .doc-prose pre code .token.keyword,
+.doc-page .doc-prose pre code .token.atrule,
+.doc-page .doc-prose pre code .token.rule,
+.doc-page .doc-prose pre code .token.important,
+.doc-page .doc-prose pre code .token.tag,
+.doc-page .doc-prose pre code .token.selector {
+  color: $code-keyword;
+}
+
+.doc-page .doc-prose pre code .token.string,
+.doc-page .doc-prose pre code .token.char,
+.doc-page .doc-prose pre code .token.number,
+.doc-page .doc-prose pre code .token.boolean,
+.doc-page .doc-prose pre code .token.constant,
+.doc-page .doc-prose pre code .token.regex,
+.doc-page .doc-prose pre code .token.attr-value {
+  color: $code-literal;
+}
+
+.doc-page .doc-prose pre code .token.function,
+.doc-page .doc-prose pre code .token.class-name,
+.doc-page .doc-prose pre code .token.builtin,
+.doc-page .doc-prose pre code .token.attr-name,
+.doc-page .doc-prose pre code .token.property,
+.doc-page .doc-prose pre code .token.symbol {
+  color: $code-callable;
+}
+
+// A shell session prints its prompt and its output in the same block. The
+// command is what a reader copies, so the rest recedes.
+.doc-page .doc-prose pre code .token.output,
+.doc-page .doc-prose pre code .token.shell-symbol {
+  color: $code-structural;
+}
+
+.doc-page .doc-prose pre code .token.deleted {
+  color: shade-color($quaternary, 22%);
+}
+
+.doc-page .doc-prose pre code .token.inserted {
+  color: shade-color($primary, 40%);
+}

_assets/styles/main.scss

@@ -18,6 +18,7 @@
 @import '../../node_modules/bootstrap/scss/nav';
 @import '../../node_modules/bootstrap/scss/navbar';
 @import 'about';
+@import 'code';
 @import 'shell';
 @import 'docs';
 @import 'docs-page';

eleventy.config.mjs

@@ -12,10 +12,61 @@ import markdownItAnchor from 'markdown-it-anchor';
 import markdownItFootnote from 'markdown-it-footnote';
 import markdownItGitHubAlerts from 'markdown-it-github-alerts';
 import postcss from 'postcss';
+import Prism from 'prismjs';
+import loadPrismLanguages from 'prismjs/components/index.js';
 import { compileString } from 'sass';
 import { optimize as optimizeSvg } from 'svgo';
 import { minify as minifyJs } from 'terser';
 
+// Highlighting happens here rather than in the browser: a page is static by
+// the time it is served, and shipping a highlighter to run over it again would
+// be work done twice. Grammars are loaded once, at build time.
+//
+// Only what the site's own pages and the SDK's generated corpus actually use.
+// Prism resolves `ts`, `js`, `sh` and `shell` through its own aliases, so this
+// is a list of grammars rather than of the flags a fence may carry.
+loadPrismLanguages([
+  'bash',
+  'diff',
+  'json',
+  'markdown',
+  'markup',
+  'shell-session',
+  'typescript',
+  'yaml',
+]);
+
+// Prism has no `console`; a prompt-and-output block is `shell-session` to it.
+const PRISM_ALIASES = new Map([['console', 'shell-session']]);
+
+// Every grammar that got loaded, by name, aliases included. A map rather than
+// `Prism.languages` itself, because looking a flag up on that object reaches
+// its prototype as readily as its grammars: a block flagged `constructor`
+// would find `Object`'s and be handed to the tokenizer as if it were one. The
+// three helpers Prism keeps alongside the grammars are functions, and drop out
+// on the same test.
+const PRISM_GRAMMARS = new Map(
+  Object.entries(Prism.languages).filter(
+    ([, grammar]) => typeof grammar === 'object'
+  )
+);
+
+/**
+ * Marks up one fenced block, or gives markdown-it nothing and lets it escape
+ * the code itself. An unknown flag is not an error here: `text` is a fence
+ * with nothing to highlight, and the generated corpus carries flags from
+ * declarations this repository does not write.
+ * @param {string} code The block's contents.
+ * @param {string} flag Its info string.
+ * @returns {string} Highlighted HTML, or an empty string.
+ */
+const highlight = (code, flag) => {
+  const language = PRISM_ALIASES.get(flag) ?? flag;
+  const grammar = PRISM_GRAMMARS.get(language);
+
+  return grammar === undefined ? '' : Prism.highlight(code, grammar, language);
+};
+
 // skipcq: JS-0116
 export default async function (eleventyConfig) {
   const isProduction = process.env.ELEVENTY_ENV === 'production';
@@ -24,6 +75,7 @@ export default async function (eleventyConfig) {
   eleventyConfig.addFilter('sanitizeSdkHtml', sanitizeSdkHtml);
 
   eleventyConfig.amendLibrary('md', (md) => {
+    md.set({ highlight });
     md.use(markdownItAnchor);
     md.use(markdownItFootnote);
     // `> [!NOTE]` and the rest become a titled callout rather than a

package.json

@@ -33,6 +33,7 @@
     "@tsconfig/node-lts": "24.0.1",
     "@types/console-log-level": "1.4.5",
     "@types/node": "24.13.3",
+    "@types/prismjs": "1.26.6",
     "@types/sanitize-html": "2.16.1",
     "@yarnpkg/shell": "4.1.3",
     "autoprefixer": "10.5.4",
@@ -58,6 +59,7 @@
     "nps": "5.10.0",
     "postcss": "8.5.26",
     "prettier": "3.9.6",
+    "prismjs": "1.30.0",
     "remark": "15.0.1",
     "remark-cli": "12.0.1",
     "remark-frontmatter": "5.0.0",

project-terms.txt

@@ -1,14 +1,15 @@
 abled
 Aftertabs
 Anson
+atrule
 autolinks
 backref
 bento
 bibtex
 biomejs
 blockified
-Browserslist
 browserslist
+Browserslist
 browserslistrc
 davidanson
 dbaeumer
@@ -74,9 +75,9 @@ rowspan
 rubocop
 screencap
 sdcard
+semgrep
 SEMGREP
 Semgrep
-semgrep
 Servagility
 signingkey
 siteify