…` element (instead of the default +`
`), so that a small client-side module
+script (`mermaid@11` ESM from jsDelivr) renders them **in the browser**. This
+is the design's 2026-08-28 revision: **Mermaid renders client-side**;
+`@mermaid-js/mermaid-cli`/`mmdc` is explicitly **not** used (it downloads a
+headless Chromium and failed to install in this environment). PlantUML stays
+build-time (Plan A), but arc42 has no PlantUML so this plan touches only Mermaid.
+
+Two new Astro routes serve the docs: `build/architecture/index.astro` (an
+overview + table of contents) and `build/architecture/[section].astro` (a
+`getStaticPaths` template that renders each section's generated HTML via
+`set:html`). The section pages include the client-side mermaid module script;
+the Build hub gains an **Architecture** card linking `/build/architecture/`.
+
+Plan D changes **no schema/validator code** — it consumes the arc42 Markdown at
+a pinned commit. It adds one runtime-free dependency (`marked`) to the site.
+
+## Architecture
+
+**Verified facts (2026-08-28):**
+
+- arc42 lives in `opencoachingformat/ocf-validator` at `docs/arc42/`, 13
+ Markdown files: `README.md`, `01-introduction-and-goals.md`,
+ `02-architecture-constraints.md`, `03-system-scope-context.md`,
+ `04-solution-strategy.md`, `05-building-block-view.md`, `06-runtime-view.md`,
+ `07-deployment-view.md`, `08-crosscutting-concepts.md`,
+ `09-architecture-decisions.md`, `10-quality-requirements.md`,
+ `11-risks-and-technical-debt.md`, `12-glossary.md`. Only
+ `03-system-scope-context`, `06-runtime-view`, and `10-quality-requirements`
+ contain ` ```mermaid ` fenced blocks. No PlantUML anywhere in arc42.
+- The validator repo's `main` commit that carries the current arc42 is
+ `07361d99f2433f2c715486e0894da5594160a218`. This plan pins arc42 to that
+ commit via a **new, separate** `OCF_ARC42_COMMIT` constant in
+ `site/src/lib/validator-version.mjs` (kept distinct from
+ `OCF_VALIDATOR_COMMIT`, which coincidentally holds the same value today, so
+ that arc42 docs and the validator bundle can be re-pinned independently later).
+- jsDelivr serves individual repo files at
+ `https://cdn.jsdelivr.net/gh/opencoachingformat/ocf-validator@/docs/arc42/.md`.
+ This mirrors how `OCF_ERROR_CODES_URL` is built from `JSDELIVR_GH_BASE` in
+ `validator-version.mjs`. arc42 is **not** part of the published npm package,
+ so — like `error-codes.json` — it must come from a pinned git commit, not the
+ npm CDN.
+- `mermaid@11` ESM loads at
+ `https://cdn.jsdelivr.net/npm/mermaid@11/dist/mermaid.esm.min.mjs` (HTTP 200,
+ `Access-Control-Allow-Origin: *`). Client-side rendering: emit
+ `SOURCE
` and a module `
+ )}
+
+
+
+
+
+
+
+
+
+
+
+ ```
+
+3. Build and assert every section page resolves, at least one carries a
+ `');process.exit(1)}
+ if(scriptPages!==mermaidPages){console.error('mermaid pages without script:',mermaidPages-scriptPages);process.exit(1)}
+ console.log('arc42 sections OK:',idx.length,'pages,',mermaidPages,'with mermaid + module script');
+ "
+ ```
+ Expect success (≥1 section with `
+
+ Architecture (arc42)
+
+ How the reference validator is built, documented with the
+ arc42 template. Pulled from the
+ ocf-validator
+ repository at a pinned commit and rendered here — diagrams included.
+
+
+
+
+
+ {arc42.map((entry) => (
+
+
+
+
+
+
diff --git a/site/src/pages/build/index.astro b/site/src/pages/build/index.astro
index b9de147..962d3ca 100644
--- a/site/src/pages/build/index.astro
+++ b/site/src/pages/build/index.astro
@@ -26,6 +26,11 @@ import Card from '../../components/Card.astro';
description="The machine-readable JSON Schema you validate documents against."
href="/docs/schema/"
/>
+ ", () => {
+ const md = "# Title\n\n```mermaid\ngraph TD\n A --> B\n```\n";
+ const html = mermaidAwareMarked(md);
+ assert.match(html, //);
+ // The diagram source is preserved verbatim inside the pre (NOT wrapped in
+ // , NOT given a language-* class).
+ assert.match(html, /graph TD/);
+ assert.match(html, /A --> B/);
+ assert.doesNotMatch(html, /language-mermaid/);
+ // The block holds no nested element.
+ const block = html.slice(html.indexOf(''));
+ assert.doesNotMatch(block.slice(0, block.indexOf('')), / {
+ // mermaid parses raw source; --> must stay literal, not >/&.
+ const md = "```mermaid\nA --> B\nC -->|x & y| D\n```\n";
+ const html = mermaidAwareMarked(md);
+ assert.match(html, /A --> B/);
+ assert.match(html, /-->\|x & y\| D/);
+ assert.doesNotMatch(html, />/);
+ assert.doesNotMatch(html, /&/);
+});
+
+test("mermaidAwareMarked: renders ordinary markdown normally", () => {
+ const html = mermaidAwareMarked("# Heading\n\nSome **bold** text.\n");
+ assert.match(html, /]/);
+ assert.match(html, /bold<\/strong>/);
+});
+
+test("mermaidAwareMarked: a non-mermaid code fence stays a normal block, escaped", () => {
+ const md = "```json\n{ \"a\": 1 < 2 }\n```\n";
+ const html = mermaidAwareMarked(md);
+ assert.match(html, /]*>/);
+ assert.doesNotMatch(html, //);
+ // Ordinary code fences keep marked's default HTML escaping.
+ assert.match(html, /1 < 2/);
+});
+
+test("mermaidAwareMarked: handles multiple mermaid blocks in one document", () => {
+ const md = "```mermaid\ngraph LR\nA-->B\n```\n\ntext\n\n```mermaid\nsequenceDiagram\nA->>B: hi\n```\n";
+ const html = mermaidAwareMarked(md);
+ const count = (html.match(//g) || []).length;
+ assert.equal(count, 2);
+ assert.match(html, /sequenceDiagram/);
+});
+
+test("buildArc42Index: derives slug + title, README first, then numeric order", () => {
+ const files = [
+ "12-glossary.md",
+ "README.md",
+ "01-introduction-and-goals.md",
+ "06-runtime-view.md",
+ ];
+ const idx = buildArc42Index(files);
+ assert.deepEqual(idx.map((e) => e.slug), [
+ "readme",
+ "01-introduction-and-goals",
+ "06-runtime-view",
+ "12-glossary",
+ ]);
+ const readme = idx.find((e) => e.slug === "readme");
+ assert.equal(readme.title, "Overview");
+ const intro = idx.find((e) => e.slug === "01-introduction-and-goals");
+ assert.equal(intro.title, "1. Introduction and Goals");
+ const runtime = idx.find((e) => e.slug === "06-runtime-view");
+ assert.equal(runtime.title, "6. Runtime View");
+ assert.equal(runtime.file, "06-runtime-view.md");
+});
+
+test("buildArc42Index: ignores non-markdown files", () => {
+ const idx = buildArc42Index(["README.md", "images", "notes.txt"]);
+ assert.deepEqual(idx.map((e) => e.slug), ["readme"]);
+});