@dogsbay/format-dogsbay-md 0.2.0-beta.131 → 0.2.0-beta.133

package/dist/browser.d.ts

@@ -22,3 +22,4 @@ export { maskMinjaInCode, unmaskMinjaInCode, maskAllMinjaOpeners, isMinjaProcess
 export { extractHeadings, slugifyHeadingText, type HeadingInfo } from "./headings.js";
 export { splitFrontmatter, type Frontmatter } from "./frontmatter.js";
 export { TemplatePages, TemplatePageError, declaresParams, ATTRIBUTE_BLOCK_OPEN, type TemplatePagesOptions } from "./template-pages.js";
+export { dogsbayMdPageFiles, mountCopies, carriedFrontmatter, MEDIA_EXTS, type AssetMount } from "./project.js";

package/dist/browser.js

@@ -22,3 +22,4 @@ export { maskMinjaInCode, unmaskMinjaInCode, maskAllMinjaOpeners, isMinjaProcess
 export { extractHeadings, slugifyHeadingText } from "./headings.js";
 export { splitFrontmatter } from "./frontmatter.js";
 export { TemplatePages, TemplatePageError, declaresParams, ATTRIBUTE_BLOCK_OPEN } from "./template-pages.js";
+export { dogsbayMdPageFiles, mountCopies, carriedFrontmatter, MEDIA_EXTS } from "./project.js";

package/dist/cli.d.ts

@@ -1,20 +1,3 @@
 import type { FormatPlugin } from "@dogsbay/types";
-/**
- * The source page's front matter, carried into the Dogsbay MD it becomes.
- * It used to be DROPPED (only title and redirect were written), so a
- * converted corpus lost `description`, `tags` and custom fields, and a
- * query listing (`::child-links{match=…}`) over it found nothing.
- *
- * Keys Dogsbay MD gives meaning to keep their value only when the value
- * MEANS that here; otherwise the key moves under `imported:` — kept, never
- * misread. Starlight's `template: splash` (a page template) must not turn a
- * page into a Jinja template page. A Dogsbay MD source round-trips unchanged:
- * its values are valid by construction.
- *
- * `title`, `redirect` and the template keys are written by the caller.
- * `layout` is free-form (a theme layout name) and passes as it is.
- * `imported:`, not `source:` — Cloudflare pages carry their own `source:`
- * (an origin URL, 91 pages), which the moved keys would have overwritten.
- */
-export declare function carriedFrontmatter(fm: Record<string, unknown> | undefined): Record<string, unknown>;
+export { carriedFrontmatter } from "./project.js";
 export declare const plugin: FormatPlugin;

package/dist/cli.js

@@ -4,15 +4,17 @@
  * Reads a directory of .md files, parses each via dogsbayMdToTree, builds nav
  * from directory structure + frontmatter, returns ExportPage[] + NavItem[].
  */
-import { cpSync, existsSync, mkdirSync, readdirSync, readFileSync, statSync, writeFileSync } from "node:fs";
+import { copyFileSync, existsSync, mkdirSync, readdirSync, readFileSync, statSync, writeFileSync } from "node:fs";
 import { join, relative, basename, dirname } from "node:path";
 import { extractHeadings } from "./headings.js";
 import { parseMeta } from "@dogsbay/types";
 import { dogsbayMdToTree } from "./parse.js";
-import { treeToDogsbayMd } from "./serialize.js";
 import { buildNavFromDirectory } from "./nav.js";
 import { renderDiagrams } from "./renderers/diagrams.js";
 import { DOGSBAY_MD_CAPABILITIES } from "./capabilities.js";
+import { dogsbayMdPageFiles, mountCopies } from "./project.js";
+import { readFolder } from "@dogsbay/corpus/folder";
+export { carriedFrontmatter } from "./project.js";
 /**
  * Detect whether a directory contains a Dogsbay MD source tree.
  *
@@ -221,79 +223,6 @@ function prettifyName(slug) {
  * is the include path. Mirrors migrate-asciidoc's fragment convention so the
  * build-time Minja preprocessor can `{% include %}` them.
  */
-/** Media files worth carrying into `_assets` from a media-only mount. */
-const MEDIA_EXTS = new Set([
-    ".png", ".jpg", ".jpeg", ".gif", ".webp", ".avif",
-    ".svg", ".ico", ".pdf", ".mp4", ".webm",
-]);
-/** Recursively copy only media files, preserving relative structure. */
-function copyMediaTree(srcDir, destDir) {
-    for (const entry of readdirSync(srcDir, { withFileTypes: true })) {
-        const full = join(srcDir, entry.name);
-        if (entry.isDirectory()) {
-            copyMediaTree(full, join(destDir, entry.name));
-            continue;
-        }
-        const dot = entry.name.lastIndexOf(".");
-        if (dot === -1 || !MEDIA_EXTS.has(entry.name.slice(dot).toLowerCase()))
-            continue;
-        mkdirSync(destDir, { recursive: true });
-        cpSync(full, join(destDir, entry.name));
-    }
-}
-/**
- * The source page's front matter, carried into the Dogsbay MD it becomes.
- * It used to be DROPPED (only title and redirect were written), so a
- * converted corpus lost `description`, `tags` and custom fields, and a
- * query listing (`::child-links{match=…}`) over it found nothing.
- *
- * Keys Dogsbay MD gives meaning to keep their value only when the value
- * MEANS that here; otherwise the key moves under `imported:` — kept, never
- * misread. Starlight's `template: splash` (a page template) must not turn a
- * page into a Jinja template page. A Dogsbay MD source round-trips unchanged:
- * its values are valid by construction.
- *
- * `title`, `redirect` and the template keys are written by the caller.
- * `layout` is free-form (a theme layout name) and passes as it is.
- * `imported:`, not `source:` — Cloudflare pages carry their own `source:`
- * (an origin URL, 91 pages), which the moved keys would have overwritten.
- */
-export function carriedFrontmatter(fm) {
-    if (!fm)
-        return {};
-    const out = {};
-    const source = {};
-    const valid = {
-        // `false` is the documented per-page opt-out of a source's `templates: jinja`.
-        template: (v) => v === "jinja" || v === false,
-        weight: (v) => typeof v === "number" && Number.isFinite(v),
-        order: (v) => typeof v === "number" && Number.isFinite(v),
-        draft: (v) => typeof v === "boolean",
-        status: (v) => typeof v === "string" && ["draft", "preview", "stable", "deprecated"].includes(v),
-        // `params:` declares a template PARTIAL's parameters: only with `template: jinja`.
-        params: (v) => Array.isArray(v) && fm.template === "jinja",
-    };
-    for (const [key, value] of Object.entries(fm)) {
-        if (key === "title" || key === "redirect" || value === undefined)
-            continue;
-        // A source that already has `imported:` keeps it: merged if a mapping,
-        // else nested under its own name.
-        if (key === "imported") {
-            if (value && typeof value === "object" && !Array.isArray(value))
-                Object.assign(source, value);
-            else
-                source.imported = value;
-            continue;
-        }
-        if (valid[key] && !valid[key](value))
-            source[key] = value;
-        else
-            out[key] = value;
-    }
-    if (Object.keys(source).length)
-        out.imported = source;
-    return out;
-}
 async function exportDogsbayMd(pages, nav, output, opts) {
     mkdirSync(output, { recursive: true });
     // Copy mounted asset dirs (e.g. Docusaurus `static/`) into `content/_assets/`,
@@ -303,51 +232,27 @@ async function exportDogsbayMd(pages, nav, output, opts) {
     // `content/_assets/**` through to `/_assets/**`. A mount may target an
     // `_assets` subdir (`into`) and restrict itself to media files (`mediaOnly`) —
     // used for docs-co-located images where the mount dir IS the docs tree.
+    // The copy is `mountCopies` over the mount read as a corpus — the list the browser import
+    // copies from its map, so both hosts copy the same files. A mount is someone else's repo:
+    // a symlink out of it (`public/leak.png -> ~/.ssh/id_rsa`) was copied as a link to that
+    // file, and `node_modules` / `.git` inside it were copied whole (2026-10-21).
     if (Array.isArray(opts.assetMounts)) {
         for (const mount of opts.assetMounts) {
             if (!existsSync(mount.dir))
                 continue;
-            // Per-mount root: `_assets` for an imported corpus, `images`/`assets`
-            // for hand-authored content. A hardcoded root would copy the file
-            // where the reference does not point.
-            const assetsRoot = join(output, mount.root ?? "_assets");
-            const dest = mount.into ? join(assetsRoot, mount.into) : assetsRoot;
-            if (mount.mediaOnly) {
-                copyMediaTree(mount.dir, dest);
-                continue;
+            const folder = readFolder(mount.dir);
+            for (const { from, to } of mountCopies(folder.paths, [{ ...mount, dir: "" }])) {
+                const dst = join(output, to);
+                mkdirSync(dirname(dst), { recursive: true });
+                copyFileSync(folder.absolute(from), dst);
             }
-            const skip = new Set(mount.exclude ?? []);
-            cpSync(mount.dir, dest, {
-                recursive: true,
-                ...(skip.size === 0 ? {} : {
-                    // Relative to the mount, so an exclusion cannot be accidentally
-                    // satisfied by a directory name somewhere above it on disk.
-                    filter: (src) => {
-                        const rel = relative(mount.dir, src);
-                        return rel === "" || !rel.split(/[\\/]/).some((seg) => skip.has(seg));
-                    },
-                }),
-            });
         }
     }
-    for (const page of pages) {
-        const slug = page.slug || "index";
-        const outPath = join(output, `${slug}.md`);
+    for (const [path, text] of dogsbayMdPageFiles(pages, nav)) {
+        const outPath = join(output, path);
         mkdirSync(dirname(outPath), { recursive: true });
-        // A template partial keeps its `params:` and the template flag, so the
-        // build treats it as a partial and checks every include against it.
-        const templateFm = page.template ? { template: "jinja", ...(page.templateParams ? { params: page.templateParams } : {}) } : {};
-        // A title-less template page still needs `template: jinja`, or the build
-        // renders it in content mode and shows the directives as text.
-        const frontmatter = page.fragment || !page.title
-            ? (page.template ? templateFm : undefined)
-            : { title: page.title, ...carriedFrontmatter(page.frontmatter), ...(page.redirect ? { redirect: page.redirect } : {}), ...templateFm };
-        const md = treeToDogsbayMd(page.tree, frontmatter ? { frontmatter } : undefined);
-        writeFileSync(outPath, md.endsWith("\n") ? md : md + "\n", "utf-8");
+        writeFileSync(outPath, text, "utf-8");
     }
-    // Nav as nav.json at the content root (the dogsbay-md importer + runtime
-    // loader both prefer nav.json). Fragments never appear here.
-    writeFileSync(join(output, "nav.json"), JSON.stringify(nav, null, 2) + "\n", "utf-8");
 }
 export const plugin = {
     name: "dogsbay-md",

package/dist/nav.js

@@ -14,6 +14,18 @@ import { existsSync, readdirSync, readFileSync, statSync } from "node:fs";
 import { join, relative, basename, dirname } from "node:path";
 import matter from "gray-matter";
 import { loadNavFile } from "./nav-file.js";
+/**
+ * gray-matter EVALUATES front matter that opens with `---js` / `---javascript` (its javascript
+ * engine is `eval`), so a page in someone else's repo could run code on this machine. Every
+ * call passes this, which refuses that engine; YAML and JSON are unchanged.
+ */
+const NO_JS_FRONT_MATTER = {
+    engines: {
+        javascript: () => {
+            throw new Error("JavaScript front matter is not run");
+        },
+    },
+};
 /**
  * File names tried, in priority order, when auto-detecting a nav
  * file in a content directory. The first existing file wins.
@@ -85,7 +97,7 @@ function collectPages(dir, rootDir) {
             const content = readFileSync(fullPath, "utf-8");
             let frontmatter = {};
             try {
-                frontmatter = (matter(content).data ?? {});
+                frontmatter = (matter(content, NO_JS_FRONT_MATTER).data ?? {});
             }
             catch {
                 // Malformed frontmatter — treat as no frontmatter

package/dist/project.d.ts

@@ -0,0 +1,60 @@
+/**
+ * A converted corpus as a Dogsbay MD project, as data: what `convert --to dogsbay-md` writes
+ * (each page as `<slug>.md`, the nav as `nav.json`, the importer's asset mounts under
+ * `_assets/`), without the file system. The exporter writes these files; the playground's
+ * browser imports (`@dogsbay/format-vitepress/migrate`) return them, so a migration in the
+ * browser is the one `convert` does.
+ */
+import type { ExportPage, NavItem } from "@dogsbay/types";
+/** Media files worth carrying into `_assets` from a media-only mount. */
+export declare const MEDIA_EXTS: Set<string>;
+/**
+ * The source page's front matter, carried into the Dogsbay MD it becomes.
+ * It used to be DROPPED (only title and redirect were written), so a
+ * converted corpus lost `description`, `tags` and custom fields, and a
+ * query listing (`::child-links{match=…}`) over it found nothing.
+ *
+ * Keys Dogsbay MD gives meaning to keep their value only when the value
+ * MEANS that here; otherwise the key moves under `imported:` — kept, never
+ * misread. Starlight's `template: splash` (a page template) must not turn a
+ * page into a Jinja template page. A Dogsbay MD source round-trips unchanged:
+ * its values are valid by construction.
+ *
+ * `title`, `redirect` and the template keys are written by the caller.
+ * `layout` is free-form (a theme layout name) and passes as it is.
+ * `imported:`, not `source:` — Cloudflare pages carry their own `source:`
+ * (an origin URL, 91 pages), which the moved keys would have overwritten.
+ */
+export declare function carriedFrontmatter(fm: Record<string, unknown> | undefined): Record<string, unknown>;
+/** Each page as `<slug>.md` and the nav as `nav.json`, relative to the content root. */
+export declare function dogsbayMdPageFiles(pages: ExportPage[], nav: NavItem[]): Map<string, string>;
+/** An importer's asset directory, as `ImportResult.assetMounts` declares it, relative to the corpus. */
+export interface AssetMount {
+    dir: string;
+    /** A subdirectory of the root to land in (`pages` → `_assets/pages/`). */
+    into?: string;
+    /** Media files only (`MEDIA_EXTS`): the mount is the docs tree itself. */
+    mediaOnly?: boolean;
+    /**
+     * Directory names to leave behind, matched at ANY depth in the mount.
+     *
+     * `mediaOnly` is the wrong tool when a mount is mostly wanted: it also drops scripts, YAML
+     * and text a corpus may legitimately carry. This skips named subtrees instead — e.g.
+     * Calico's `licenses/`, ~35 MB of third-party attribution HTML for versions the corpus does
+     * not even import, which nothing references. Matched at any depth on purpose: the first
+     * version compared only the FIRST path segment and silently did nothing, because the real
+     * tree is `_assets/calico/3.32/licenses/…`.
+     */
+    exclude?: string[];
+    /** Public root the mount lands in; `_assets` unless the source used another. */
+    root?: string;
+}
+/**
+ * The files the exporter copies for `mounts`, from a corpus's `paths`: corpus path → path in
+ * the content root. The same rules as the exporter's copy on disk: the whole mount minus
+ * excluded names, or its media only.
+ */
+export declare function mountCopies(paths: string[], mounts: AssetMount[]): {
+    from: string;
+    to: string;
+}[];

package/dist/project.js

@@ -0,0 +1,109 @@
+import { treeToDogsbayMd } from "./serialize.js";
+/** Media files worth carrying into `_assets` from a media-only mount. */
+export const MEDIA_EXTS = new Set([
+    ".png", ".jpg", ".jpeg", ".gif", ".webp", ".avif",
+    ".svg", ".ico", ".pdf", ".mp4", ".webm",
+]);
+/**
+ * The source page's front matter, carried into the Dogsbay MD it becomes.
+ * It used to be DROPPED (only title and redirect were written), so a
+ * converted corpus lost `description`, `tags` and custom fields, and a
+ * query listing (`::child-links{match=…}`) over it found nothing.
+ *
+ * Keys Dogsbay MD gives meaning to keep their value only when the value
+ * MEANS that here; otherwise the key moves under `imported:` — kept, never
+ * misread. Starlight's `template: splash` (a page template) must not turn a
+ * page into a Jinja template page. A Dogsbay MD source round-trips unchanged:
+ * its values are valid by construction.
+ *
+ * `title`, `redirect` and the template keys are written by the caller.
+ * `layout` is free-form (a theme layout name) and passes as it is.
+ * `imported:`, not `source:` — Cloudflare pages carry their own `source:`
+ * (an origin URL, 91 pages), which the moved keys would have overwritten.
+ */
+export function carriedFrontmatter(fm) {
+    if (!fm)
+        return {};
+    const out = {};
+    const source = {};
+    const valid = {
+        // `false` is the documented per-page opt-out of a source's `templates: jinja`.
+        template: (v) => v === "jinja" || v === false,
+        weight: (v) => typeof v === "number" && Number.isFinite(v),
+        order: (v) => typeof v === "number" && Number.isFinite(v),
+        draft: (v) => typeof v === "boolean",
+        status: (v) => typeof v === "string" && ["draft", "preview", "stable", "deprecated"].includes(v),
+        // `params:` declares a template PARTIAL's parameters: only with `template: jinja`.
+        params: (v) => Array.isArray(v) && fm.template === "jinja",
+    };
+    for (const [key, value] of Object.entries(fm)) {
+        if (key === "title" || key === "redirect" || value === undefined)
+            continue;
+        // A source that already has `imported:` keeps it: merged if a mapping,
+        // else nested under its own name.
+        if (key === "imported") {
+            if (value && typeof value === "object" && !Array.isArray(value))
+                Object.assign(source, value);
+            else
+                source.imported = value;
+            continue;
+        }
+        if (valid[key] && !valid[key](value))
+            source[key] = value;
+        else
+            out[key] = value;
+    }
+    if (Object.keys(source).length)
+        out.imported = source;
+    return out;
+}
+/** Each page as `<slug>.md` and the nav as `nav.json`, relative to the content root. */
+export function dogsbayMdPageFiles(pages, nav) {
+    const files = new Map();
+    for (const page of pages) {
+        const slug = page.slug || "index";
+        // A template partial keeps its `params:` and the template flag, so the
+        // build treats it as a partial and checks every include against it.
+        const templateFm = page.template ? { template: "jinja", ...(page.templateParams ? { params: page.templateParams } : {}) } : {};
+        // A title-less template page still needs `template: jinja`, or the build
+        // renders it in content mode and shows the directives as text.
+        const frontmatter = page.fragment || !page.title
+            ? (page.template ? templateFm : undefined)
+            : { title: page.title, ...carriedFrontmatter(page.frontmatter), ...(page.redirect ? { redirect: page.redirect } : {}), ...templateFm };
+        const md = treeToDogsbayMd(page.tree, frontmatter ? { frontmatter } : undefined);
+        files.set(`${slug}.md`, md.endsWith("\n") ? md : md + "\n");
+    }
+    // Nav as nav.json at the content root (the dogsbay-md importer + runtime
+    // loader both prefer nav.json). Fragments never appear here.
+    files.set("nav.json", JSON.stringify(nav, null, 2) + "\n");
+    return files;
+}
+/**
+ * The files the exporter copies for `mounts`, from a corpus's `paths`: corpus path → path in
+ * the content root. The same rules as the exporter's copy on disk: the whole mount minus
+ * excluded names, or its media only.
+ */
+export function mountCopies(paths, mounts) {
+    const out = [];
+    for (const mount of mounts) {
+        const dir = mount.dir.replace(/\/+$/, "");
+        const dest = [mount.root ?? "_assets", mount.into].filter(Boolean).join("/");
+        const skip = new Set(mount.exclude ?? []);
+        for (const path of paths) {
+            if (dir && !path.startsWith(dir + "/"))
+                continue;
+            const rel = dir ? path.slice(dir.length + 1) : path;
+            const segs = rel.split("/");
+            if (mount.mediaOnly) {
+                const name = segs[segs.length - 1];
+                const dot = name.lastIndexOf(".");
+                if (dot === -1 || !MEDIA_EXTS.has(name.slice(dot).toLowerCase()))
+                    continue;
+            }
+            else if (segs.some((s) => skip.has(s)))
+                continue;
+            out.push({ from: path, to: `${dest}/${rel}` });
+        }
+    }
+    return out;
+}

package/dist/serialize.js

@@ -1,4 +1,6 @@
-import { walkInline, applyTextFlags, renderAroundGroup } from "@dogsbay/serialize-core";
+import { walkInline, applyTextFlags, renderAroundGroup, neutralizeMarkdown, mapOutsideCodeSpans } from "@dogsbay/serialize-core";
+import MarkdownIt from "markdown-it";
+import { transformFenceInfo, transformProseSegments } from "./code-regions.js";
 import { inlineToDogsbayMd } from "./inline.js";
 import { assertDirectiveField } from "./directive-guard.js";
 import { renderAttrs, splitProps } from "./attributes.js";
@@ -192,13 +194,60 @@ function renderConditionalDirective(node, ctx) {
         .join("\n\n");
     return body ? `${opener}\n\n${body}\n\n{% endif %}` : `${opener}\n\n{% endif %}`;
 }
+/**
+ * Markdown we did not write (an OpenAPI description) kept as Markdown but not as Dogsbay MD.
+ * Each piece of syntax is made inert by the grammar of whatever would act on it, never by a
+ * guess at it (review 2026-10-21: three guesses disagreed with the readers, and template tags
+ * and containers leaked):
+ * - template tags, by minja's own code/prose split (`transformProseSegments`): `{` before
+ *   `%`, `{` or `#` in what minja reads as prose becomes `{`; and a fence opener's `{…}`
+ *   attribute group is dropped wherever minja sees an opener (`transformFenceInfo`: indented,
+ *   after a definition-list `:`) — `{minja}` there opts the block INTO template processing;
+ * - directives (`:::name`, `::name`, `:name[…]`), by markdown-it's: outside the lines it
+ *   parses as code and outside code spans, every colon of a colon run and a colon that could
+ *   start a directive becomes `:`.
+ * Entities read the same as the characters; code is left as written (neither reader acts on
+ * it there).
+ */
+function inertDogsbaySyntax(md) {
+    let out = transformFenceInfo(md, (info) => info.replace(/\s*\{[^{}]*\}[\s\S]*$/, ""));
+    out = transformProseSegments(out, (p) => p.replace(/\{(?=[%{#])/g, "{"));
+    const code = new Set();
+    for (const t of CODE_LINES_PARSER.parse(out, {})) {
+        if ((t.type === "fence" || t.type === "code_block") && t.map)
+            for (let i = t.map[0]; i < t.map[1]; i++)
+                code.add(i);
+    }
+    return out
+        .split("\n")
+        .map((line, i) => code.has(i)
+        ? line
+        : mapOutsideCodeSpans(line, (p) => p.replace(/:(?=:)|(?<=:):|(?<![\p{L}\p{N}:]):(?=[A-Za-z])/gu, "&#58;")))
+        .join("\n");
+}
+/** Only to find the lines markdown-it reads as code (fences, indented blocks). */
+const CODE_LINES_PARSER = new MarkdownIt();
+/** How deep a schema is written, how many field lines an endpoint gets, how long an example is. */
+const ENDPOINT_FIELD_DEPTH = 8;
+const ENDPOINT_FIELD_LINES = 400;
+const ENDPOINT_EXAMPLE_CHARS = 8000;
 /**
  * Serialize an OpenAPI `endpoint` TreeNode (produced by
  * @dogsbay/format-openapi) as agent-readable markdown. The HTML
  * version uses ApiLayout + EndpointCard + friends; the markdown
- * mirror collapses the same data into headings, tables, and code
- * blocks so an agent fetching the `.md` URL still gets the full
- * operation reference.
+ * mirror writes the same data as headings, tables, lists and code
+ * blocks so an agent fetching the `.md` URL (or a site converted to
+ * Dogsbay MD) gets the full operation reference: parameters with their
+ * enums and defaults, the request body's fields to any depth (dotted
+ * names: `user.address.city`, `items[].id`), and each response's
+ * content type, fields and example.
+ *
+ * The shapes are read back by `@dogsbay/transition`'s endpoint
+ * extractor: a `- \`name\` (\`type\`) …` line is a body field, a table
+ * headed Name / Type / Required is parameters, `- **200** — …` under
+ * `### Responses` is a response. Response fields are therefore a table
+ * headed FIELD, and body fields stay flat list lines (a nested list's
+ * text would run into its parent's).
  */
 function renderEndpoint(node) {
     const props = (node.props ?? {});
@@ -213,12 +262,96 @@ function renderEndpoint(node) {
     const responses = props.responses ?? [];
     const codeSamples = props.codeSamples ?? [];
     // Spec text is Markdown (CommonMark, per OpenAPI) from a file the site's
-    // author may not have written: its Markdown is kept, its raw HTML is not
-    // (`<` → `&lt;`, which still reads as `<`). Names and paths go into code
-    // spans, which a backtick would end.
-    const text = (v) => String(v ?? "").replace(/&(?=[#a-zA-Z0-9]+;)/g, "&amp;").replace(/</g, "&lt;");
-    const line = (v) => text(v).replace(/\s*\n\s*/g, " ");
+    // author may not have written: its Markdown is kept; its raw HTML and
+    // unsafe links are not (neutralizeMarkdown), nor is Dogsbay MD's own
+    // syntax — a `:::` container or a `{% %}` / `{{ }}` / `{# #}` template
+    // tag would be read as one. Names and paths go into code spans, which a
+    // backtick would end.
+    const text = (v) => inertDogsbaySyntax(neutralizeMarkdown(String(v ?? "").replace(/\r\n?/g, "\n")));
+    // One line: joined BEFORE it is made inert (code that spans lines is prose once joined)
+    const line = (v) => text(String(v ?? "").replace(/\s*[\r\n]+\s*/g, " ").trim());
+    const cell = (v) => line(v).replace(/\|/g, "\\|");
     const code = (v) => String(v ?? "").replace(/[`\r\n]/g, " ");
+    /** A code span in a table cell: a `|` would end the cell. */
+    const codeCell = (v) => code(v).replace(/\|/g, "\\|");
+    const value = (v) => code(typeof v === "string" ? v : JSON.stringify(v));
+    /** The description, then what a reader needs to send a valid value. */
+    const detail = (p) => {
+        const parts = [];
+        if (p.description)
+            parts.push(line(p.description));
+        if (p.format)
+            parts.push(`Format: \`${code(p.format)}\`.`);
+        if (Array.isArray(p.enum) && p.enum.length) {
+            const shown = p.enum.slice(0, 20).map((e) => `\`${value(e)}\``).join(", ");
+            parts.push(`One of: ${shown}${p.enum.length > 20 ? `, … (${p.enum.length} values)` : ""}.`);
+        }
+        if (p.default !== undefined && p.default !== "")
+            parts.push(`Default: \`${value(p.default)}\`.`);
+        if (p.nullable === true)
+            parts.push("Nullable.");
+        if (p.deprecated === true)
+            parts.push("Deprecated.");
+        return parts.join(" ");
+    };
+    /** Field lines left for this endpoint: shared by the request body and every response. */
+    let fieldLines = ENDPOINT_FIELD_LINES;
+    /**
+     * Every field, flattened to dotted names, depth- and count-capped. `more` counts what is
+     * not written for either reason, descendants included (counting stops at 100,000).
+     */
+    const flatten = (fields) => {
+        const rows = [];
+        let more = 0;
+        const count = (list, depth) => {
+            if (!Array.isArray(list) || more >= 100_000 || depth > 64)
+                return;
+            for (const f of list) {
+                if (!f || typeof f !== "object")
+                    continue;
+                more++;
+                count(f.properties, depth + 1);
+                count(f.items, depth + 1);
+            }
+        };
+        const walk = (list, prefix, depth) => {
+            if (!Array.isArray(list))
+                return;
+            if (depth > ENDPOINT_FIELD_DEPTH)
+                return count(list, depth);
+            for (const f of list) {
+                if (!f || typeof f !== "object")
+                    continue;
+                if (fieldLines <= 0) {
+                    count([f], depth);
+                    continue;
+                }
+                fieldLines--;
+                const name = `${prefix}${String(f.name ?? "")}`;
+                rows.push({ name, field: f });
+                walk(f.properties, `${name}.`, depth + 1);
+                walk(f.items, `${name}[].`, depth + 1);
+            }
+        };
+        walk(fields, "", 0);
+        return { rows, more };
+    };
+    /**
+     * An example as a titled code block (JSON unless it is a string), cut at
+     * ENDPOINT_EXAMPLE_CHARS. The title, not a paragraph, says what it is: the endpoint
+     * extractor takes an endpoint's first paragraph as its description.
+     */
+    const example = (v, title, out) => {
+        if (v === undefined)
+            return;
+        let json = typeof v === "string" ? v : JSON.stringify(v, null, 2);
+        if (json === undefined)
+            return;
+        const cut = json.length > ENDPOINT_EXAMPLE_CHARS;
+        if (cut)
+            json = json.slice(0, ENDPOINT_EXAMPLE_CHARS);
+        out.push(renderCode({ type: "code", props: { code: json, language: typeof v === "string" ? "" : "json", title: cut ? `${title} (first ${ENDPOINT_EXAMPLE_CHARS} characters)` : title } }), "");
+    };
     const out = [];
     out.push(`## ${method.replace(/[^A-Z]/g, "")} ${line(path)}`);
     out.push("");
@@ -245,18 +378,23 @@ function renderEndpoint(node) {
         out.push("| Name | In | Type | Required | Description |");
         out.push("| --- | --- | --- | --- | --- |");
         for (const p of parameters) {
-            const cell = (v) => line(v).replace(/\|/g, "\\|");
-            out.push(`| \`${code(p.name)}\` | ${cell(p.in)} | \`${code(p.type)}\` | ${p.required ? "yes" : "no"} | ${cell(p.description)} |`);
+            out.push(`| \`${codeCell(p.name)}\` | ${cell(p.in)} | \`${codeCell(p.type)}\` | ${p.required ? "yes" : "no"} | ${detail(p).replace(/\|/g, "\\|")} |`);
         }
         out.push("");
     }
-    if (requestBody.length > 0) {
+    if (requestBody.length > 0 || props.requestBodyExample !== undefined) {
         out.push("### Request body");
         out.push("");
-        for (const p of requestBody) {
-            out.push(`- \`${code(p.name)}\` (\`${code(p.type)}\`)${p.required ? " — required" : ""}${p.description ? ` — ${line(p.description)}` : ""}`);
+        const { rows, more } = flatten(requestBody);
+        for (const { name, field } of rows) {
+            const d = detail(field);
+            out.push(`- \`${code(name)}\` (\`${code(field.type)}\`)${field.required ? " — required" : ""}${d ? ` — ${d}` : ""}`);
         }
-        out.push("");
+        if (more)
+            out.push(`- … ${more} more field${more === 1 ? "" : "s"} not shown`);
+        if (rows.length || more)
+            out.push("");
+        example(props.requestBodyExample, "Request example", out);
     }
     if (responses.length > 0) {
         out.push("### Responses");
@@ -267,6 +405,26 @@ function renderEndpoint(node) {
             out.push(`- **${status}** — ${desc}`);
         }
         out.push("");
+        for (const r of responses) {
+            const schema = Array.isArray(r.schema) ? r.schema : [];
+            if (!schema.length && r.example === undefined)
+                continue;
+            // The content type in the heading, not a paragraph (see `example`)
+            out.push(`#### ${line(r.status)}${r.contentType ? ` (\`${code(r.contentType)}\`)` : ""}`);
+            out.push("");
+            const { rows, more } = flatten(schema);
+            if (rows.length) {
+                out.push("| Field | Type | Required | Description |");
+                out.push("| --- | --- | --- | --- |");
+                for (const { name, field } of rows) {
+                    out.push(`| \`${codeCell(name)}\` | \`${codeCell(field.type)}\` | ${field.required ? "yes" : "no"} | ${detail(field).replace(/\|/g, "\\|")} |`);
+                }
+                out.push("");
+            }
+            if (more)
+                out.push(`… ${more} more field${more === 1 ? "" : "s"} not shown.`, "");
+            example(r.example, `Response example (${line(r.status)})`, out);
+        }
     }
     if (codeSamples.length > 0) {
         out.push("### Code samples");

package/dist/yaml.d.ts

@@ -15,7 +15,4 @@ export type YamlValue = string | number | boolean | null | undefined | Date | Ya
  * Keys emitted in insertion order.
  */
 export declare function renderYaml(value: Record<string, YamlValue>, indent?: number): string;
-/**
- * Render a frontmatter block: --- YAML ---
- */
 export declare function renderFrontmatter(value: Record<string, YamlValue>): string;

package/dist/yaml.js

@@ -131,7 +131,34 @@ function needsQuoting(value) {
 /**
  * Render a frontmatter block: --- YAML ---
  */
+/** Values a front matter may expand to when written out in full (see renderFrontmatter). */
+const MAX_FRONTMATTER_VALUES = 100_000;
+/** What `v` expands to when every shared reference is written out, up to `cap` + 1. */
+function expandedSize(v, cap, memo = new Map(), depth = 0) {
+    if (v === null || typeof v !== "object" || v instanceof Date)
+        return 1;
+    const known = memo.get(v);
+    if (known !== undefined)
+        return known;
+    if (depth > 1000)
+        return cap + 1;
+    let n = 1;
+    for (const c of Array.isArray(v) ? v : Object.values(v)) {
+        n += expandedSize(c, cap, memo, depth + 1);
+        if (n > cap)
+            break;
+    }
+    memo.set(v, n);
+    return n;
+}
 export function renderFrontmatter(value) {
+    // A source's YAML aliases are shared references once parsed. Written out in full, ten lines of
+    // nested aliases became megabytes (an alias bomb — review 2026-10-21, Docusaurus front matter;
+    // GitBook met it 2026-10-20). Such a value is written with its aliases kept; every other page
+    // is written exactly as before.
+    if (expandedSize(value, MAX_FRONTMATTER_VALUES) > MAX_FRONTMATTER_VALUES) {
+        return `---\n${jsyaml.dump(value, { lineWidth: -1, noRefs: false, skipInvalid: true }).trimEnd()}\n---`;
+    }
     const yaml = renderYaml(value);
     if (readsBackAs(yaml, value))
         return `---\n${yaml}\n---`;

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@dogsbay/format-dogsbay-md",
-  "version": "0.2.0-beta.131",
+  "version": "0.2.0-beta.133",
   "description": "Dogsbay Markdown dialect — canonical format for TreeNode[] with directives, YAML bodies, and intelligent fallbacks",
   "type": "module",
   "main": "dist/index.js",
@@ -40,9 +40,10 @@
     "markdown-it-footnote": "^4.0.0",
     "markdown-it-front-matter": "^0.2.4",
     "pele": "1.6.0",
-    "@dogsbay/minja": "0.2.0-beta.131",
-    "@dogsbay/serialize-core": "0.2.0-beta.131",
-    "@dogsbay/types": "0.2.0-beta.131"
+    "@dogsbay/corpus": "0.2.0-beta.133",
+    "@dogsbay/serialize-core": "0.2.0-beta.133",
+    "@dogsbay/minja": "0.2.0-beta.133",
+    "@dogsbay/types": "0.2.0-beta.133"
   },
   "license": "MIT",
   "repository": {