@zvndev/darkmown 1.5.0 → 2.0.1

package/src/compiler/frontmatter.js

@@ -12,13 +12,15 @@ import { stripQuotes } from "./interpolation.js";
  */
 
 /**
- * Split a raw file into its frontmatter `meta` and `body`.
+ * Split a raw file into its frontmatter `meta` and `body`. `bodyLine` is the
+ * 0-based file line index the body starts on (the number of lines the
+ * frontmatter block consumed) so compile errors can report true file lines.
  * @param {string} raw Full file contents.
  * @param {string} [file] Source path, used only for error messages.
- * @returns {{ meta: Meta, body: string }}
+ * @returns {{ meta: Meta, body: string, bodyLine: number }}
  */
 export function parseFrontmatter(raw, file) {
-  if (!raw.startsWith("---\n")) return { meta: {}, body: raw };
+  if (!raw.startsWith("---\n")) return { meta: {}, body: raw, bodyLine: 0 };
   const end = raw.indexOf("\n---", 3);
   if (end === -1) {
     const where = file ? ` in ${file}` : "";
@@ -27,14 +29,17 @@ export function parseFrontmatter(raw, file) {
     );
   }
   const front = raw.slice(4, end).trim();
-  const body = raw.slice(end + 4).replace(/^\n/, "");
+  let bodyStart = end + 4;
+  if (raw[bodyStart] === "\n") bodyStart++;
+  const body = raw.slice(bodyStart);
+  const bodyLine = raw.slice(0, bodyStart).split("\n").length - 1;
   /** @type {Meta} */
   const meta = {};
   for (const line of front.split("\n")) {
     const match = line.match(/^([A-Za-z0-9_-]+):\s*(.*)$/);
     if (match) meta[match[1]] = parseFrontmatterValue(match[2]);
   }
-  return { meta, body };
+  return { meta, body, bodyLine };
 }
 
 /**

package/src/compiler/includes.js

@@ -1,7 +1,8 @@
 // ---------------------------------------------------------------------------
 // Includes / assets: resolve `@include` (and `@loop` data) targets to absolute
 // paths inside `site/pages` or `site/_`, register colocated `.skin`/`.js`
-// siblings, and warn when a plain `.md` file uses `.wd`-only syntax.
+// siblings, detect scoped skins and stamp their subtree HTML (`stampScope`),
+// and warn when a plain `.md` file uses `.wd`-only syntax.
 // ---------------------------------------------------------------------------
 
 import fs from "node:fs";
@@ -57,6 +58,70 @@ export function scopedSkinFor(file, context) {
   return scopeInfoForSkin(candidate, context.cwd);
 }
 
+/**
+ * Raw-text (`script`, `style`) and escapable-raw-text (`textarea`, `title`)
+ * elements per the HTML spec: their CONTENT is not markup, so `<`/`>` inside them
+ * are plain characters and must never be treated as tags. The content runs to the
+ * first matching close tag.
+ * @type {Set<string>}
+ */
+const RAW_TEXT_ELEMENTS = new Set(["script", "style", "textarea", "title"]);
+
+/**
+ * Stamp `data-wd-scope="<id>"` onto every opening tag of a subtree — the HTML
+ * half of compile-time scoped styles, mirroring {@link enhanceImages}: a
+ * compile-time post-pass over assembled HTML, zero runtime JS. Every element
+ * start tag that doesn't already carry a scope attribute gets one, so the scoped
+ * stylesheet (whose selectors end in `[data-wd-scope="<id>"]`) matches inside
+ * this subtree and nowhere else. Void/self-closing tags are stamped too (the
+ * attribute is valid on any element). Closing tags, comments, doctype, and the
+ * `<!`/`<?` families are left alone. A tag that ALREADY has a `data-wd-scope`
+ * (e.g. a nested include with its own scope) keeps its own — first stamp wins.
+ *
+ * Raw-text / escapable-raw-text elements (`script`, `style`, `textarea`,
+ * `title`) are special-cased: their OPENING tag is stamped (valid), but their
+ * BODY is left byte-intact — `<`/`>` inside a `<script>` are JavaScript, not
+ * markup, so stamping there would corrupt the content. A small tokenizer walks
+ * tag-by-tag (quote-aware in attribute lists) and, on entering a raw-text
+ * element, copies through verbatim until the matching close tag.
+ * @param {string} html Subtree HTML to scope.
+ * @param {string} scopeId Scope id (from {@link import("../skin.js").scopeIdFor}).
+ * @returns {string}
+ */
+export function stampScope(html, scopeId) {
+  // Opening tag: name + (quote-aware) attribute list + optional self-close slash.
+  const openTag = /<([a-zA-Z][\w-]*)((?:[^>"']|"[^"]*"|'[^']*')*?)(\/?)>/g;
+  let out = "";
+  let cursor = 0;
+  for (let m = openTag.exec(html); m; m = openTag.exec(html)) {
+    const [tag, name, attrs, slash] = m;
+    out += html.slice(cursor, m.index); // text/markup before this opening tag
+    const stamped = /\bdata-wd-scope\s*=/.test(attrs)
+      ? tag // first stamp wins — a pre-stamped tag keeps its own scope
+      : `<${name}${attrs} data-wd-scope="${scopeId}"${slash ? " /" : ""}>`;
+    out += stamped;
+    cursor = m.index + tag.length;
+
+    // Raw-text element (not self-closed): copy its body through untouched and
+    // resume scanning after the matching close tag, so nothing inside is stamped.
+    if (!slash && RAW_TEXT_ELEMENTS.has(name.toLowerCase())) {
+      const rest = html.slice(cursor);
+      const closeMatch = new RegExp(`</${name}\\s*>`, "i").exec(rest);
+      if (!closeMatch) {
+        out += rest; // unterminated raw-text element — copy the remainder verbatim
+        cursor = html.length;
+        break;
+      }
+      const through = closeMatch.index + closeMatch[0].length; // body + close tag
+      out += rest.slice(0, through); // byte-intact
+      cursor += through;
+      openTag.lastIndex = cursor; // skip the body the scanner would otherwise re-walk
+    }
+  }
+  out += html.slice(cursor); // trailing text after the last opening tag
+  return out;
+}
+
 /**
  * Register a page's colocated `.skin`/`.js` siblings as emitted assets.
  * @param {string} file
@@ -93,9 +158,13 @@ export function collectColocatedAssets(file, context, assets) {
  * @param {string} fromFile File requesting the include.
  * @param {Paths} context
  * @param {boolean} [allowAny] Allow non-page extensions (e.g. JSON for `@loop`).
+ * @param {string} [loc] Source location (`file:line`) for the error messages, so
+ *   an unresolved/out-of-sandbox include reports the directive's line. Callers
+ *   with a line index pass `at(ctx, index)`; it defaults to `fromFile` (the bare
+ *   path) for any caller without one, preserving the file-only message.
  * @returns {string}
  */
-export function resolveInclude(spec, fromFile, context, allowAny = false) {
+export function resolveInclude(spec, fromFile, context, allowAny = false, loc = fromFile) {
   const clean = stripQuotes(spec);
   const candidates = [];
   if (clean.startsWith("/")) {
@@ -107,13 +176,15 @@ export function resolveInclude(spec, fromFile, context, allowAny = false) {
   for (const candidate of candidates) {
     const resolved = path.resolve(candidate);
     if (!isAllowedInclude(resolved, context)) {
-      throw new Error(`Include "${spec}" from ${fromFile} resolves outside site/pages or site/_`);
+      throw new Error(`Include "${spec}" from ${loc} resolves outside site/pages or site/_`);
     }
     if (!fs.existsSync(resolved)) continue;
     if (!allowAny && !pageIncludeExtensions.includes(path.extname(resolved))) continue;
     return resolved;
   }
-  throw new Error(`Could not resolve include "${spec}" from ${fromFile}`);
+  throw new Error(
+    `Could not resolve include "${spec}" from ${loc}. Looked in site/pages and site/_ — check the path and leading slash.`
+  );
 }
 
 /**

package/src/compiler/index.js

@@ -4,20 +4,32 @@
 //   context.js        shared typedefs + tiny helpers (createCompilation, at, …)
 //   interpolation.js  path/value resolution, state-key lookup, escapeHtml, literals
 //   frontmatter.js    `---` block → meta + body, inline scalar/array parsing
-//   includes.js       @include / @loop-data resolution, colocated assets, .md hints
+//   includes.js       @include / @loop-data resolution, colocated assets,
+//                     scoped-skin detection + the HTML scope stamp, .md hints
 //   predicates.js     where / when / :if / :computed expression compilers
 //   format.js         { value | pipe } format pipes + list aggregates (value layer)
 //   markdown.js       markdown-it instances + plugins + prose interpolation
+//   state.js          :state / :store / :computed / :theme + declare* helpers
+//   actions.js        the :button action parser + :button / :effect / :every
+//   fetch.js          :fetch + the shared URL scheme guard
+//   forms.js          :form + field directives + :bind / :slider
+//   media.js          :video / :audio / :embed
+//   structure.js      @include / ::: container / :if / :carousel + demo directives
+//   directives.js     barrel re-exporting the handle* family from the six above
 //   loops.js          @loop pipeline + row-template initial-paint fill
-//   directives.js     the handle* family + :button action parser + demo directives
 //   body.js           the line-based directive dispatcher (compileBody)
 //   page.js           HTML page shell, image hardening, per-file compile
 //
+// Handlers recurse into nested bodies through `ctx.compileBody` (and `@include`
+// through `ctx.compileFile`), threaded in by `compileFile` — so the graph is an
+// import-cycle-free DAG rooted at context.js.
+//
 // This barrel re-exports the public API; `src/compiler.js` re-exports from here
 // so every existing `import … from "./compiler.js"` keeps working unchanged.
 // ---------------------------------------------------------------------------
 
 export { parseFrontmatter } from "./frontmatter.js";
+export { stampScope } from "./includes.js";
 export { escapeHtml } from "./interpolation.js";
 export { loopKeyOf } from "./loops.js";
-export { compileDocument, compilePage, enhanceImages, stampScope } from "./page.js";
+export { compileDocument, compilePage, enhanceImages } from "./page.js";

package/src/compiler/loops.js

@@ -7,8 +7,7 @@
 // ---------------------------------------------------------------------------
 
 import fs from "node:fs";
-import { compileBody } from "./body.js";
-import { createScope } from "./context.js";
+import { at, createScope, nestedCtx } from "./context.js";
 import { applyPipeline, stagesFromAttr } from "./format.js";
 import { resolveInclude } from "./includes.js";
 import {
@@ -213,11 +212,14 @@ function numArgAttr(arg) {
  * @param {string[]} bodyLines
  * @param {string[] | null} emptyLines
  * @param {Ctx} ctx
+ * @param {number} index 0-based line index of the `@loop` opener.
+ * @param {number} [emptyStart] 0-based index the empty branch starts at within
+ *   the loop body, so its nested errors report the true file line.
  * @returns {string}
  */
-export function handleLoop(line, bodyLines, emptyLines, ctx) {
+export function handleLoop(line, bodyLines, emptyLines, ctx, index, emptyStart = 0) {
   const match = line.match(/^@loop\s+(.+?)\s+into\s+([A-Za-z_$][\w$]*)(\s+.+?)?\s*$/);
-  if (!match) throw new Error(`Malformed @loop in ${ctx.file}: ${line}. ${LOOP_USAGE}`);
+  if (!match) throw new Error(`Malformed @loop in ${at(ctx, index)}: ${line}. ${LOOP_USAGE}`);
   const source = stripQuotes(match[1].trim());
   const itemName = match[2];
   const clauses = match[3]
@@ -265,10 +267,19 @@ export function handleLoop(line, bodyLines, emptyLines, ctx) {
     offset: clauses.offset,
     limit: clauses.limit,
     empty: emptyLines,
+    emptyStart,
     clauseRefsState: clauses.refsState,
     sortable: clauses.sortable,
     paginate: clauses.paginate
   };
+  // The loop body starts on the line after the opener; nested errors in it (and
+  // in the empty branch, via `opts.emptyStart`) report the true file line. The
+  // opener's location rides on the body ctx so a reactive loop nested inside this
+  // one can point the depth error back at its own opener line.
+  const bodyCtx = {
+    ...nestedCtx(ctx, index + 1),
+    loopOpener: { at: at(ctx, index), line: line.trim() }
+  };
 
   if (
     source.startsWith("/") ||
@@ -277,21 +288,29 @@ export function handleLoop(line, bodyLines, emptyLines, ctx) {
     source.endsWith(".json")
   ) {
     if (opts.paginate) throw new Error(paginateOnlyCollections(ctx));
-    const dataFile = resolveInclude(source, ctx.file, ctx.context, true);
+    const dataFile = resolveInclude(source, ctx.file, ctx.context, true, at(ctx, index));
+    ctx.comp.deps.add(dataFile);
     const rows = JSON.parse(fs.readFileSync(dataFile, "utf8"));
     if (!Array.isArray(rows)) throw new Error(`@loop data must be a JSON array: ${dataFile}`);
-    return loopOverData(rows, itemName, bodyLines, ctx, opts);
+    return loopOverData(rows, itemName, bodyLines, bodyCtx, opts);
   }
 
   const resolved = lookupPath(source, ctx);
   if (resolved.found) {
     if (opts.paginate) throw new Error(paginateOnlyCollections(ctx));
+    // A missing/unset field (e.g. an optional frontmatter key) is an EMPTY
+    // list, not an error — the `@empty` branch renders, matching the runtime.
+    if (resolved.value === null || resolved.value === undefined) {
+      return loopOverData([], itemName, bodyLines, bodyCtx, opts);
+    }
     if (!Array.isArray(resolved.value)) {
       throw new Error(
-        `@loop ${source} in ${ctx.file} found an in-scope value, but it is not a list`
+        `@loop ${source} in ${at(ctx, index)} found an in-scope value, but it is not a list ` +
+          `(got ${typeof resolved.value}). Use: a list value (e.g. \`tags: [a, b]\` in frontmatter) — ` +
+          `or leave the field out entirely, which loops zero rows and renders the @empty branch.`
       );
     }
-    return loopOverData(resolved.value, itemName, bodyLines, ctx, opts);
+    return loopOverData(resolved.value, itemName, bodyLines, bodyCtx, opts);
   }
 
   // A bare name OR a dotted path resolving to declared :state (e.g. team.members).
@@ -304,13 +323,16 @@ export function handleLoop(line, bodyLines, emptyLines, ctx) {
     if (key) {
       if (opts.paginate) throw new Error(paginateOnlyCollections(ctx));
       const fullKey = segs.length > 1 ? `${key}.${segs.slice(1).join(".")}` : key;
-      return reactiveLoop(fullKey, itemName, bodyLines, ctx, opts);
+      return reactiveLoop(fullKey, itemName, bodyLines, bodyCtx, opts);
     }
     // A bare name matching a collection (any `site/pages/<name>/` subdir) resolves
     // to its entry rows at build time and static-unrolls — zero JS. This is checked
     // after state so a declared `:state` of the same name still wins.
     const collection = segs.length === 1 ? ctx.comp.collections.get(source) : undefined;
-    if (collection) return loopOverCollection(collection, source, itemName, bodyLines, ctx, opts);
+    if (collection) {
+      ctx.comp.collectionsUsed.add(source);
+      return loopOverCollection(collection, source, itemName, bodyLines, bodyCtx, opts);
+    }
     // Inside a reactive loop, `@loop <outerItem>.<path> into x` loops a field of
     // the enclosing row item — an ITEM-RELATIVE loop the runtime fills per row.
     if (ctx.loopItem && segs[0] === ctx.loopItem && segs.length > 1) {
@@ -320,7 +342,7 @@ export function handleLoop(line, bodyLines, emptyLines, ctx) {
         );
       }
       if (opts.paginate) throw new Error(paginateOnlyCollections(ctx));
-      return itemRelativeLoop(segs.slice(1).join("."), itemName, bodyLines, ctx, opts);
+      return itemRelativeLoop(segs.slice(1).join("."), itemName, bodyLines, bodyCtx, opts);
     }
   }
 
@@ -355,6 +377,27 @@ function paginateOnlyCollections(ctx) {
   return `@loop paginate requires a collection source (a site/pages/<name>/ subdirectory) in ${ctx.file}. ${LOOP_USAGE}`;
 }
 
+/**
+ * Reject a reactive `@loop` that would open a THIRD reactive nesting level. The
+ * runtime reconciles at most two nested `data-wd-loop` levels (an outer loop and
+ * one inner loop); a third level's `data-wd-loop-out` paints empty. This guards
+ * every reactive-region entry point ({@link reactiveLoop}, {@link itemRelativeLoop}),
+ * so a state-key, item-relative, or state-filtered source is all covered. Static
+ * (build-unrolled) loops carry the depth through without incrementing it, so an
+ * interleaved static level neither triggers nor masks the limit.
+ * `ctx.reactiveDepth` is the number of reactive loops already enclosing this one.
+ * @param {Ctx} ctx
+ * @returns {void}
+ */
+function assertReactiveDepth(ctx) {
+  if ((ctx.reactiveDepth ?? 0) < 2) return;
+  const opener = ctx.loopOpener ?? { at: ctx.file, line: "" };
+  throw new Error(
+    `Reactive @loop nesting is limited to one inner level in ${opener.at}: "${opener.line}". ` +
+      `Unroll the outer data at build time (JSON/frontmatter source) or move the innermost list into build-time data.`
+  );
+}
+
 /**
  * Loop over a build-time collection's entry rows. With no `paginate`, this is a
  * plain static unroll (filter/sort/reverse/offset/limit at build time, zero JS).
@@ -387,7 +430,14 @@ function loopOverCollection(rows, name, itemName, bodyLines, ctx, opts) {
   // document scope). Slice this page out of the already-filtered/sorted list.
   const current = currentPage(ctx);
   const start = (current - 1) * perPage;
-  return staticUnroll(filtered.slice(start, start + perPage), itemName, bodyLines, ctx, opts.empty);
+  return staticUnroll(
+    filtered.slice(start, start + perPage),
+    itemName,
+    bodyLines,
+    ctx,
+    opts.empty,
+    opts.emptyStart
+  );
 }
 
 /**
@@ -466,7 +516,8 @@ function loopOverData(rows, itemName, bodyLines, ctx, opts) {
     itemName,
     bodyLines,
     ctx,
-    opts.empty
+    opts.empty,
+    opts.emptyStart
   );
 }
 
@@ -476,10 +527,13 @@ function loopOverData(rows, itemName, bodyLines, ctx, opts) {
  * @param {string[]} bodyLines
  * @param {Ctx} ctx
  * @param {string[] | null} [empty] Empty-branch body, rendered when 0 rows.
+ * @param {number} [emptyStart] 0-based index the empty branch starts at within
+ *   the loop body, so its nested errors report the true file line.
  * @returns {string}
  */
-function staticUnroll(rows, itemName, bodyLines, ctx, empty = null) {
-  if (rows.length === 0 && empty) return compileBody(empty, { ...ctx, loopMeta: true });
+function staticUnroll(rows, itemName, bodyLines, ctx, empty = null, emptyStart = 0) {
+  if (rows.length === 0 && empty)
+    return ctx.compileBody(empty, { ...nestedCtx(ctx, emptyStart), loopMeta: true });
   const out = [];
   const count = rows.length;
   for (let i = 0; i < count; i++) {
@@ -495,7 +549,7 @@ function staticUnroll(rows, itemName, bodyLines, ctx, empty = null) {
       loopMeta: true,
       scope: createScope(ctx.scope, { [itemName]: rows[i], ...meta })
     };
-    out.push(compileBody(bodyLines, rowCtx));
+    out.push(ctx.compileBody(bodyLines, rowCtx));
   }
   return out.join("\n");
 }
@@ -512,6 +566,7 @@ function staticUnroll(rows, itemName, bodyLines, ctx, empty = null) {
  * @returns {string}
  */
 function reactiveLoop(key, itemName, bodyLines, ctx, opts = null) {
+  assertReactiveDepth(ctx);
   ctx.comp.assets.runtime = true;
   /** @type {Ctx} */
   const templateCtx = {
@@ -519,9 +574,10 @@ function reactiveLoop(key, itemName, bodyLines, ctx, opts = null) {
     loopItem: itemName,
     loopKey: key ?? undefined,
     loopMeta: true,
+    reactiveDepth: (ctx.reactiveDepth ?? 0) + 1,
     scope: createScope(ctx.scope)
   };
-  const templateHtml = compileBody(bodyLines, templateCtx).trim();
+  const templateHtml = ctx.compileBody(bodyLines, templateCtx).trim();
 
   const { wrapperTag, itemTemplate } = wrapRowTemplate(templateHtml);
 
@@ -577,10 +633,12 @@ function reactiveLoop(key, itemName, bodyLines, ctx, opts = null) {
     })
     .join("");
 
-  const emptyTemplate = loopEmptyTemplate(emptyLines, ctx);
+  const emptyTemplate = loopEmptyTemplate(emptyLines, ctx, opts?.emptyStart);
   const initialOut =
     count === 0 && emptyLines
-      ? compileBody(emptyLines, { ...ctx, loopMeta: true }).trim()
+      ? ctx
+          .compileBody(emptyLines, { ...nestedCtx(ctx, opts?.emptyStart ?? 0), loopMeta: true })
+          .trim()
       : initial;
 
   // `sortable` tags the region for the drag-reorder behavior (emitted only here)
@@ -615,11 +673,13 @@ function wrapRowTemplate(templateHtml) {
  * there is no empty branch). Shared by top-level and item-relative loops.
  * @param {string[] | null} emptyLines
  * @param {Ctx} ctx
+ * @param {number} [emptyStart] 0-based index the empty branch starts at within
+ *   the loop body, so its nested errors report the true file line.
  * @returns {string}
  */
-function loopEmptyTemplate(emptyLines, ctx) {
+function loopEmptyTemplate(emptyLines, ctx, emptyStart = 0) {
   return emptyLines
-    ? `<template data-wd-loop-empty>${compileBody(emptyLines, { ...ctx, loopMeta: true }).trim()}</template>`
+    ? `<template data-wd-loop-empty>${ctx.compileBody(emptyLines, { ...nestedCtx(ctx, emptyStart), loopMeta: true }).trim()}</template>`
     : "";
 }
 
@@ -657,6 +717,7 @@ function loopClauseAttrs(c) {
  * @returns {string}
  */
 function itemRelativeLoop(path, itemName, bodyLines, ctx, opts) {
+  assertReactiveDepth(ctx);
   /** @type {Ctx} */
   // loopKey: undefined — an item-relative loop's source is a path off the outer
   // row, not a top-level state key, so a per-row `remove` inside it has no valid
@@ -666,13 +727,14 @@ function itemRelativeLoop(path, itemName, bodyLines, ctx, opts) {
     loopItem: itemName,
     loopKey: undefined,
     loopMeta: true,
+    reactiveDepth: (ctx.reactiveDepth ?? 0) + 1,
     scope: createScope(ctx.scope)
   };
-  const templateHtml = compileBody(bodyLines, templateCtx).trim();
+  const templateHtml = ctx.compileBody(bodyLines, templateCtx).trim();
 
   const { wrapperTag, itemTemplate } = wrapRowTemplate(templateHtml);
 
-  const emptyTemplate = loopEmptyTemplate(opts.empty || null, ctx);
+  const emptyTemplate = loopEmptyTemplate(opts.empty || null, ctx, opts.emptyStart);
   const attrs = loopClauseAttrs({
     where: opts.where || null,
     sort: opts.sort || null,

package/src/compiler/markdown.js

@@ -1,6 +1,6 @@
 // ---------------------------------------------------------------------------
-// Markdown layer: the shared markdown-it instances (raw-HTML default + a lazy
-// `html: false` strict variant), the `wd_binding` inline plugin and `wd_attrs`
+// Markdown layer: the shared markdown-it instances (strict default + a lazy
+// `html: true` raw-HTML variant), the `wd_binding` inline plugin and `wd_attrs`
 // core plugin, and prose rendering with `{ name.path }` interpolation resolved
 // against the loop item / static scope / declared state.
 // ---------------------------------------------------------------------------
@@ -26,29 +26,33 @@ import {
 // with a known language. The callback returns escaped token HTML or `""` to let
 // markdown-it render a plain escaped `<code>` (graceful degradation). Both
 // instances share it so `html: false` pages highlight too.
-const md = new MarkdownIt({ html: true, highlight: highlightCode });
+const md = new MarkdownIt({ html: false, highlight: highlightCode });
 md.use(bindingPlugin);
 md.use(attrsPlugin);
+md.use(anchorPlugin);
 
-// Raw HTML in markdown passes through by default (a documented design choice).
-// Pages can opt out with frontmatter `html: false` for untrusted content; the
-// stricter instance is built lazily so the default path stays a single instance.
+// Raw HTML in markdown is escaped by default: a stray `<script>` or `onerror=`
+// attribute in content renders as inert text, so multi-author content (blog
+// collections, contributed docs) is stored-XSS-safe out of the box. A page
+// whose author writes their own HTML opts in with frontmatter `html: true`;
+// that instance is built lazily so the default path stays a single instance.
 /** @type {MarkdownIt | null} */
-let mdNoHtml = null;
+let mdRawHtml = null;
 /**
- * Pick the markdown-it instance for a page (raw HTML on by default, off with `html: false`).
+ * Pick the markdown-it instance for a page (raw HTML off by default, on with `html: true`).
  * @param {Meta} [meta]
  * @returns {MarkdownIt}
  */
 export function selectMd(meta) {
   // Frontmatter scalars stay strings (no coercion), so accept both forms.
-  if (meta?.html !== false && meta?.html !== "false") return md;
-  if (!mdNoHtml) {
-    mdNoHtml = new MarkdownIt({ html: false, highlight: highlightCode });
-    mdNoHtml.use(bindingPlugin);
-    mdNoHtml.use(attrsPlugin);
+  if (meta?.html !== true && meta?.html !== "true") return md;
+  if (!mdRawHtml) {
+    mdRawHtml = new MarkdownIt({ html: true, highlight: highlightCode });
+    mdRawHtml.use(bindingPlugin);
+    mdRawHtml.use(attrsPlugin);
+    mdRawHtml.use(anchorPlugin);
   }
-  return mdNoHtml;
+  return mdRawHtml;
 }
 
 /**
@@ -59,7 +63,8 @@ export function selectMd(meta) {
 export function renderProse(text, ctx) {
   text = resolveDestinationBindings(text, ctx);
   return (ctx.md ?? md).render(text, {
-    resolveBinding: (/** @type {string} */ expr) => resolveBindingHtml(expr, ctx)
+    resolveBinding: (/** @type {string} */ expr) => resolveBindingHtml(expr, ctx),
+    headingSlugs: ctx.comp.headingSlugs
   });
 }
 
@@ -197,6 +202,51 @@ export function attrTarget(children, i) {
   return null;
 }
 
+/**
+ * GitHub-style heading slug: lowercase, punctuation stripped (letters, numbers,
+ * whitespace, `_`, and `-` survive), each whitespace character becomes a hyphen.
+ * Punctuation-only headings fall back to `"section"` so the id is never empty.
+ * @param {string} text Plain heading text.
+ * @returns {string}
+ */
+export function slugify(text) {
+  const slug = text
+    .trim()
+    .toLowerCase()
+    .replace(/[^\p{L}\p{N}\s_-]+/gu, "")
+    .replace(/\s/gu, "-");
+  return slug || "section";
+}
+
+/**
+ * markdown-it plugin (core rule): every heading gets a stable slugified `id`
+ * so long pages are linkable without any JS. Duplicate slugs dedupe with
+ * `-1`/`-2` suffixes; the counters live in `env.headingSlugs` so a page whose
+ * prose renders in chunks (directives between headings) still dedupes across
+ * the whole document. Bindings and inline HTML inside a heading contribute no
+ * slug text — only literal text and inline code do.
+ * @param {MarkdownIt} mdInstance
+ * @returns {void}
+ */
+function anchorPlugin(mdInstance) {
+  mdInstance.core.ruler.push("wd_heading_anchors", (state) => {
+    const counts = (state.env.headingSlugs ??= new Map());
+    const tokens = state.tokens;
+    for (let i = 0; i < tokens.length; i++) {
+      if (tokens[i].type !== "heading_open") continue;
+      let text = "";
+      for (const child of tokens[i + 1].children ?? []) {
+        if (child.type === "text" || child.type === "code_inline") text += child.content;
+      }
+      const base = slugify(text);
+      const seen = counts.get(base) ?? 0;
+      counts.set(base, seen + 1);
+      tokens[i].attrSet("id", seen ? `${base}-${seen}` : base);
+    }
+    return false;
+  });
+}
+
 /**
  * Resolve a `{ name.path }` binding to HTML: loop item span, static value, or
  * a reactive bind span. Returns null when nothing in scope matches.