skill-family-doc-render 0.3.0 → 0.4.1

package/CHANGELOG.md

@@ -1,5 +1,33 @@
 # 变更日志
 
+## 0.4.1 - 2026-09-07
+
+### 变更
+
+- 与 `skill-family-docs` 和公开站点的 0.4.1 联合发布对齐版本。渲染器的公开 API、
+  命令行参数与输入合同均没有变化；相同内容输入仍生成相同的站点字节。
+
+## 0.4.0 - 2026-09-07
+
+### 新增
+
+- 增加显式成对的 `site.format: markdown-v1` 与 `site.template: editorial`。受限 Markdown
+  由精确依赖 `marked@18.0.11` 分词，再经过本包的结构、链接和锚点校验；包内模板生成
+  完整 HTML、分组目录、静态搜索、交互与首尾不循环的教程翻页。
+- 增加包内 `editorial` 模板的 CSS、JavaScript 和 SVG 图标。新模式不读取项目自有主题
+  CSS 或 JavaScript，同一冻结输入会产生确定的页面及资源字节。
+- 增加站内 SVG 主动内容检查。脚本、事件属性、`foreignObject`、DTD/实体声明，以及
+  外部或 data 资源会在输出替换前被拒绝；SVG 不内联。
+- 增加只读的 `--check-project --repo <name>`，依次检查输入与公开安全、Markdown 机械
+  合同、覆盖状态、渲染与基线、内部链接和资源，并在失败时输出可复制的恢复提示。
+
+### 安全与兼容
+
+- `site.format` 与 `site.template` 同时缺省时继续使用完整 HTML 注入。该路径只供既有
+  消费者兼容，不获得新主题；新建站点使用 `markdown-v1` 与 `editorial`。
+- `--check-project` 必须与单个 `--repo` 一起使用，不与其他模式组合。全程只读；状态
+  问题返回 1，输入或工具问题返回 2。
+
 ## 0.3.0 - 2026-09-07
 
 ### 新增

package/README.md

@@ -2,10 +2,13 @@
 
 Config-driven GitHub Pages knowledge-site renderer for skill-family projects (multi-repo capable).
 
-Reads `public-release.json` from the current working directory, renders every repo carrying a
-`site` field from its site source directory to its target directory (typically `docs/`), injects
-nav / pager / footer, replaces version placeholders, copies assets, writes `.nojekyll` and a
-tree baseline (`site-baseline.json`), and runs a content-level leak scan over every output file
+Reads `public-release.json` from the current working directory and renders every repo carrying a
+`site` field from its site source directory to its target directory (typically `docs/`). New
+sites explicitly select `format: "markdown-v1"` and `template: "editorial"`; the renderer parses
+restricted Markdown and supplies the complete page structure, navigation, theme, interactions,
+and search data. Sites without `format` keep the legacy complete-HTML injection path for
+compatibility. Both paths replace version placeholders, write `.nojekyll` and a
+tree baseline (`site-baseline.json`), and run a content-level leak scan over every output file
 (pages **and** assets) before any target change. Render, scan, baseline computation and the
 `--assert-git` preflight all finish before the target is changed, so failures in those steps
 leave the existing target untouched. The final directory commit uses Foundation's fixed-set
@@ -13,70 +16,70 @@ publication APIs. A failure before commit removes staging and leaves the existin
 untouched. After commit, or when publication is indeterminate, staging or displaced data may
 remain for diagnosis; the renderer does not guess or roll back.
 
-> **Development status:** this worktree is the unpublished `0.3.0` candidate. The latest npm
-> release is `0.2.1`; it does not contain `site.coverage`, `site.versionSources`, `--status`, or
-> `--refresh-coverage`.
+> **Version boundary:** this source tree is version `0.4.1`. Verify that exact version in the
+> official npm registry before treating it as installable. Version 0.4.1 preserves the
+> `markdown-v1`, `editorial`, and `--check-project` behavior introduced in 0.4.0 and aligns the
+> renderer, documentation plugin, and public site at 0.4.1 for the joint release.
 
 ## Install
 
-Install the current published release with an exact version:
+After confirming availability, install this release with an exact version:
 
 ```sh
-npm install --save-exact skill-family-doc-render@0.2.1
+npm install --save-exact skill-family-doc-render@0.4.1
 ```
 
 Requires Node.js `>=22.22.2 <23` (aligned with the skill-family foundation packages).
 
