feat(docs): format landing-page code snippets with Prism (#43)

The per-skill landing pages now let Prism format their code blocks. SKILL.md fenced code is tokenized server-side via the installed prismjs package, so every snippet on a skill page picks up the shared Prism theme, and the custom code-snippet styling (accent border, sunken panel) is scoped to the home page. The Prism theme is vendored from the npm dependency and inlined into each page.

Author: castastrophe

_data/lib/skill-metadata.js

@@ -6,6 +6,31 @@
  * `docs/tests/` exercise these directly.
  */
 import MarkdownIt from "markdown-it";
+import Prism from "prismjs";
+import loadLanguages from "prismjs/components/index.js";
+
+// Grammars for the fenced-code languages that appear in SKILL.md bodies. Loading
+// `bash` also registers its `shell` alias. `bash` doubles as the fallback grammar
+// for unknown/unlabeled fences (see `highlightFence`), so it must stay loaded.
+const FALLBACK_LANGUAGE = "bash";
+loadLanguages([FALLBACK_LANGUAGE, "json", "markdown", "yaml"]);
+
+/**
+ * Prism-highlight a fenced code block into the same `pre.language-*` markup the
+ * site's `{% highlight %}` shortcode emits, so the shared Prism theme formats the
+ * SKILL.md code snippets rendered on the per-skill landing pages. Unknown or
+ * unlabeled languages fall back to `bash` — most SKILL.md fences are shell
+ * commands — so every block is tokenized and picks up the Prism styling.
+ *
+ * @param {string} code
+ * @param {string} lang
+ * @returns {string}
+ */
+function highlightFence(code, lang) {
+	const language = lang && Prism.languages[lang] ? lang : FALLBACK_LANGUAGE;
+	const body = Prism.highlight(code, Prism.languages[language], language);
+	return `<pre class="language-${language}"><code class="language-${language}">${body}</code></pre>`;
+}
 
 /** Default branch used when building GitHub `blob`/raw URLs for skill assets. */
 export const DEFAULT_BRANCH = "main";
@@ -52,6 +77,7 @@ const renderToken = (tokens, idx, options, _env, self) => self.renderToken(token
  */
 export function createSkillRenderer() {
 	const md = new MarkdownIt({ html: true, linkify: true, typographer: true });
+	md.set({ highlight: (code, lang) => highlightFence(code, lang) });
 	const defaultLinkOpen = md.renderer.rules.link_open ?? renderToken;
 
 	md.renderer.rules.link_open = (tokens, idx, options, env, self) => {

_includes/foundation.njk

@@ -35,9 +35,16 @@
 		<link rel="preconnect" href="https://fonts.gstatic.com" crossorigin />
 		<link href="https://fonts.googleapis.com/css2?family=EB+Garamond:ital,wght@0,400..800;1,400..800&family=PT+Mono&family=Roboto:ital,wght@0,100..900;1,100..900&display=swap&family=Josefin+Sans:wght@400;500;600;700&display=swap" rel="stylesheet">
 
-		<link href="https://unpkg.com/prismjs@1.20.0/themes/prism.css" rel="stylesheet" />
 		<script src="https://kit.fontawesome.com/42e99b4632.js" crossorigin="anonymous"></script>
 
+		{# Prism syntax-highlighting themes, vendored from the installed `prismjs`
+		   package via Eleventy passthrough copy (see `eleventy.config.js`). Light and
+		   dark variants are swapped by `prefers-color-scheme` so code snippets track
+		   the page's light/dark mode. Loaded before the site styles so those can
+		   override them. #}
+		<link href="/assets/prism.css" rel="stylesheet" media="(prefers-color-scheme: light)" />
+		<link href="/assets/prism-dark.css" rel="stylesheet" media="(prefers-color-scheme: dark)" />
+
         <style>
 		:root {
 			color-scheme: {{ theme.colorScheme | default('light dark') }};

_includes/styles.css

@@ -122,23 +122,6 @@ p {
 	line-height: 1.8;
 }
 
-pre {
-	background: var(--theme--surface--color--sunken);
-	border-inline-start: 4px solid var(--base);
-	border-end-end-radius: .2em;
-	border-start-end-radius: .2em;
-	font-size: 0.8em !important;
-	box-shadow: inset 1px 1px 0 hsl(0deg 0% 0% / 0.04), inset -1px -1px 0 hsl(0deg 0% 0% / 0.04);
-
-	/* Breathing room so code doesn't sit flush against the left accent border. */
-	padding: 0.2rem .4rem;
-
-	/* Long lines (install commands, code samples) scroll inside the block
-	   instead of stretching the page past the viewport on narrow screens. */
-	max-inline-size: 100%;
-	overflow-x: auto;
-}
-
 code {
 	font-family: var(--theme--code--FontFamily);
 	line-height: 1.4;
@@ -155,6 +138,28 @@ code {
 	overflow-wrap: break-word;
 }
 
+/* Prism's themes add a text-shadow to code — a white "emboss" in the default
+   light theme — that reads as a halo on our card and prose surfaces (the code
+   block background is themed separately from Prism's own). Drop it so snippets
+   render flat and crisp in both light and dark mode. `text-shadow` inherits, so
+   this also clears it from the token spans. */
+:is(pre, code)[class*="language-"] {
+	text-shadow: none;
+}
+
+/* The site owns the code-block container so light and dark match: a flat surface
+   panel — the same color as inline `code` — with a thin subtle border and gentle
+   rounding. The Prism themes then supply only the token colors, so the light
+   theme's panel and prism-dark's brown panel, thick border, and inset shadow are
+   all overridden here. Components that own their code area (`.hero-terminal pre`,
+   `.card pre`) restyle it below. */
+pre[class*="language-"] {
+	background: var(--theme--surface--color);
+	border: 1px solid var(--theme--ui--color--subtle);
+	border-radius: 0.4em;
+	box-shadow: none;
+}
+
 /* Copy-to-clipboard affordance injected around every <pre> by copy-code.js. */
 .code-block {
 	position: relative;
@@ -589,6 +594,15 @@ li {
 		background: var(--theme--surface--color);
 	}
 
+	/* Code snippets in a card carry the brand accent bar instead of the full
+	   border, with the leading corners squared so the bar reads as a clean edge. */
+	pre[class*="language-"] {
+		border: none;
+		border-inline-start: 4px solid var(--base);
+		border-start-start-radius: 0;
+		border-end-start-radius: 0;
+	}
+
 	:is(header, .header) :is(h2, h3, h4, h5, h6):not([class]) {
 		font-size: calc(1.2em + 1cqi);
 	}

docs/skill.css

@@ -1,7 +1,17 @@
 .skill-hero {
 	padding-block: 2.5rem 2.25rem;
 	border-block-end: 1px solid var(--theme--ui--color--subtle);
-	background-image: linear-gradient(180deg, var(--theme--surface--color--accent), transparent);
+
+	/* Soft glow that fades delicately outward, matching the home page header
+	   (docs/styles.css) rather than a flat top-to-bottom wash. Anchored toward the
+	   start edge so the glow sits behind this hero's left-aligned content — the way
+	   the home glow sits behind its centered content — instead of leaving the
+	   top-left corner in the faint zone. */
+	background-image: radial-gradient(
+		75% 85% at 20% 0%,
+		var(--theme--surface--color--accent),
+		transparent 70%
+	);
 
 	> * + * {
 		margin-block-start: 1.25rem;

docs/styles.css

@@ -123,8 +123,14 @@ body > header {
 
 	pre {
 		margin: 0;
-		border-inline-start: none;
+		/* The terminal frame owns the border, the rounded corners (via
+		   overflow: hidden), and the background. Clear Prism's own border, radius,
+		   shadow, and panel color so the code area fills the frame flush instead of
+		   showing a mismatched inner box with a tighter border-radius. */
+		border: none;
+		border-radius: 0;
 		box-shadow: none;
+		background: var(--theme--surface--color--sunken);
 	}
 }
 

docs/tests/skill-metadata.test.js

@@ -106,3 +106,20 @@ test("wraps tables in a horizontal scroll container", () => {
 	assert.match(html, /<div class="table-scroll">\s*<table>/);
 	assert.match(html, /<\/table>\s*<\/div>/);
 });
+
+test("Prism-highlights fenced code into a language-tagged block", () => {
+	const md = createSkillRenderer();
+	const html = md.render("```bash\nnpm install foo\n```\n");
+	assert.match(html, /<pre class="language-bash"><code class="language-bash">/);
+	// Tokenized by Prism so the shared theme colors the snippet.
+	assert.match(html, /<span class="token function">npm<\/span>/);
+});
+
+test("unlabeled fences fall back to a tokenized bash block", () => {
+	const md = createSkillRenderer();
+	const html = md.render("```\nnpm install foo && echo done\n```\n");
+	assert.match(html, /<pre class="language-bash"><code class="language-bash">/);
+	// Tokenized as bash so shell operators are still colored, and HTML is escaped.
+	assert.match(html, /<span class="token function">npm<\/span>/);
+	assert.doesNotMatch(html, /class="language-none"/);
+});

eleventy.config.js

@@ -62,5 +62,11 @@ export default async function ( config ) {
 		"assets/*": "assets",
 		"skills/*/assets": "assets",
 		"skills/dreamlight-valley/references/sprites/*": "sprites",
+		// Prism syntax-highlighting themes, served from the installed `prismjs`
+		// dependency and linked from the base template (`_includes/foundation.njk`):
+		// the default light theme, plus a dark theme loaded under a dark-mode media
+		// query.
+		"node_modules/prismjs/themes/prism.css": "assets/prism.css",
+		"node_modules/prismjs/themes/prism-dark.css": "assets/prism-dark.css",
 	});
 };

package.json

@@ -89,6 +89,7 @@
     "listr2": "^10.2.1",
     "markdown-it": "^14.1.1",
     "pinst": "^3.0.0",
+    "prismjs": "^1.30.0",
     "text-table": "^0.2.0",
     "yargs": "^18.0.0"
   },

yarn.lock

@@ -177,6 +177,7 @@ __metadata:
     listr2: "npm:^10.2.1"
     markdown-it: "npm:^14.1.1"
     pinst: "npm:^3.0.0"
+    prismjs: "npm:^1.30.0"
     text-table: "npm:^0.2.0"
     yargs: "npm:^18.0.0"
   bin: