@zvndev/darkmown 1.2.0 → 1.3.0

package/CHANGELOG.md

@@ -2,6 +2,23 @@
 
 All notable changes to Darkmown are documented here. Versions follow [semver](https://semver.org); pre-1.0 minor versions may contain breaking changes.
 
+## 1.3.0 — 2026-06-28
+
+The "table-stakes batteries" release — the build-time, zero-JS features a markdown site is expected to ship. The runtime is unchanged (still 7459 B gzipped, well under the 8 KB budget); everything here is compile-time HTML/CSS or build output.
+
+- **Syntax highlighting.** Fenced code blocks with a known language are highlighted at compile time (via `highlight.js` through markdown-it) — HTML plus a small stylesheet, **zero client JS**. Colors are driven by a new `$code-*` skin-token set (`code-bg`, `code-fg`, `code-keyword`, `code-string`, `code-comment`, `code-function`, `code-number`, `code-punctuation`), so code **dark-modes for free** through the existing `tokens dark` / `:theme` system — override any token in your own `.skin`. The stylesheet (`/__wd/highlight.css`) ships **only on pages that contain a highlighted block** (pay-for-what-you-use). Unknown/absent languages degrade to plain escaped `<code>`; inline code and line numbers are intentionally excluded; a prose+code page stays `runtime: false`.
+- **RSS + sitemap.xml + robots.txt.** `darkmown build` now emits `sitemap.xml`, `rss.xml`, and `robots.txt` at build time. Site identity lives in **one reserved home-page frontmatter field, `site_url`** (absolute origin) — which reuses the home `title`/`description` as the RSS channel and acts as the trigger; no config file is introduced. The sitemap lists every published route with a `<lastmod>` (frontmatter `date` → git last-commit date → file mtime). Any page with a `date:` becomes an RSS item (newest-first, capped; description from `excerpt:` → `description:` → first paragraph of a `.md`); an `<link rel="alternate" type="application/rss+xml">` is injected into every page `<head>`. With no `site_url`, `robots.txt` still emits (without the `Sitemap:` line) and the feeds are skipped with a build hint — never a crash.
+- **Drafts.** `draft: true` frontmatter excludes a page from a production build — gone from `dist`, `routes.json`, the sitemap, and the feed (even if it has a `date:`). `darkmown dev` still builds and serves drafts with a dev-only banner; `darkmown build --drafts` includes them (for staging). Drafts are filtered at route discovery, so a feed can never leak one. This is distinct from the permanent `.`/`-`/`_` filename-prefix hiding: use a prefix to hide a file forever, `draft: true` to hide a page you intend to publish later.
+- **New public frontmatter:** `site_url` (home page), `draft`, `date`, `excerpt`. New build flag: `--drafts`. The `blog` starter template now ships working feeds out of the box.
+
+## 1.2.1 — 2026-06-27
+
+Repository hygiene and documentation polish from a gold-standard audit (50/50 — every dimension at React-tier). No runtime, API, or behavior change; the shipped package is byte-identical except for one source comment.
+
+- **Architecture docs name the value layer.** `src/compiler/format.js` (format pipes + list aggregates) is now listed in the compiler module map in both `CLAUDE.md` and `src/compiler/index.js` — previously the only module in the compile path absent from the architecture doc.
+- **Honest CI labels.** The coverage-gate job was labeled "src-only line ≥ 90%" but `npm run test:cov` has always enforced **100%** (`scripts/test-coverage-gate.mjs 100`). The job name and its comment now state the real bar.
+- **Tighter ignore rules.** `.env` / `.env.*` are now gitignored (the build's hidden-segment asset guard already kept them out of `dist`; this stops one from ever reaching git), and a stale internal design spec that predated the `docs/superpowers/` ignore rule is no longer tracked.
+
 ## 1.2.0 — 2026-06-27
 
 Backends, deploy, and rich interactions — all additive. The core runtime is unchanged (still well under the 8 KB budget); the new behavior modules are budgeted separately so static pages stay zero-JS.

package/README.md

@@ -52,7 +52,7 @@ npm run dev     # live demo site — the same site that runs darkmown.com
 
 - `darkmown init [dir] [--template <name>]` scaffolds a new site from a template (`starter`, `blog`, `store`, `dashboard`, `landing`).
 - `darkmown dev` starts the live compiler with browser reload, an in-browser error overlay, and a local runner for `api/*` functions.
-- `darkmown build [--target cloudflare]` writes static output to `dist`.
+- `darkmown build [--target cloudflare] [--drafts]` writes static output to `dist` (plus `sitemap.xml`/`rss.xml`/`robots.txt`); `--drafts` includes `draft: true` pages for staging.
 - `darkmown deploy <vercel|cloudflare> [--prod]` builds and deploys via the platform CLI.
 - `darkmown serve` previews the built `dist` locally.
 - `darkmown version` prints the installed package version.
@@ -113,6 +113,8 @@ tags: [sales, revenue, "q1, q2"]
 
 Three keys also drive the document `<head>`: `title` sets `<title>`, `description` adds the meta description plus Open Graph / Twitter tags, and `image` (an absolute URL) sets the social-share preview (`og:image` / `twitter:image` and a `summary_large_image` card).
 
+A few reserved keys drive **drafts and feeds** (see [SEO & feeds](#seo--feeds-sitemap-rss-robots) below): `draft: true` excludes a page from production builds; `site_url` on the home page turns on `sitemap.xml` + `rss.xml`; `date:` marks a page as a blog post (it lands in `rss.xml` and sets the page's `<lastmod>`); `excerpt:` is the RSS summary.
+
 `transitions: true` opts a page into **instant, flash-free navigation** — zero JavaScript, all declarative. It emits a directional fade+slide **view transition** for the page swap (old lifts up and out, new rises up and in — replacing the default cross-fade, which left both pages ghosted at ~50 % opacity mid-navigation), plus a **`<script type="speculationrules">` prerender** hint that renders the next same-origin page on hover/pointerdown so the click activates an already-painted page (no white render-gap flash). It honors `prefers-reduced-motion`. Only same-origin pages that both opt in transition; browsers without support — or with page-preloading disabled — navigate normally. Off by default; opt out with `transitions: false`. Mark a link `{.no-prefetch}` to exclude it from prerendering. (Chrome disables prerendering while DevTools is open, so test the built site with DevTools closed.)
 
 ## Static assets
@@ -135,6 +137,55 @@ Hidden/private page paths stay private: any `site/pages` asset below a path segm
 
 Use the shelf for assets shared across many pages; colocate the ones that belong to a single page or section. Both ship untouched with the correct content-type.
 
+## SEO & feeds (sitemap, RSS, robots)
+
+`darkmown build` emits the crawler files a site needs — all build-time, zero client JS — driven by a little frontmatter. There is no config file: the **home page** (`site/pages/index.md` or `.wd`) carries the site's identity.
+
+```wd
+---
+title: My Blog
+description: Notes on shipping Markdown that runs.
+site_url: https://example.com
+---
+```
+
+- **`site_url`** (absolute origin, **no trailing slash**) turns on `sitemap.xml` and `rss.xml` and is the absolute prefix for every URL in them. The home `title`/`description` become the RSS channel title/description.
+- **`robots.txt`** is *always* emitted (`User-agent: * / Allow: /`); the `Sitemap:` line is added only when `site_url` is set.
+- **`sitemap.xml`** lists every built page (reactive pages included — they're indexable HTML). Each `<lastmod>` is the page's frontmatter `date:` if set, else its git last-commit date, else the file's mtime. No `<priority>`/`<changefreq>`.
+- **`rss.xml`** syndicates your **posts** — any page with a `date:` in its frontmatter. Newest first, capped at the 20 most recent. Each item's `<description>` is the page's `excerpt:`, else its `description:`, else (for a plain `.md` post) its first paragraph. Every page links the feed with `<link rel="alternate" type="application/rss+xml">` so readers can autodiscover it.
+
+```md
+---
+title: Hello, Darkmown
+date: 2026-01-15
+excerpt: Why I rewrote my blog as plain Markdown files.
+---
+
+# Hello, Darkmown
+…
+```
+
+Without `site_url`, `robots.txt` still emits and the build prints a one-line hint telling you which field to set; it never crashes.
+
+### Drafts
+
+Mark any page `draft: true` to keep it out of production:
+
+```md
+---
+title: Work in progress
+draft: true
+---
+```
+
+- **`darkmown build`** excludes drafts everywhere — no HTML in `dist`, no entry in `routes.json`, `sitemap.xml`, or `rss.xml` (even a draft that *also* has a `date:` never reaches a feed).
+- **`darkmown dev`** builds and serves drafts so you can preview them, with a visible "DRAFT" banner that exists only in the dev server — never in any shipped HTML.
+- **`darkmown build --drafts`** includes drafts everywhere — for a staging deploy.
+
+Drafts are filtered at one point — route discovery — so nothing downstream ever sees them. This is **separate from** the permanent `.`/`-`/`_` filename hiding: a hidden name (`-notes.wd`) is private forever; `draft:` is a toggle you flip when the page is ready to ship.
+
+The `build` summary reports what it emitted: `Built 14 routes, sitemap (14 urls), rss (6 posts) into dist`.
+
 ## Loops
 
 `@loop <things> into <thing>` is the only loop. The source decides the behavior:
@@ -692,6 +743,39 @@ The block must follow the element with no space, and works on links, images, emp
 
 Darkmown's shipped CSP pre-authorizes exactly the two embed origins (`youtube-nocookie.com`, `player.vimeo.com`) and `media-src 'self' https:`, so embeds and remote media work out of the box on the bundled server, Cloudflare `_headers`, and Vercel.
 
+## Syntax highlighting
+
+*New in 1.3.* Fenced code blocks with a language are highlighted at **build time** — HTML and CSS only, no client JavaScript. Tag the fence with a language and it just works:
+
+````md
+```js
+const greeting = "Darkmown"; // highlighted at build time
+```
+````
+
+The highlighter is [highlight.js](https://highlightjs.org/) and is not configurable (one closed default, like the rest of the framework). Its token classes map onto your skin's `$code-*` tokens, so highlighted code **dark-modes for free** through the same [`tokens dark` / `:theme`](#dark-mode--tokens-dark) system below — no extra wiring. Tune the palette (or rely on the built-in default set) in your `.skin`:
+
+```skin
+tokens
+  code-bg #1b2420
+  code-fg #e9efe7
+  code-keyword #d9a8e0
+  code-string #97d892
+  code-comment #859289
+  code-function #88c4ee
+  code-number #ecae78
+  code-punctuation #c1ccc6
+tokens dark
+  code-bg #100d0a
+  code-keyword #e2b9e8
+```
+
+- **Pay-for-what-you-use.** The stylesheet (`/__wd/highlight.css`) is emitted and linked **only** on pages that actually contain a highlighted block — a page with no code ships nothing extra.
+- **Zero runtime.** Highlighting is build-time output, so a page of prose plus code stays `runtime: false` (no `/__wd/runtime.js`). It never pulls in the reactive runtime.
+- **Graceful degradation.** A fence with an unknown or absent language renders as plain escaped `<code>` (no highlighting, no error). Inline `` `code` `` is never highlighted, and there are deliberately **no line numbers** (they break copy-paste).
+
+See it recolor live on the [Syntax highlighting demo](https://darkmown.com/highlight/) — flip the theme toggle and every block recolors at once.
+
 ## Dark mode — `tokens dark`
 
 *New in 0.19.0.* A colocated `.skin` file already declares its palette in a `tokens` block (`name value` pairs referenced elsewhere as `$name`). Add a second `tokens dark` block to override any of those tokens under the visitor's OS dark preference — it compiles to a `@media (prefers-color-scheme: dark) :root { … }` rule, so the page follows the system theme with **zero JavaScript**.

package/docs/spec-alignment.md

@@ -134,6 +134,14 @@ Four progressive-disclosure capabilities plus an assets and a security change. T
 - **Page-colocated static assets:** any non-page file under `site/pages/` (anything but `.md`/`.wd` routes and colocated `.skin`/`.js`) is copied to `dist/` at its path (`site/pages/logo.svg` → `dist/logo.svg`). The shelf (`site/_/` → `/__wd/media`, `/__wd/data`) is unchanged; a name clash with an emitted route is skipped with a warning. As of v0.14.1, hidden path segments (`.`, `-`, `_`) and symlinked page assets are skipped. `.avif` was added to the served content-types.
 - **`:fetch` URL scheme hardening (security):** `:fetch`/`refresh=` URLs are validated at compile time — relative, `http(s)://`, or a leading `{ state }` interpolation are allowed; protocol-relative `//host` and non-http(s) schemes (`file:`, `data:`, `javascript:`, …) are rejected with a corrective hint. **This is scheme validation, not a host allowlist** — SSRF to arbitrary http(s) hosts remains the author's responsibility (see the trust boundary).
 
+## 1.3.0 additions — table-stakes batteries (2026-06-28)
+
+The 1.3.0 cycle closes table-stakes gaps a new user expects out of the box. Tracks land in parallel; this entry covers the **syntax-highlighting** and **drafts + feeds** tracks.
+
+- **Drafts + sitemap.xml + rss.xml + robots.txt:** three coupled SEO/feed capabilities sharing one draft-exclusion gate. Site identity lives in the **home page frontmatter** (no config loader this cycle): one reserved field `site_url` (absolute origin, no trailing slash) reuses the home `title`/`description` as the RSS channel fields and is the absolute prefix for — and the trigger for emitting — `sitemap.xml` + `rss.xml`. **Drafts:** `draft: true` excludes a page from a production build everywhere (not in `dist`, `routes.json`, sitemap, or rss — even a draft that *also* has a `date:`); `darkmown dev` builds/serves drafts with a dev-only visible banner injected at serve time (never in shipped HTML, like the SSE client); `darkmown build --drafts` includes them for staging. Drafts are filtered at the single route-discovery **chokepoint** (`discoverRoutes`), which now reads each file's frontmatter **once** and threads it out as `route.meta` (one source of truth for "is this a draft", and the data the feeds consume — no second parse). This is distinct from the permanent `.`/`-`/`_` filename hiding (private forever vs a publish-when-ready toggle). **sitemap.xml** (emitted whenever `site_url` is set) lists one `<url>` per built non-404 route — reactive pages included (indexable HTML) — with `<lastmod>` = frontmatter `date:` → git last-commit date of the source file → file mtime (git wrapped in try/catch so a scaffolded app or extracted tarball with no `.git` degrades to mtime, never crashes); no `<priority>`/`<changefreq>`. **rss.xml** (emitted only with `site_url` *and* at least one dated post) syndicates the pages with a `date:` (the "this is a post" signal), newest-first, capped at 20; `<description>` resolves `excerpt:` → `description:` → first paragraph of rendered prose (plain `.md` only — `.wd` directive markup is not stripped back to prose); `<pubDate>` is RFC-822; every page advertises the feed with `<link rel="alternate" type="application/rss+xml">`. **robots.txt** is *always* emitted (`User-agent: * / Allow: /`); the `Sitemap:` line appears only with `site_url`. **No `site_url`:** robots still emits (without the Sitemap line), sitemap + rss are skipped with a loud, actionable build hint, and the build never crashes. String/XML building lives in a new `src/feeds.js` (mirroring how `src/highlight.js` keeps `builder.js` lean); the `build` summary reports counts (`Built 14 routes, sitemap (14 urls), rss (6 posts) into dist`). **Zero runtime impact** — all build-time; `src/runtime.js` and the 8 KB budget are untouched. **The leak contract** (a `draft: true` page with a `date:` produces zero sitemap entries and zero rss items; `/404/` never appears in either) is regression-tested on both the production-exclusion and `--drafts`-inclusion paths, plus the git-date vs mtime-fallback paths.
+
+- **Build-time syntax highlighting:** fenced code blocks with a known language are highlighted at compile time via [highlight.js](https://highlightjs.org/), wired onto both markdown-it instances (the default `html: true` and the lazy `html: false` strict variant) through markdown-it's `highlight` option in `src/compiler/markdown.js`. Output is **class-based** (`hljs-*` token spans, escaped) — no inline colors — and the framework ships a small stylesheet (`/__wd/highlight.css`) that maps the common token classes onto a `$code-*` skin-token set (`code-bg`, `code-fg`, `code-keyword`, `code-string`, `code-comment`, `code-function`, `code-number`, `code-punctuation`), each `var(--code-*, fallback)`. Because those tokens carry a `tokens dark` override in the base skin, **highlighted code dark-modes for free** through the existing `tokens dark` / `:theme` system with zero JavaScript. The highlighter is **not configurable** (closed-whitelist philosophy). Emission/injection is **pay-for-what-you-use**: a per-page `assets.hasCode` flag (set when the rendered HTML carries the `hljs` marker) emits and links the stylesheet **only** on pages that contain a highlighted block, mirroring the behavior modules — a page with no code ships nothing extra. **Zero runtime impact:** highlighting is build-time HTML + CSS only (`src/runtime.js` untouched, the 8 KB runtime budget unchanged), so a page of prose plus a code block stays `runtime: false`. **Graceful degradation:** a fence with an unknown or absent language renders as plain escaped `<code>` (no throw, no highlighting); inline `` `code` `` is never highlighted; there are deliberately **no line numbers** (they break copy-paste). **Honest caveat:** the stylesheet maps a curated common subset of highlight.js classes — any token class outside that subset inherits the base `--code-fg` color, so it stays legible but is not individually themed.
+
 ## 1.2.0 additions — backends, deploy & interactions (2026-06-27)
 
 - **Serverless `api/` model:** backend endpoints are plain-JS Web-standard handlers — `export default (request, context) => Response` — in a top-level `api/` directory (`api/echo.js` → `/api/echo`; `api/users/[id].js` → `/api/users/:id` with `context.params.id`). Darkmown owns no server; it *adapts* to the host. The build stays 100% static. On Vercel the `api/` functions run natively (Edge); `darkmown deploy cloudflare` (or `build --target cloudflare`) emits `dist/_worker.js` that routes `/api/*` to the same functions and serves everything else from `env.ASSETS`. `darkmown dev` runs a local runner so `/api/*` behaves identically before deploy. No `.wd` backend DSL — minimal new learning, zero lock-in. `form-action 'self'` was added to both CSP variants (and `vercel.json`) so a native `:form action="/api/…"` POST is allowed.

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@zvndev/darkmown",
-  "version": "1.2.0",
+  "version": "1.3.0",
   "private": false,
   "publishConfig": {
     "access": "public"
@@ -57,6 +57,7 @@
     "node": ">=20"
   },
   "dependencies": {
+    "highlight.js": "^11.11.1",
     "image-size": "^1.2.1",
     "markdown-it": "^14.2.0"
   },

package/site/_/base.skin

@@ -26,6 +26,13 @@ tokens
   code-bg #1b2420
   code-ink #e9efe7
   code-line #2c3b34
+  code-fg #e9efe7
+  code-keyword #d9a8e0
+  code-string #97d892
+  code-comment #859289
+  code-function #88c4ee
+  code-number #ecae78
+  code-punctuation #c1ccc6
   ring #0f6b5e
   radius 12px
   radius-sm 8px
@@ -51,6 +58,13 @@ tokens dark
   code-bg #100d0a
   code-ink #e4ebe2
   code-line #2a231b
+  code-fg #e4ebe2
+  code-keyword #e2b9e8
+  code-string #a6e0a1
+  code-comment #7c8983
+  code-function #9bd0f4
+  code-number #f2bb8a
+  code-punctuation #b6c2bc
   ring #5ccab4
 
 /* ── Reset & base ───────────────────────────────────────────────── */

package/site/_/nav.wd

@@ -5,6 +5,7 @@
     <a href="/showcase/">Showcase</a>
     <a href="/reactive/">Reactive</a>
     <a href="/data/">Data</a>
+    <a href="/highlight/">Highlight</a>
   </span>
   <a class="nav-gh" href="https://github.com/ZVN-DEV/darkmown">GitHub ↗</a>
 </nav>

package/site/pages/blog/drafts-that-never-leak.md

@@ -0,0 +1,16 @@
+---
+title: Drafts that never leak
+description: draft true excludes a page everywhere in a production build — dist, routes.json, sitemap, and rss.
+date: 2026-06-27
+---
+
+# Drafts that never leak
+
+Set `draft: true` on any page and it disappears from a production build — no
+HTML in `dist`, no entry in `routes.json`, and crucially no entry in
+`sitemap.xml` or `rss.xml`, even if the draft also carries a `date:`.
+
+The filter lives at one chokepoint — route discovery — so every downstream
+consumer only ever sees published pages. `darkmown dev` still builds and serves
+your drafts (with a visible banner), and `darkmown build --drafts` includes them
+for a staging preview.

package/site/pages/blog/index.md

@@ -0,0 +1,13 @@
+---
+title: The Darkmown Blog
+description: Notes on shipping Markdown that runs — feeds, drafts, and zero-JS releases.
+---
+
+# The Darkmown Blog
+
+Short notes on the framework. Every post here is a plain `.md` file with a
+`date:` in its frontmatter — that `date:` is what lands a page in `rss.xml` and
+stamps its `<lastmod>` in `sitemap.xml`.
+
+- [Shipping feeds without a config file](/blog/shipping-feeds/)
+- [Drafts that never leak](/blog/drafts-that-never-leak/)

package/site/pages/blog/shipping-feeds.md

@@ -0,0 +1,17 @@
+---
+title: Shipping feeds without a config file
+description: Site identity lives in the home page frontmatter — one site_url field turns on sitemap.xml and rss.xml.
+date: 2026-06-26
+excerpt: One reserved frontmatter field on the home page — site_url — turns on the whole feeds story. No config loader, no plugin.
+---
+
+# Shipping feeds without a config file
+
+Darkmown has no config file, so the site's public origin lives where the rest of
+its identity already does: the home page frontmatter. Add `site_url` to
+`site/pages/index` and the build emits `sitemap.xml` and `rss.xml`, reusing the
+home `title` and `description` as the RSS channel fields.
+
+Every page picks up a `<link rel="alternate" type="application/rss+xml">` so
+feed readers can autodiscover the feed, and `robots.txt` points crawlers at the
+sitemap. All build-time — not a byte of client JavaScript.

package/site/pages/blog/unfinished-thoughts.md

@@ -0,0 +1,13 @@
+---
+title: Unfinished thoughts (do not ship)
+description: A work-in-progress post that demonstrates draft exclusion — it carries a date but never reaches a production feed.
+date: 2026-06-28
+draft: true
+---
+
+# Unfinished thoughts
+
+This post is marked `draft: true`. It also has a `date:`, which would normally
+land it in `rss.xml` and `sitemap.xml` — but because it is a draft, a production
+build excludes it from both, and from `dist` and `routes.json` entirely. You are
+only reading this in `darkmown dev` or a `build --drafts` staging build.

package/site/pages/docs/index.wd

@@ -176,6 +176,24 @@ tags: [sales, revenue, "q1, q2"]
 
 `{ meta.title }` prints a scalar and `{ meta.tags }` joins an array with `, `. You can loop a frontmatter array at build time — `@loop meta.tags into tag` — and the page stays static. Arrays are inline flow only (`[a, b]`); quoted items keep their commas.
 
+## SEO & feeds
+
+`darkmown build` writes `sitemap.xml`, `rss.xml`, and `robots.txt` — all build-time, zero client JS. There's no config file: the **home page** frontmatter carries the site's identity. Add `site_url` (absolute origin, no trailing slash) and the sitemap and feed switch on, prefixed with that origin and titled with the home `title`/`description`.
+
+```wd
+---
+title: My Blog
+description: Notes
+site_url: https://example.com
+---
+```
+
+A page becomes an **RSS post** by carrying a `date:`; `excerpt:` is its feed summary (else `description:`, else — for a plain `.md` — its first paragraph). The sitemap's `<lastmod>` is the `date:` if set, else the file's git/last-modified date. `robots.txt` is always written; the `Sitemap:` line only appears with a `site_url`. Without `site_url`, robots still emits and the build prints a hint — it never breaks.
+
+## Drafts
+
+Mark a page `draft: true` and it stays out of production: `darkmown build` leaves it out of `dist`, `routes.json`, the sitemap, and the feed — even if it has a `date:`. `darkmown dev` still builds and serves it (with a "DRAFT" banner you only see in dev), and `darkmown build --drafts` includes drafts for a staging deploy. This is separate from the permanent `.`/`-`/`_` filename hiding — a hidden name is private forever; `draft:` is a switch you flip when the page is ready.
+
 ## Instant navigation
 
 Add `transitions: true` to a page's frontmatter for **instant, flash-free navigation** — zero JavaScript. It emits a directional fade+slide view transition for the page swap and a `<script type="speculationrules">` prerender hint, so the browser renders the next same-origin page on hover/pointerdown and the click activates an already-painted page (no white render-gap). It honors `prefers-reduced-motion`, and only same-origin pages that both opt in transition. Off by default; opt out with `transitions: false`, or exclude a single link from prerendering with `{.no-prefetch}`. (Chrome turns prerendering off while DevTools is open — test the built site with DevTools closed.)
@@ -408,6 +426,35 @@ Three compile-time-only directives (they emit no `data-wd-*`, so a media page st
 
 `:video`/`:audio` emit a hardened HTML5 player — `preload="metadata"` and `controls` by default, whitelisted flags (`autoplay` implies `muted`), and the `:fetch` URL scheme guard. `:embed` rewrites a YouTube/Vimeo link to its no-cookie/player form in a lazy, responsive `16/9` iframe. See the zero-JS [Media demo](/media/).
 
+## Syntax highlighting
+
+Fenced code blocks with a language are highlighted at **build time** — HTML and CSS only, no client JavaScript. Tag the fence with a language:
+
+````md
+```js
+const greeting = "Darkmown"; // highlighted at build time
+```
+````
+
+The highlighter is [highlight.js](https://highlightjs.org/) and isn't configurable (one closed default, like everything else). It maps onto your skin's `$code-*` tokens, so highlighted code **dark-modes for free** through the same `tokens dark` / `:theme` system — no extra wiring. Define the palette once:
+
+```
+tokens
+  code-bg #1b2420
+  code-fg #e9efe7
+  code-keyword #d9a8e0
+  code-string #97d892
+  code-comment #859289
+  code-function #88c4ee
+  code-number #ecae78
+  code-punctuation #c1ccc6
+tokens dark
+  code-bg #100d0a
+  code-keyword #e2b9e8
+```
+
+The framework ships a small default `$code-*` set, so highlighting looks right out of the box. The stylesheet is **pay-for-what-you-use**: it's emitted and linked only on pages that actually contain a highlighted block — a page with no code ships nothing extra. A fence with an unknown or absent language renders as plain escaped `<code>` (no highlighting, no error); inline `` `code` `` is never highlighted, and there are deliberately no line numbers (they break copy-paste). See the live [Syntax highlighting demo](/highlight/).
+
 ## Trust boundary
 
 Darkmown is a trusted-author site generator: you compile content you wrote, the way you trust your own source. Three things define that boundary.

package/site/pages/highlight/index.skin

@@ -0,0 +1,78 @@
+main.app-highlight
+  max-width 1000px
+  margin 0 auto
+  padding 2.5rem 1.5rem
+
+.hl-eyebrow
+  text-transform uppercase
+  letter-spacing .08em
+  font-size .8rem
+  opacity .7
+
+.hl-tagline
+  font-size 1.05rem
+  opacity .85
+  margin-top .5rem
+  max-width 60ch
+
+/* Theme toggle — reuse the ledger's pill-button switch so flipping the theme
+   recolors every highlighted block at once. */
+.app-highlight .theme-switch
+  display inline-flex
+  align-items center
+  gap .4rem
+  font-size .75rem
+  font-weight 600
+  letter-spacing .04em
+  text-transform uppercase
+  color $muted
+  margin 1.5rem 0 .5rem
+
+.app-highlight .theme-switch button[data-wd-action]
+  border 1px solid $line
+  bg $panel
+  color $ink-soft
+  font-size .8rem
+  font-weight 600
+  padding .4rem .8rem
+  radius 999px
+  cursor pointer
+  transition color .14s ease, border-color .14s ease, background .14s ease
+
+.app-highlight .theme-switch button[data-wd-action]:hover
+  color $ink
+  border-color $accent
+
+.hl-grid
+  margin 1rem 0 1.5rem
+
+.hl-panel
+  padding 1.4rem 1.5rem
+
+.hl-panel h3
+  margin-top 0
+  margin-bottom .6rem
+  font-size 1rem
+  color $muted
+  text-transform uppercase
+  letter-spacing .04em
+
+.hl-panel pre
+  margin 0
+
+.hl-note
+  margin-top 1.5rem
+  padding 1rem 1.25rem
+  border 1px solid $line
+  border-left 3px solid $accent
+  bg $panel
+  radius $radius-sm
+  color $ink-soft
+  font-size .95rem
+
+.hl-degrade
+  border-left-color $muted
+
+@media (max-width: 760px)
+  .hl-grid
+    grid-template-columns 1fr

package/site/pages/highlight/index.wd

@@ -0,0 +1,142 @@
+---
+title: Syntax highlighting — code that dark-modes for free
+description: Build-time syntax highlighting in plain Markdown. Fenced code blocks highlight at compile time (zero client JS) and recolor with your theme through the same tokens dark / :theme system — flip the toggle and watch every language recolor at once.
+image: https://darkmown.com/__wd/media/og-showcase.png
+transitions: true
+---
+
+@include /nav.wd
+@include /base.wd
+
+<main class="wide app-highlight">
+
+::: section #highlight
+
+:theme
+
+::: hl-head
+::: eyebrow .hl-eyebrow
+Build-time syntax highlighting
+:::
+
+# *Highlighted code*
+
+::: hl-tagline
+Fenced code blocks highlight at **build time** — HTML and CSS only, no client
+JavaScript. Colors come from your skin's `$code-*` tokens, so highlighting
+recolors with the theme through the same `tokens dark` / `:theme` system that
+drives the rest of the page. Flip the toggle and watch every block below recolor
+at once — no toggle script for the code, no flash.
+:::
+:::
+
+::: theme-switch
+Theme
+:button "Auto" -> theme = "auto"
+:button "Light" -> theme = "light"
+:button "Dark" -> theme = "dark"
+:::
+
+::: grid .cols-2 .hl-grid
+
+::: card .hl-panel
+### JavaScript
+
+```js
+// A tiny reactive island, declared in Markdown.
+const cart = wd.state("cart");
+function total(items) {
+  return items.reduce((sum, it) => sum + it.price, 0);
+}
+wd.subscribe("cart", (items) => {
+  document.title = `Cart (${items.length})`;
+});
+```
+:::
+
+::: card .hl-panel
+### Python
+
+```python
+from dataclasses import dataclass
+
+@dataclass
+class Expense:
+    merchant: str
+    amount: float  # in dollars
+
+def total(rows: list[Expense]) -> float:
+    return sum(r.amount for r in rows)
+```
+:::
+
+::: card .hl-panel
+### CSS
+
+```css
+.card {
+  background: var(--panel, #fff);
+  border: 1px solid var(--line);
+  border-radius: 12px;
+  padding: 1.4rem;
+}
+```
+:::
+
+::: card .hl-panel
+### JSON
+
+```json
+{
+  "name": "@zvndev/darkmown",
+  "type": "module",
+  "zeroJsOnStaticPages": true,
+  "runtimeBudgetKb": 8
+}
+```
+:::
+
+::: card .hl-panel
+### Bash
+
+```bash
+npx @zvndev/darkmown init --template blog
+cd blog && npx darkmown dev   # live reload on :5173
+```
+:::
+
+::: card .hl-panel
+### HTML
+
+```html
+<main class="wide">
+  <a class="btn primary" href="/docs/">Read the docs</a>
+</main>
+```
+:::
+
+:::
+
+::: hl-note
+**How it works.** The highlighter is [highlight.js](https://highlightjs.org/),
+wired into Markdown's fenced-code path and mapped onto `$code-*` skin tokens.
+The stylesheet is **pay-for-what-you-use** — emitted and linked only on pages
+with a highlighted block. The highlighting itself ships zero JavaScript; the only
+reactive thing on this page is the theme toggle above (so you can demo the
+recolor without changing your OS setting). A fence with an unknown or absent
+language renders as plain escaped `<code>`, and inline `` `code` `` is never
+highlighted.
+:::
+
+::: hl-note .hl-degrade
+**Graceful degradation.** A bare fence (no language) or an unknown one stays
+plain — no highlighting, no error:
+
+```
+just a plain block — no language, so no highlighting
+```
+:::
+
+:::
+
+</main>

package/site/pages/index.wd

@@ -2,6 +2,7 @@
 title: Darkmown — Markdown that runs, not Markdown that needs React
 description: A live store widget — search filter, add-to-cart, running total — written as one Markdown file that runs. The same outcome in Markdoc needs a React component, hydration, and a build step. Compare them side by side.
 image: https://darkmown.com/__wd/media/og.png
+site_url: https://darkmown.com
 transitions: true
 ---