-The unpublished 0.3.0 candidate consumes the three Foundation packages at the exact `0.18.0` pin:
-`skill-family-contracts@0.18.0`, `skill-family-harness-node@0.18.0` and
-`skill-family-engineering-kit@0.18.0` (the last one is used by the workspace profile check).
+Version 0.4.1 has exact runtime dependencies on `marked@18.0.11`,
+`skill-family-contracts@0.18.0`, and `skill-family-harness-node@0.18.0`. `marked` supplies the
+Markdown lexer; the renderer applies its own restricted-format validation before passing semantic
+content to the template. The workspace profile check separately uses
+`skill-family-engineering-kit@0.18.0`.
 The 0.2.0 baseline format and exit-code changes are breaking changes; existing 0.1.x users
 must re-render their baseline before using `--check`. See the changelog for the full migration
 notes.
 
 ## CLI
 
-The published 0.2.1 release supports rendering, drift checks, repository selection, and the Git
-index assertion:
+Use the exact 0.4.1 CLI for rendering, checks, coverage maintenance, and the Git index assertion:
 
 ```sh
 # render all repos with a site field (writes to disk)
-npx skill-family-doc-render@0.2.1
+npx skill-family-doc-render@0.4.1
 
 # drift check only: compare in-memory render against committed site-baseline.json, write nothing
-npx skill-family-doc-render@0.2.1 --check
+npx skill-family-doc-render@0.4.1 --check
 
 # render / check a single repo by name
-npx skill-family-doc-render@0.2.1 --repo <name>
+npx skill-family-doc-render@0.4.1 --repo <name>
 
 # additionally assert every rendered file is tracked in the git index
-npx skill-family-doc-render@0.2.1 --assert-git
-```
-
-Run the unpublished 0.3.0 coverage commands from a local package checkout. The current directory
-must still be the workspace that owns `public-release.json`; adjust the script path when the
-package is nested in a monorepo:
-
-```sh
-# inspect whether reviewed product inputs have changed; writes nothing
-node bin/skill-family-doc-render.mjs --status --repo <name>
+npx skill-family-doc-render@0.4.1 --assert-git
 
-# refresh only the reviewed-input snapshot after semantic and style review
-node bin/skill-family-doc-render.mjs --refresh-coverage --repo <name>
+# inspect or refresh the reviewed product-input snapshot
+npx skill-family-doc-render@0.4.1 --status --repo <name>
+npx skill-family-doc-render@0.4.1 --refresh-coverage --repo <name>
+npx skill-family-doc-render@0.4.1 --check-project --repo <name>
 ```
 
-After 0.3.0 is published, consumers can install or invoke that exact release:
+The current directory must be the workspace that owns `public-release.json`. From this package's
+source checkout, `node bin/skill-family-doc-render.mjs` is the equivalent local CLI entry.
 
-```sh
-npm install --save-exact skill-family-doc-render@0.3.0
-npx skill-family-doc-render@0.3.0 --status --repo <name>
-```
+`--check-project` requires exactly one `--repo <name>`. It cannot be combined with `--check`,
+`--status`, `--refresh-coverage`, `--assert-git`, or `--help`. It checks input and public-content
+safety, the mechanical Markdown contract, coverage freshness, the in-memory render and baseline,
+then internal links and resources. It writes nothing. A failure identifies the repo,
+`public-release.json`, the reason, and a copyable `skill-family-docs-render-site` recovery prompt.
 
-Exit codes: `0` success; `1` drift class — `--check` drift, leak-scan hit, `--assert-git`
+Exit codes: `0` success; `1` drift/status class — `--check` drift, leak-scan hit, `--assert-git`
 missing files, missing/corrupt render baseline, or missing/stale coverage snapshot; `2`
 configuration/tool class — missing/invalid `public-release.json` or `pages.json`, JSON parse
 failures, unreplaced `@TOKEN@` placeholders, invalid `--repo` usage, invalid coverage inputs, or
-Git failure (the message includes the JSON field path). When several repos are
+Git failure (the message includes the JSON field path). `--check-project` uses the same classes:
+public-safety, coverage, render, link, or resource findings return `1`; invalid input,
+configuration, or tool errors return `2`.
+When several repos are
 rendered in one run, each repo is isolated: a failure in one does not stop the others, and the
 run ends with a summary of successes/failures plus a non-zero exit (2 if any failure was
 configuration-class, otherwise 1).
@@ -85,8 +88,8 @@ configuration-class, otherwise 1).
 
 The config file lives at the workspace root (resolved from `process.cwd()`). It is validated
 against `schemas/public-release.schema.json` (JSON Schema 2020-12, strict policy) before
-anything runs. `coverage` and `versionSources` in the example below belong to the unpublished
-0.3.0 candidate.
+anything runs. The paired `format` and `template` fields in the example below require version
+0.4.0 or later.
 
 ```json
 {
@@ -102,6 +105,8 @@ anything runs. `coverage` and `versionSources` in the example below belong to th
         "dir": "site-src",
         "target": "docs",
         "pages": "pages.json",
+        "format": "markdown-v1",
+        "template": "editorial",
         "coverage": {
           "lock": "site-coverage-lock.json",
           "inputs": ["package.json", "src/**", "schemas/**"]
@@ -128,10 +133,12 @@ anything runs. `coverage` and `versionSources` in the example below belong to th
 
 - Only repos with a `site` field are rendered; `--repo <name>` selects one by `name`
   (`--repo` without a valid value is an error, never a silent "render all").
-- `site.pages` points to a pages manifest: `{ "pages": [{ "id", "title", "order", "inPager" }] }`,
-  validated against `schemas/pages.schema.json`. Pages are sorted by `order`;
-  `inPager: false` excludes a page from the prev/next pager. Page `id` is restricted to
-  `[A-Za-z0-9][A-Za-z0-9_-]*`.
+- `site.format` and `site.template` are paired. New sites use only `markdown-v1` and `editorial`.
+  Omitting both selects the legacy HTML compatibility path.
+- `site.pages` points to a manifest validated against `schemas/pages.schema.json`. A
+  `markdown-v1` manifest declares site metadata, navigation groups, and each page's `id`, title,
+  reader role, layout kind, group, unique order, and `inPager` state. The page `id` is restricted
+  to `[A-Za-z0-9][A-Za-z0-9_-]*`.
 - `forbiddenPublicPaths` / `privateLiterals` append project-specific literals to the leak scan.
 - `site.coverage` declares reviewed product inputs relative to `repo.source`. Each input accepts
   `*` and `**` glob syntax and must match at least one file after the coverage lock itself is
@@ -141,14 +148,37 @@ anything runs. `coverage` and `versionSources` in the example below belong to th
   the scalar value without copying the version into configuration. Every referenced JSON file
   automatically joins the coverage inputs.
 
-## Placeholders
+## Input formats
+
+### Restricted Markdown and the editorial template
 
-Source pages use three HTML-comment injection points, replaced at render time:
+Each `markdown-v1` page is `site.dir/<id>.md`, with an exact one-to-one match to the manifest.
+The format supports paragraphs, level 2–4 headings, ordered and unordered lists, tables, inline
+links and emphasis, fenced code with a language, `NOTE` / `TIP` / `WARNING` callouts, and local
+SVG images. The manifest supplies the only H1. A heading may end with `{#stable-id}`; otherwise a
+deterministic slug is generated. Raw HTML, MDX, task or nested lists, indented or unlabelled code,
+ordinary blockquotes, and arbitrary attributes are rejected before output replacement.
+
+The editorial template owns HTML, CSS, JavaScript, icons, navigation, search, and the non-circular
+tutorial pager. Projects using `markdown-v1` do not supply theme CSS or JavaScript. Project images
+are limited to contained SVG files. Before rendering, SVG safety checks reject scripts, event
+attributes, `foreignObject`, DTD/entity declarations, and external or data resources; SVG remains
+an external image and is never inlined.
+
+### Legacy HTML compatibility
+
+When `format` and `template` are omitted, source pages remain complete HTML and use three comment
+injection points:
 
 - `<!--NAV-->` — table-of-contents nav (active page gets `class="active"`)
-- `<!--PAGER-->` — circular prev/next pager
+- `<!--PAGER-->` — legacy circular prev/next pager
 - `<!--FOOTER-->` — site footer (owner + license)
 
+Legacy HTML remains available for existing consumers, but it does not receive the editorial
+theme. New sites should not start on this compatibility path.
+
+## Version placeholders
+
 Version tokens are derived automatically from the repo's `package.json` version and `name`
 (uppercased, non-alphanumeric runs collapsed to `_`):
 
@@ -189,7 +219,7 @@ changes.
 
 ## Leak scan
 
-Every output file — rendered pages **and** copied assets (`.html`/`.css`/`.js`/`.svg`) — is
+Every output file — rendered pages **and** copied or template assets (`.html`/`.css`/`.js`/`.svg`) — is
 scanned **before** any write (`scripts/lib/leak-scan.mjs`). The scanner decodes HTML entities
 (two passes, defeating double encoding), JS escape sequences and URL percent-encoding first,
 then matches case-insensitively against built-in private literals (absolute home paths) and
@@ -221,8 +251,8 @@ The digest is a deterministic set-level sha256 over the contained resources.
 
 ## Foundation dependencies
 
-This package is a thin domain layer over the skill-family foundation and adds no other runtime
-dependencies:
+This package is a thin domain layer over the skill-family foundation. In addition to the two
+Foundation packages below, it uses exact `marked@18.0.11` for Markdown tokenization:
 
 - [`skill-family-harness-node`](https://github.com/ifoohoo/skill-family-harness-node) — all file
   reads go through `resolveContained` / `readFileContained` (path traversal, symlink and realpath
@@ -244,9 +274,9 @@ dependencies:
 Apache-2.0
 
 <!-- release-skill:capability:safe-first-command -->
-> **Start here:** for the unpublished 0.3.0 candidate, run
-> `node bin/skill-family-doc-render.mjs --check` from its local checkout. Published 0.2.1 users
-> can run `./node_modules/.bin/skill-family-doc-render --check`. The drift check is read-only:
+> **Start here:** run `npx skill-family-doc-render@0.4.1 --check-project --repo <name>` after
+> confirming that exact release in the official registry. From a local checkout, use
+> `node bin/skill-family-doc-render.mjs --check-project --repo <name>`. The check is read-only:
 > it renders in memory, compares against the committed `site-baseline.json`, writes
 > nothing and touches no network or credentials. The CLI performs no Git writes; only an
 > explicit `--assert-git` performs a read-only query of the Git index.
@@ -255,7 +285,7 @@ Apache-2.0
 > **External write boundary:** rendering writes the declared target and a controlled sibling
 > staging directory, both within the target's canonical parent, with contained path checks. An
 > explicit `--refresh-coverage` writes only the declared coverage lock through an atomic file
-> replacement. `--status` and `--check` write nothing.
+> replacement. `--status`, `--check`, and `--check-project` write nothing.
 > Render, scan, baseline and `--assert-git` preflight failures happen before target changes.
 > Staging is removed after success or a clearly pre-commit failure; post-commit or
 > indeterminate failures may retain it to preserve diagnosable state.
@@ -265,12 +295,9 @@ Apache-2.0
 
 ## Minimal example
 
-Use the local checkout while 0.3.0 remains unpublished:
+Display help and run a read-only project check:
 
 ```sh
-node bin/skill-family-doc-render.mjs --help
-node bin/skill-family-doc-render.mjs --check
+npx skill-family-doc-render@0.4.1 --help
+npx skill-family-doc-render@0.4.1 --check-project --repo <name>
 ```
-
-Replace `node bin/skill-family-doc-render.mjs` with `npx skill-family-doc-render@0.3.0` only after
-the registry publishes 0.3.0.

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "skill-family-doc-render",
-  "version": "0.3.0",
+  "version": "0.4.1",
   "description": "Config-driven GitHub Pages knowledge-site renderer for skill-family projects (multi-repo capable).",
   "author": "广州市风荷科技有限公司",
   "license": "Apache-2.0",
@@ -15,6 +15,7 @@
     "bin",
     "scripts",
     "schemas",
+    "templates",
     "README.md",
     "CHANGELOG.md",
     "LICENSE"
@@ -25,6 +26,7 @@
     "render:site:check": "node bin/skill-family-doc-render.mjs --check"
   },
   "dependencies": {
+    "marked": "18.0.11",
     "skill-family-contracts": "0.18.0",
     "skill-family-harness-node": "0.18.0"
   }

package/schemas/pages.schema.json

@@ -2,24 +2,82 @@
   "$id": "https://github.com/ifoohoo/skill-family-doc-render/schemas/pages.schema.json",
   "$schema": "https://json-schema.org/draft/2020-12/schema",
   "title": "pages.json",
-  "description": "站点页面清单：页面顺序、导航与翻页的真源。site 块为站点元数据（渲染器不消费）。id 限文件名片段字符，顺带消除拼路径时的 shell 元字符面。",
-  "type": "object",
-  "additionalProperties": false,
-  "required": ["pages"],
-  "properties": {
-    "site": { "type": "object" },
-    "pages": {
-      "type": "array",
-      "minItems": 1,
-      "items": {
-        "type": "object",
-        "additionalProperties": false,
-        "required": ["id", "title", "order"],
-        "properties": {
-          "id": { "type": "string", "pattern": "^[A-Za-z0-9][A-Za-z0-9_-]*$" },
-          "title": { "type": "string", "minLength": 1 },
-          "order": { "type": "integer" },
-          "inPager": { "type": "boolean" }
+  "description": "旧 HTML 与 markdown-v1 共用的页面清单合同。渲染器按 public-release.json 中的 format 选择对应语义。",
+  "oneOf": [
+    { "$ref": "#/$defs/legacy" },
+    { "$ref": "#/$defs/markdownV1" }
+  ],
+  "$defs": {
+    "safeId": { "type": "string", "pattern": "^[A-Za-z0-9][A-Za-z0-9_-]*$" },
+    "legacy": {
+      "type": "object",
+      "additionalProperties": false,
+      "required": ["pages"],
+      "properties": {
+        "site": { "type": "object" },
+        "pages": {
+          "type": "array",
+          "minItems": 1,
+          "items": {
+            "type": "object",
+            "additionalProperties": false,
+            "required": ["id", "title", "order"],
+            "properties": {
+              "id": { "$ref": "#/$defs/safeId" },
+              "title": { "type": "string", "minLength": 1 },
+              "order": { "type": "integer" },
+              "inPager": { "type": "boolean" }
+            }
+          }
+        }
+      }
+    },
+    "markdownV1": {
+      "type": "object",
+      "additionalProperties": false,
+      "required": ["site", "groups", "pages"],
+      "properties": {
+        "site": {
+          "type": "object",
+          "additionalProperties": false,
+          "required": ["title", "description", "productKind"],
+          "properties": {
+            "title": { "type": "string", "minLength": 1 },
+            "description": { "type": "string", "minLength": 1 },
+            "productKind": { "enum": ["plugin", "library"] }
+          }
+        },
+        "groups": {
+          "type": "array",
+          "minItems": 1,
+          "items": {
+            "type": "object",
+            "additionalProperties": false,
+            "required": ["id", "title"],
+            "properties": {
+              "id": { "$ref": "#/$defs/safeId" },
+              "title": { "type": "string", "minLength": 1 }
+            }
+          }
+        },
+        "pages": {
+          "type": "array",
+          "minItems": 1,
+          "items": {
+            "type": "object",
+            "additionalProperties": false,
+            "required": ["id", "title", "role", "kind", "group", "order", "inPager"],
+            "properties": {
+              "id": { "$ref": "#/$defs/safeId" },
+              "title": { "type": "string", "minLength": 1 },
+              "navTitle": { "type": "string", "minLength": 1 },
+              "role": { "enum": ["overview", "setup", "first-success", "maintenance", "release", "troubleshooting", "upgrade", "reference"] },
+              "kind": { "enum": ["home", "task", "reference", "troubleshooting"] },
+              "group": { "$ref": "#/$defs/safeId" },
+              "order": { "type": "integer" },
+              "inPager": { "type": "boolean" }
+            }
+          }
         }
       }
     }

package/schemas/public-release.schema.json

@@ -29,6 +29,8 @@
               "dir": { "type": "string", "minLength": 1 },
               "target": { "type": "string", "minLength": 1 },
               "pages": { "type": "string", "minLength": 1 },
+              "format": { "const": "markdown-v1" },
+              "template": { "const": "editorial" },
               "coverage": {
                 "type": "object",
                 "additionalProperties": false,
@@ -65,6 +67,10 @@
                   "anyOf": [{ "type": "string" }, { "type": "number" }, { "type": "boolean" }]
                 }
               }
+            },
+            "dependentRequired": {
+              "format": ["template"],
+              "template": ["format"]
             }
           }
         }

package/scripts/lib/markdown-v1.mjs

@@ -0,0 +1,213 @@
+// SPDX-License-Identifier: Apache-2.0
+// 将受限 markdown-v1 编译为 editorial 模板的语义内容块。
+import { Lexer } from 'marked';
+
+const TOKEN = /@[A-Z0-9_]+@/g;
+const SAFE_ID = /^[A-Za-z0-9][A-Za-z0-9_-]*$/;
+
+export class MarkdownV1Error extends TypeError {
+  constructor(message) {
+    super(`markdown-v1: ${message}`);
+  }
+}
+
+const fail = (message) => { throw new MarkdownV1Error(message); };
+
+/** Replace configured facts as literal data, never as Markdown syntax. */
+export function replaceMarkdownTokens(value, tokens, label = 'text') {
+  if (typeof value !== 'string') fail(`${label} must be a string`);
+  const replaced = value.replace(TOKEN, (match) => (
+    Object.hasOwn(tokens, match) ? String(tokens[match]) : match
+  ));
+  const residual = replaced.match(TOKEN);
+  if (residual) fail(`${label} contains unresolved token(s): ${[...new Set(residual)].join(', ')}`);
+  return replaced;
+}
+
+function inline(tokens, facts, label) {
+  const result = [];
+  for (const token of tokens || []) {
+    switch (token.type) {
+      case 'text':
+        if (token.tokens?.length) result.push(...inline(token.tokens, facts, label));
+        else result.push(replaceMarkdownTokens(token.text, facts, label));
+        break;
+      case 'escape':
+        result.push(replaceMarkdownTokens(token.text, facts, label));
+        break;
+      case 'strong':
+      case 'em':
+        result.push({ type: token.type, content: inline(token.tokens, facts, label) });
+        break;
+      case 'codespan':
+        result.push({ type: 'code', text: replaceMarkdownTokens(token.text, facts, label) });
+        break;
+      case 'link':
+        if (token.title) fail(`${label} link titles are not supported`);
+        result.push({
+          type: 'link',
+          href: replaceMarkdownTokens(token.href, facts, `${label} link`),
+          content: inline(token.tokens, facts, label),
+        });
+        break;
+      case 'image':
+        fail(`${label} images must be the only content in their paragraph`);
+        break;
+      case 'html':
+        fail(`${label} raw HTML is not supported`);
+        break;
+      default:
+        fail(`${label} uses unsupported inline syntax: ${token.type}`);
+    }
+  }
+  return result;
+}
+
+function listItem(item, facts, label) {
+  if (item.task || item.checked !== undefined) fail(`${label} task lists are not supported`);
+  const content = item.tokens.filter((token) => token.type !== 'space');
+  if (content.length !== 1 || !['text', 'paragraph'].includes(content[0].type)) {
+    fail(`${label} nested or multi-paragraph list items are not supported`);
+  }
+  const token = content[0];
+  return inline(token.tokens || Lexer.lexInline(token.text, { gfm: true }), facts, label);
+}
+
+function explicitHeading(token) {
+  const match = /^(.*\S)\s+\{#([A-Za-z0-9][A-Za-z0-9_-]*)\}\s*$/.exec(token.text);
+  if (!match) {
+    if (/\s+\{[^}]*\}\s*$/.test(token.text)) fail('heading contains an unsupported or invalid attribute extension');
+    return null;
+  }
+  return { title: match[1], id: match[2] };
+}
+
+function slug(title) {
+  const value = title
+    .normalize('NFKD')
+    .toLowerCase()
+    .replace(/[^a-z0-9_-]+/g, '-')
+    .replace(/^-+|-+$/g, '');
+  return value || 'section';
+}
+
+function callout(token, facts, label) {
+  const meaningful = token.tokens.filter((item) => item.type !== 'space');
+  if (meaningful.length !== 1 || meaningful[0].type !== 'paragraph') {
+    fail(`${label} callout must contain one paragraph`);
+  }
+  const match = /^\[!(NOTE|TIP|WARNING)\]\s*\n([\s\S]*\S)\s*$/.exec(meaningful[0].text);
+  if (!match) fail(`${label} blockquotes must use NOTE, TIP, or WARNING callout syntax`);
+  return {
+    type: 'callout',
+    tone: match[1],
+    content: inline(Lexer.lexInline(match[2], { gfm: true }), facts, label),
+  };
+}
+
+/**
+ * @param {string} source
+ * @param {{pageId:string,tokens?:Record<string,string|number|boolean>}} options
+ * @returns {{blocks:object[],images:string[]}}
+ */
+export function compileMarkdownV1(source, { pageId, tokens = {} }) {
+  if (typeof source !== 'string' || source.includes('\u0000')) fail(`${pageId}.md must be UTF-8 text without NUL`);
+  if (!SAFE_ID.test(pageId)) fail(`invalid page ID: ${pageId}`);
+
+  let lexed;
+  try {
+    lexed = Lexer.lex(source, { gfm: true, breaks: false, pedantic: false });
+  } catch (cause) {
+    throw new MarkdownV1Error(`${pageId}.md cannot be tokenized: ${cause.message}`);
+  }
+
+  const explicitIds = new Set([pageId]);
+  for (const token of lexed) {
+    if (token.type !== 'heading') continue;
+    if (token.depth === 1) fail(`${pageId}.md must not contain an H1`);
+    if (![2, 3, 4].includes(token.depth)) fail(`${pageId}.md heading levels must be H2-H4`);
+    const explicit = explicitHeading(token);
+    if (!explicit) continue;
+    if (explicit.id.startsWith('editorial-')) fail(`${pageId}.md uses a reserved heading ID: ${explicit.id}`);
+    if (explicitIds.has(explicit.id)) fail(`${pageId}.md contains duplicate heading ID: ${explicit.id}`);
+    explicitIds.add(explicit.id);
+  }
+
+  const usedIds = new Set(explicitIds);
+  const blocks = [];
+  const images = new Set();
+  for (const token of lexed) {
+    const label = `${pageId}.md`;
+    switch (token.type) {
+      case 'space':
+        break;
+      case 'paragraph': {
+        if (token.tokens.length === 1 && token.tokens[0].type === 'image') {
+          const image = token.tokens[0];
+          if (image.title) fail(`${label} image titles are not supported`);
+          const src = replaceMarkdownTokens(image.href, tokens, `${label} image`);
+          const alt = replaceMarkdownTokens(image.text, tokens, `${label} image alt`);
+          blocks.push({ type: 'image', src, alt });
+          images.add(src);
+        } else {
+          blocks.push({ type: 'paragraph', content: inline(token.tokens, tokens, label) });
+        }
+        break;
+      }
+      case 'heading': {
+        const explicit = explicitHeading(token);
+        const title = explicit?.title ?? token.text;
+        let headingId = explicit?.id;
+        if (!headingId) {
+          const candidate = slug(title);
+          const base = candidate.startsWith('editorial-') ? `section-${candidate}` : candidate;
+          headingId = base;
+          let suffix = 2;
+          while (usedIds.has(headingId)) {
+            headingId = `${base}-${suffix}`;
+            suffix += 1;
+          }
+          usedIds.add(headingId);
+        }
+        const headingTokens = Lexer.lexInline(title, { gfm: true });
+        blocks.push({ type: 'heading', level: token.depth, id: headingId, content: inline(headingTokens, tokens, label) });
+        break;
+      }
+      case 'list':
+        if (token.ordered && token.start !== 1) fail(`${label} ordered lists must start at 1`);
+        blocks.push({
+          type: 'list',
+          ordered: token.ordered,
+          items: token.items.map((item, index) => listItem(item, tokens, `${label} list item ${index + 1}`)),
+        });
+        break;
+      case 'table':
+        blocks.push({
+          type: 'table',
+          headers: token.header.map((cell) => inline(cell.tokens, tokens, label)),
+          rows: token.rows.map((row) => row.map((cell) => inline(cell.tokens, tokens, label))),
+        });
+        break;
+      case 'code':
+        if (!token.lang || token.codeBlockStyle === 'indented') fail(`${label} code fences require a language marker`);
+        blocks.push({
+          type: 'code',
+          language: token.lang,
+          text: replaceMarkdownTokens(token.text, tokens, `${label} code`),
+        });
+        break;
+      case 'blockquote':
+        blocks.push(callout(token, tokens, label));
+        break;
+      case 'html':
+        fail(`${label} raw HTML is not supported`);
+        break;
+      case 'def':
+        fail(`${label} reference definitions are not supported`);
+        break;
+      default:
+        fail(`${label} uses unsupported block syntax: ${token.type}`);
+    }
+  }
+  return { blocks, images: [...images].sort() };
+}