@zvndev/darkmown 2.9.0 → 2.10.1

package/site/pages/benchmarks/index.wd

@@ -0,0 +1,126 @@
+---
+title: Benchmarks: a production Next.js site, rebuilt in Markdown
+description: We rebuilt a live production marketing site (Next.js 16, React 19, Tailwind, Vercel) in Darkmown and measured both sides. Same copy, same images, same CMS. A tenth of the JavaScript, a third of the requests, and the two places the rebuild lost, stated plainly.
+image: https://darkmown.com/__wd/media/og.png
+site_url: https://darkmown.com
+transitions: true
+schema: TechArticle
+---
+
+@include /nav.wd
+@include /base.wd
+
+::: main
+
+::: eyebrow
+Benchmarks
+:::
+
+# Same site. Same copy. A tenth of the JavaScript.
+
+We took a live production marketing site, a multi-location dental practice running **Next.js 16, React 19, and Tailwind on Vercel**, and rebuilt it in Darkmown: same copy, same images, same fonts, same CMS content pipeline. Then we measured both. This page is every number we found, including the two categories where the rebuild is worse.
+
+The rebuild lives in a private demo repository, so there is no source link; every figure below is the median of three measured page loads, and the [methodology](#methodology) section says exactly how we measured.
+
+## The headline numbers
+
+::: stats
+
+::: stat
+10x
+::: statlabel
+less JavaScript on the homepage: 22 KB against 225 KB, raw bytes against compressed. Gzip to gzip it is 28x.
+:::
+:::
+
+::: stat
+3.3x
+::: statlabel
+fewer requests per page: 11 to 20 across the four measured routes, against 46 to 70.
+:::
+:::
+
+::: stat
+5.6x
+::: statlabel
+smaller HTML document: 56.7 KB raw against 318 KB. Compressed both ways, still 2.4x leaner.
+:::
+:::
+
+::: stat
+~6x
+::: statlabel
+faster full builds: 2.7 to 3.6 seconds for 67 routes, against 16.6 s cold and 23.2 s warm.
+:::
+:::
+
+:::
+
+## What every page pays
+
+| | Next.js on Vercel | Darkmown rebuild |
+|---|---|---|
+| JavaScript per page | 225 to 227 KB compressed, 16 chunks | 18 to 23 KB total (the whole runtime is 6.6 KB gzipped) |
+| Requests per page | 46 to 70 | 11 to 20 |
+| Homepage HTML document | 318 KB raw, 24.9 KB brotli | 56.7 KB raw, 10.6 KB gzip |
+| Third-party JavaScript | ~357 KB (Google Tag Manager, DoubleClick) | 0 B |
+
+Two things worth saying out loud. The live site sends the **same 16 chunks, byte-identical, on all four measured routes**: whatever route-level code splitting Next.js is doing never showed up, so every page pays the full 226 KB. And the Darkmown column is raw bytes off an uncompressed preview server while the Next.js column is compressed transfer, so the real gap is wider than the table shows.
+
+## Route by route
+
+::: tablewrap
+
+| Route | JS: Next.js | JS: Darkmown | Requests: Next.js | Requests: Darkmown | Total wire: Next.js | Total wire: Darkmown |
+|---|---|---|---|---|---|---|
+| `/` | 225 KB | 22 KB | 50 | 15 | 2.16 MB | 1.79 MB |
+| `/services/dental-implants/` | 226 KB | 18 KB | 54 | 12 | 828 KB | 793 KB |
+| `/doctors/` | 227 KB | 18 KB | 70 | 20 | 965 KB | **1.69 MB** |
+| `/request-appointment/` | 226 KB | 23 KB | 46 | 11 | 784 KB | 678 KB |
+
+:::
+
+The doctors route is the one page where the rebuild's total wire bytes are **higher**, and it is not a rounding error: the rebuild shipped unoptimized headshots where the live site serves CDN width variants. That is the next section.
+
+## Build time and source size
+
+Measured on the same machine, 67 routes on both sides:
+
+| | Next.js 16 | Darkmown |
+|---|---|---|
+| Cold build | 16.6 s | 2.7 to 3.6 s |
+| Warm build | 23.2 s | 2.7 to 3.6 s (there is no build cache) |
+| CPU time per build | ~30 s | ~0.6 s |
+
+| | Next.js project | Darkmown rebuild |
+|---|---|---|
+| Maintained source | ~33,000 lines (24.5k code + 8.4k CMS JSON) | 17,300 lines total |
+| Project on disk | 39 MB | 5.5 MB |
+| `node_modules` | 932 MB | 15 MB (62x smaller) |
+
+## Where Darkmown loses
+
+Both of these were real losses on measured bytes, not hypotheticals, and both shaped what shipped next.
+
+- **Fonts, badly.** The rebuild served three raw variable TTFs: 1.07 MB on the homepage, against `next/font`'s 158 KB of subset woff2. Fonts were the single largest byte category on every rebuilt page. The 2.8 documentation shipped a font recipe (convert to woff2, subset to the glyphs used, `font-display swap`, preload the critical face), and 2.10 closes the gap outright: with the optional toolchain installed, the build subsets project-local fonts to the site's charset automatically. Measured on these same demo fonts, the 1.07 MB of TTFs became 288 KB of woff2.
+- **Photos.** The doctors page shipped 1,045 KB of headshots against the live site's 147 KB of CDN width variants. Darkmown 2.8 added the `@width` convention (drop in `photo@640.jpg` and the build wires the `srcset`), and 2.9 generates those variants at build time when sharp is installed. Run the same rebuild today and this category flips.
+- **A shared cost neither side avoids:** both sites load the same ~594 KB hero video on the homepage. No edge for anyone there.
+
+## Methodology
+
+- Measured on 2026-10-13 with Chromium via Playwright: 1280x900 desktop viewport, cache disabled, three fresh loads per URL, median reported. Wire bytes are CDP `encodedDataLength`, which is compressed transfer size plus response headers.
+- The live site runs on Vercel's edge network; the rebuild was measured from a local static build (`darkmown serve`). Local timings reflect zero network latency, so **we do not compare timing columns at all**. Bytes and request counts are the fair comparison.
+- The preview server did not compress responses in this run, so the rebuild's text wire bytes overstate what the same `dist/` transfers behind a compressing host: its homepage HTML is 57.4 KB on the wire but 10.6 KB gzipped, and any Vercel or Cloudflare deploy of the same output gets brotli and edge caching for free.
+- Four routes measured out of 67. The content pipeline is identical on both sides: the same Capa CMS snapshot drives both sites, and the Darkmown sync regenerates its 41 managed pages byte-identically in 0.05 s.
+- **What Next.js does that Darkmown does not:** server rendering, streaming, per-request personalization, edge caching, an image CDN, and automatic font subsetting. This site exercises none of the dynamic ones; its pages are the same for every visitor, which is exactly the case a static build exists for. Where Next.js's automatic asset optimization (fonts, responsive images) would win, it did win, and that is the section above.
+- Whether a production dental site keeps Google Tag Manager is a business decision, not a framework property. The rebuild demonstrates the site works without it, and the ~357 KB saving is stated as such.
+
+::: bench-cta
+[Read the docs](/docs/){.btn .primary}
+[Try Darkmown in your browser](/playground/){.btn}
+[Darkmown vs. Markdoc](/vs/markdoc/){.btn}
+:::
+
+:::
+
+@include /footer.wd

package/site/pages/docs/index.wd

@@ -60,6 +60,7 @@ Darkmown is a Markdown-native framework for mostly-static sites with tiny reacti
 - [Compile error codes](#compile-error-codes)
 - [CLI reference](#cli-reference)
 - [Editor support](#editor-support)
+- [Benchmarks](#benchmarks)
 - [Accessibility](#accessibility)
 - [Security](#security)
 - [Limits](#limits)
@@ -116,6 +117,44 @@ A directive is a whole line, written flush against the left margin. Four rules c
 - `with title={ feature.title }` passes a value already in scope — including whole objects.
 - Includes inside a loop inherit the loop value automatically.
 
+An include declares fallbacks for its `with` arguments in its own frontmatter with `defaults: [title="Untitled", cta="Learn more"]`. The caller's `with` value always wins; the default fills in when the caller is silent; an argument with neither renders as literal `{ title }` text, as before. Values are strings (frontmatter is string-typed), entries split on top-level commas only (so `cta="Learn more, today"` works), and a malformed `defaults:` is `[WD613]`.
+
+The block form turns an include into a wrapper component. The lines between the call and `@endinclude` compile once in the **caller's** scope (its `:state`, and the loop item inside a `@loop`) and land wherever the include puts a standalone `{ children }` line:
+
+```wd
+@include /card.wd with title="Pricing"
+
+Everything in **this paragraph** is the card body.
+
+@endinclude
+```
+
+with `site/_/card.wd`:
+
+```wd
+---
+defaults: [title="Untitled"]
+---
+
+::: card
+## { title }
+
+{ children }
+:::
+```
+
+The slot is a standalone line only (mid-paragraph or fenced `{ children }` stays literal; on a top-level page it is literal too; a `.md` include cannot host one). Called without a block, the slot renders empty; a block given to an include that never uses `{ children }` is dropped with a build warning. `@endinclude` closes the nearest preceding unpaired `@include`, so an inline `@include` written between opener and closer consumes the pairing; one level of block nesting is supported (deeper is `[WD616]`), and a stray closer is `[WD614]`. There is deliberately no unclosed-block error: an unpaired opener is the inline form, and the inline form must stay legal. Per-row components in a loop are the payoff, and stay zero-JS over a static source:
+
+```wd
+@loop /products.json into product
+@include /card.wd with title={ product.name }
+
+Price: { product.price | money }
+
+@endinclude
+@endloop
+```
+
 ## Loops
 
 `@loop <things> into <thing>` is the only loop. The body is normal Markdown (or more directives) and repeats once per row:
@@ -861,6 +900,8 @@ Two CSS at-rules compile as self-contained blocks in a `.skin`, because their in
 
 `@font-face` takes plain declarations, several blocks per skin allowed. `@keyframes <name>` requires a plain identifier; each indented child is a keyframe selector (`from`, `to`, a percentage, or a comma list) with its declarations one level deeper, and anything else is a compile error, so a keyframe selector is never misread as a declaration. Aliases and `$token` refs work inside both, both can nest under an `@media` line (the home for `prefers-reduced-motion` animation guards), and both stay **global** in a `scoped` skin, same as `tokens` blocks.
 
+**Build-time font subsetting.** With the wasm toolchain installed (`npm i -D harfbuzzjs wawoff2`, both optional dependencies), a post-pass subsets every project-local `.ttf`/`.otf`/`.woff` referenced by an `@font-face src url(...)` to the site's character set (every code point in the emitted HTML, plus a base set of ASCII, Latin-1, punctuation, arrows, and ★ ☆ ✓ ✕ ✗), encodes it as woff2, emits `<name>-subset.woff2` beside the original, and rewrites the dist CSS so `src:` lists the subset first; the source `.skin` is never touched, and layout features and variable axes survive. Without the toolchain the build is unchanged plus one hint per build, a font that fails to parse ships as-is with its own hint, and the build never fails over a font. Subsets cache in `node_modules/.cache/darkmown-fonts/` keyed by font and charset hashes, and the CSS rewrite is idempotent, so incremental dev builds are safe. The build summary reports `fonts (3 subsetted, 0 cached)` when the post-pass did work.
+
 ## Inline attributes
 
 A trailing `{.class .class #id}` attaches classes or an id to the inline element directly before it, most often to style a link as a button without a wrapper:
@@ -1010,6 +1051,10 @@ The `darkmown` command (installed by `npx @zvndev/darkmown`) is the whole tool
 
 A [VS Code extension](https://github.com/ZVN-DEV/darkmown/tree/master/editors/vscode) gives `.wd` and `.skin` files syntax highlighting, snippets, and folding, so a `.wd` file reads as Markdown-plus-directives instead of broken Markdown. Build a `.vsix` from the framework repo and install it with `code --install-extension`; a Marketplace listing is pending.
 
+## Benchmarks
+
+A live production marketing site (Next.js 16, React 19, Tailwind, on Vercel) was rebuilt in Darkmown with the same copy, images, and CMS content pipeline, then both sides were measured (median of three loads, four matched routes): 225-227 KB of compressed JavaScript on every Next.js page vs 18-23 KB total in Darkmown, 46-70 requests vs 11-20, and full builds of 16.6 s cold / 23.2 s warm vs 2.7-3.6 s for all 67 routes. The rebuild lost two categories honestly: raw TTF fonts (1.07 MB vs 158 KB of subset woff2) and unoptimized photos (1,045 KB vs 147 KB of CDN width variants), both addressed by the 2.8/2.9 font recipe and build-time responsive images. The full tables, the per-route breakdown, and the methodology are at [/benchmarks/](/benchmarks/).
+
 ## Accessibility
 
 Landmark and announcement basics are baked in at build time, so they cost zero JavaScript and a static page stays static:
@@ -1042,7 +1087,7 @@ Builds emit security response headers, so a deployed site gets sane defaults wit
 - **`X-Content-Type-Options: nosniff`**, a **`Referrer-Policy`**, and a **`frame-ancestors`** directive (clickjacking protection) on every page.
 - A raw inline `<script>` you write into an `html: true` page is blocked by that policy. Put it in a colocated `.js` file (same-origin, allowed by `'self'`) or widen `script-src` deliberately.
 - Calling another host with `:fetch` or `:form action=`? Widen `connect-src` (and `form-action` for a native form POST) in your deploy config. It is not derived from your page sources.
-- The two embed origins (`youtube-nocookie.com`, `player.vimeo.com`) and `media-src 'self' https:` are pre-authorized, so `:embed` and remote media work out of the box.
+- The two built-in embed origins (`youtube-nocookie.com`, `player.vimeo.com`) are pre-authorized on every page, and any other `:embed` host is unioned into `frame-src` for exactly the pages that embed it, so a third-party booking or checkout iframe works under the shipped headers. `media-src 'self' https:` is unchanged, so `:embed` and remote media work out of the box. The per-route union ships in Cloudflare's `dist/_headers` and is honored by `darkmown serve`; Vercel reads `vercel.json` before the build, so on Vercel you widen `frame-src` in your own `vercel.json` for a non-YouTube/Vimeo host.
 
 ## Limits
 
@@ -1068,7 +1113,7 @@ Darkmown is small on purpose. Here is what it deliberately refuses and what it g
 - **Reactive rows cannot fill a Markdown table.** A reactive row is cloned into a `<div>`, which is not a legal child of `<table>`, so `[WD191]` refuses it. Static loops fill tables fine; for reactive rows, build them from containers (`::: trow` / `::: td`) and style them as a table.
 - **No i18n beyond `lang:`.** No `hreflang`, no message catalog, no ambient locale, no locale routing. A multilingual site means duplicating the tree per locale.
 - **Every framework asset URL is absolute** (`/__wd/...`), so a Darkmown site cannot be mounted at a subpath. It is all-or-nothing per origin.
-- **Includes are macros, not components.** No children, no slots, no default arguments, and a missing argument renders `{ title }` literally rather than erroring.
+- **Includes are macros, not components.** One slot (`{ children }`), string-typed `defaults:` fallbacks, and no props interface beyond `with`; a missing argument with no default still renders `{ title }` literally rather than erroring.
 - **No `darkmown test`.** There is no built-in way to assert your own site's behavior. Use [`compileFromMemory`](#programmatic-compile-compilefrommemory) or a browser test runner.
 
 **Migrating out is easy, and that is on purpose.** `dist/` is portable static HTML plus one runtime file of ~6.6 KB gzipped. No server to port, no proprietary component format, no framework baked into the output. Point any host at the folder, or hand it to whatever you move to next, and the site keeps working.

package/site/pages/index.wd

@@ -188,6 +188,7 @@ The echo endpoint is only live on the deployed site: { reply_error }
 [Deploy to Vercel](https://vercel.com/new/clone?repository-url=https%3A%2F%2Fgithub.com%2FZVN-DEV%2Fdarkmown){.btn .primary}
 [Read the docs](/docs/){.btn}
 [How it compares to Markdoc](/vs/markdoc/){.btn}
+[Benchmarks vs. a real Next.js site](/benchmarks/){.btn}
 :::
 
 :::