@dogsbay/format-dogsbay-md 0.2.0-beta.132 → 0.2.0-beta.134

package/dist/browser.d.ts

@@ -22,4 +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";
+export { dogsbayMdPageFiles, dogsbayMdPagePath, mountCopies, carriedFrontmatter, MEDIA_EXTS, type AssetMount } from "./project.js";

package/dist/browser.js

@@ -22,4 +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";
+export { dogsbayMdPageFiles, dogsbayMdPagePath, mountCopies, carriedFrontmatter, MEDIA_EXTS } from "./project.js";

package/dist/escape.js

@@ -145,5 +145,7 @@ export function normalizeTrailingWhitespace(content) {
         if (blankRun < 2)
             out.push(trimmed);
     }
-    return out.join("\n").replace(/\s*$/, "\n");
+    // trimEnd removes what `\s*$` matched, in one pass: the regex, tried at every whitespace run,
+    // was 1.8 s of pan.dev's 9,203 pages
+    return out.join("\n").trimEnd() + "\n";
 }

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

@@ -27,6 +27,8 @@ export declare const MEDIA_EXTS: Set<string>;
  */
 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. */
+/** The file a page is written to, relative to the content root (`dogsbayMdPageFiles`). */
+export declare function dogsbayMdPagePath(page: Pick<ExportPage, "slug">): string;
 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 {

package/dist/project.js

@@ -58,10 +58,13 @@ export function carriedFrontmatter(fm) {
     return out;
 }
 /** Each page as `<slug>.md` and the nav as `nav.json`, relative to the content root. */
+/** The file a page is written to, relative to the content root (`dogsbayMdPageFiles`). */
+export function dogsbayMdPagePath(page) {
+    return `${page.slug || "index"}.md`;
+}
 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 } : {}) } : {};
@@ -71,7 +74,7 @@ export function dogsbayMdPageFiles(pages, nav) {
             ? (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");
+        files.set(dogsbayMdPagePath(page), 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.

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.132",
+  "version": "0.2.0-beta.134",
   "description": "Dogsbay Markdown dialect — canonical format for TreeNode[] with directives, YAML bodies, and intelligent fallbacks",
   "type": "module",
   "main": "dist/index.js",
@@ -40,10 +40,10 @@
     "markdown-it-footnote": "^4.0.0",
     "markdown-it-front-matter": "^0.2.4",
     "pele": "1.6.0",
-    "@dogsbay/corpus": "0.2.0-beta.132",
-    "@dogsbay/minja": "0.2.0-beta.132",
-    "@dogsbay/serialize-core": "0.2.0-beta.132",
-    "@dogsbay/types": "0.2.0-beta.132"
+    "@dogsbay/corpus": "0.2.0-beta.134",
+    "@dogsbay/minja": "0.2.0-beta.134",
+    "@dogsbay/serialize-core": "0.2.0-beta.134",
+    "@dogsbay/types": "0.2.0-beta.134"
   },
   "license": "MIT",
   "repository": {