@dogsbay/format-dogsbay-md 0.2.0-beta.127 → 0.2.0-beta.129

package/dist/browser.d.ts

@@ -13,7 +13,7 @@
  */
 export { dogsbayMdToTree, parseInline, containerOpenBefore, type ParseResult, type ParseOptions } from "./parse.js";
 export { KNOWN_INLINE_DIRECTIVES, type ParseDiagnostic } from "./diagnostics.js";
-export { KNOWN_BLOCK_DIRECTIVES } from "./plugin-containers.js";
+export { KNOWN_BLOCK_DIRECTIVES, LEAF_ONLY_DIRECTIVES, BLOCK_LEAF_DIRECTIVES } from "./plugin-containers.js";
 export { treeToDogsbayMd, nodeToDogsbayMd } from "./serialize.js";
 export type { SerializeOptions } from "./types.js";
 export { inlineToDogsbayMd } from "./inline.js";

package/dist/browser.js

@@ -14,7 +14,7 @@
 export { dogsbayMdToTree, parseInline, containerOpenBefore } from "./parse.js";
 export { KNOWN_INLINE_DIRECTIVES } from "./diagnostics.js";
 // The `:::name` blocks the parser knows (an editor completes names from it)
-export { KNOWN_BLOCK_DIRECTIVES } from "./plugin-containers.js";
+export { KNOWN_BLOCK_DIRECTIVES, LEAF_ONLY_DIRECTIVES, BLOCK_LEAF_DIRECTIVES } from "./plugin-containers.js";
 export { treeToDogsbayMd, nodeToDogsbayMd } from "./serialize.js";
 export { inlineToDogsbayMd } from "./inline.js";
 export { transformCodeRegions, transformProseLines, transformProseSegments, fenceOpenBefore, createFenceTracker, } from "./code-regions.js";

package/dist/capabilities.js

@@ -30,7 +30,7 @@ export const DOGSBAY_MD_CAPABILITIES = [
         rendersAs: "a ```mermaid fence with the diagram source",
         note: "The source round-trips (it re-parses as a code fence, which the build turns back into a diagram); a pre-rendered SVG is not kept.",
     },
-    { feature: "youtube", support: "full", rendersAs: "`:::youtube{#id title=\"…\"}`" },
+    { feature: "youtube", support: "full", rendersAs: "`::youtube{#id title=\"…\"}`" },
     // ── Components ───────────────────────────────────────────
     { feature: "callout", support: "full", rendersAs: "GitHub alert `> [!NOTE]`; `:::type[Title]{…}` for a custom title or a non-GitHub type" },
     { feature: "details", support: "full", rendersAs: "`:::details{title=\"…\"}`" },

package/dist/cli.js

@@ -131,11 +131,13 @@ async function importDogsbayMd(source, opts) {
     // (mermaid-cli) isn't installed the code block is left as-is and
     // a one-line warning is printed. See plans/mermaid-dogsbay-md.md.
     const diagramsOn = opts.diagrams !== false;
+    // `content.diagrams: pele` draws them with Pele; `true` (the default) with mmdc
+    const diagramEngine = opts.diagrams === "pele" ? "pele" : "mermaid-cli";
     for (const { filePath, slug, sourcePath } of files) {
         const content = readFileSync(filePath, "utf-8");
         const { tree, frontmatter } = dogsbayMdToTree(content);
         if (diagramsOn) {
-            await renderDiagrams(tree);
+            await renderDiagrams(tree, { engine: diagramEngine });
         }
         const title = String(frontmatter.title
             ?? prettifyName(basename(slug)));

package/dist/container-rule.d.ts

@@ -58,8 +58,9 @@ import type MarkdownIt from "markdown-it";
  * Only a known directive name opens a block in the scan. An unknown `:::word` is a block only if
  * it has a closer of its own and is otherwise text (markUnclosedGenericContainers), and the scan
  * cannot know which, so it does not push one: an unknown block nested at the same colon count
- * as its parent still needs more colons on the parent. A body-less block (`:::youtube{#id}`) is
- * pushed only when a closer that fits it follows, or it would take its parent's.
+ * as its parent still needs more colons on the parent. `:::` always opens a block that needs a
+ * closer; a directive with no body is a leaf, `::youtube{#id}` (plugin-block-leaf.ts), so no
+ * opener depends on the line after it.
  *
  * VERIFY. The scan reads raw lines, and markdown-it may not read an opener there as one: in raw
  * HTML, a `$$` math block, a fence that never closes. Where that is depends on where the blocks
@@ -77,11 +78,6 @@ export interface ContainerOptions {
     validate: (params: string, markup: string) => boolean;
     render?: (tokens: unknown[], idx: number) => string;
 }
-/**
- * Make `name` an opener for the nesting scan (the known directives; not the generic container).
- * A `leaf` is written with no body (`:::youtube{#id}`) and often with no closer.
- */
-export declare function registerOpener(name: string, options?: {
-    leaf?: boolean;
-}): void;
+/** Make `name` an opener for the nesting scan (the known directives; not the generic container). */
+export declare function registerOpener(name: string): void;
 export declare function containerRule(md: MarkdownIt, name: string, options: ContainerOptions): void;

package/dist/container-rule.js

@@ -52,31 +52,16 @@ function closesFence(line, markup, after) {
     const m = /^[ \t>]*(`{3,}|~{3,})[ \t]*$/.exec(line);
     return m !== null && m[1][0] === markup[0] && m[1].length >= markup.length;
 }
-/** The directive names the scan treats as openers (plugin-containers registers them), and whether each is body-less. */
-const KNOWN_OPENERS = new Map();
-/** The known directive the text after an opener's colons starts with. */
-function knownOpener(rest) {
+/** The directive names the scan treats as openers (plugin-containers registers them). */
+const KNOWN_OPENERS = new Set();
+/** Whether the text after an opener's colons starts with a known directive name. */
+function isKnownOpener(rest) {
     const m = /^\s*([A-Za-z][\w-]*)(?=$|[\s{[])/.exec(rest);
-    return m === null ? undefined : KNOWN_OPENERS.get(m[1]);
+    return m !== null && KNOWN_OPENERS.has(m[1]);
 }
-/**
- * Make `name` an opener for the nesting scan (the known directives; not the generic container).
- * A `leaf` is written with no body (`:::youtube{#id}`) and often with no closer.
- */
-export function registerOpener(name, options = {}) {
-    KNOWN_OPENERS.set(name, { leaf: options.leaf === true });
-}
-/** Whether the next non-blank line after `line`, before `endLine`, is a closer for a block opened with `colons`. */
-function closerFollows(state, line, endLine, colons) {
-    for (let l = line + 1; l < endLine; l++) {
-        const start = state.bMarks[l] + state.tShift[l];
-        const max = state.eMarks[l];
-        if (start >= max)
-            continue;
-        const m = /^(:{3,})(.*)$/.exec(state.src.slice(start, max));
-        return m !== null && m[1].length >= colons && CLOSER_TAIL.test(m[2]);
-    }
-    return false;
+/** Make `name` an opener for the nesting scan (the known directives; not the generic container). */
+export function registerOpener(name) {
+    KNOWN_OPENERS.add(name);
 }
 /** Tokens whose lines are not block openers: an opener the scan pushed inside one is wrong (VERIFY). */
 const READ_AS_OTHER = new Set(["paragraph_open", "heading_open", "html_block", "fence", "code_block", "math_block", "hr", "table_open"]);
@@ -177,8 +162,11 @@ export function containerRule(md, name, options) {
             if (wrong.length === 0 && missed.length === 0)
                 break;
             const budget = retryBudget(state);
-            if (budget.lines < scan.nextLine - startLine)
+            if (budget.lines < scan.nextLine - startLine) {
+                // Out of budget: this reading stands, with an opener known to be wrong; say so (diagnostics)
+                open.meta = { ...(open.meta ?? {}), unverified: true };
                 break;
+            }
             budget.lines -= scan.nextLine - startLine;
             for (const l of wrong)
                 notOpeners.add(l);
@@ -238,7 +226,7 @@ export function containerRule(md, name, options) {
                 continue;
             const rest = state.src.slice(pos, max);
             const tail = CLOSER_TAIL.exec(rest);
-            const opener = tail ? undefined : knownOpener(rest);
+            const opener = !tail && isKnownOpener(rest);
             if (!tail && !opener)
                 continue;
             // a `:::` in a code example is code
@@ -248,7 +236,7 @@ export function containerRule(md, name, options) {
                 continue;
             }
             if (opener) {
-                if (notOpeners.has(nextLine) || (opener.leaf && !closerFollows(state, nextLine, endLine, colons)))
+                if (notOpeners.has(nextLine))
                     continue;
                 const least = Math.min(colons, inner.length > 0 ? inner[inner.length - 1].least : colons);
                 inner.push({ colons, indent: state.sCount[nextLine], least });

package/dist/diagnostics.d.ts

@@ -2,7 +2,7 @@ export interface ParseDiagnostic {
     /** 1-based line in the source (front matter counted). */
     line: number;
     /** Stable kind, for filtering. */
-    code: "unclosed-container" | "stray-closer" | "unknown-container" | "unknown-inline" | "block-directive-inline" | "bad-attributes" | "closer-mismatch" | "dropped-attributes" | "missing-label";
+    code: "unclosed-container" | "stray-closer" | "unknown-container" | "unknown-inline" | "block-directive-inline" | "bad-attributes" | "closer-mismatch" | "dropped-attributes" | "missing-label" | "leaf-as-block" | "nesting-unchecked";
     message: string;
 }
 /**
@@ -32,6 +32,7 @@ type Token = {
         unclosed?: boolean;
         skippedCloser?: number;
         legacyCloser?: number;
+        unverified?: boolean;
     } | null;
 };
 /**
@@ -40,9 +41,5 @@ type Token = {
  * missing brace or an unterminated quote loses attributes silently.
  */
 export declare function attributeProblem(block: string): string | undefined;
-/**
- * Diagnostics for a token stream. `lines` is the parsed text split at `\n`;
- * `lineOf` maps a 0-based line of it to a 1-based source line.
- */
 export declare function collectDiagnostics(tokens: Token[], lines: string[], lineOf: (line0: number) => number | undefined): ParseDiagnostic[];
 export {};

package/dist/diagnostics.js

@@ -8,7 +8,7 @@
  * here: the parser passes any leaf through as a node of that type, and only a
  * renderer knows whether it can draw it (render-html reports the ones it can't).
  */
-import { GENERIC_CONTAINER, KNOWN_BLOCK_DIRECTIVES } from "./plugin-containers.js";
+import { BLOCK_LEAF_DIRECTIVES, GENERIC_CONTAINER } from "./plugin-containers.js";
 import { PRECEDES_TEXT } from "./plugin-inline-directives.js";
 /**
  * Whether a source line closes a container opened with `colons` colons. The
@@ -24,10 +24,54 @@ export const closesContainer = (line, colons) => line !== undefined && new RegEx
 export function closerLabel(comment) {
     return /^<!--\s*(?:end\s+|\/)?:*([A-Za-z][\w-]*)\s*-->$/.exec(comment.trim())?.[1];
 }
+/**
+ * The line of an attribute block a list or list item was given, so the diagnostic points at the
+ * braces rather than the first item. In `from`..`to`, the last line that is only `{…}`, else the
+ * last that ends with one (code lines skipped). With `after` (a list's block may follow it, past
+ * blank lines), only when the list has none: then a line that is only `{…}`. Else `from`.
+ */
+function braceLine(lines, code, from, to, after = false) {
+    const only = (l) => !code.has(l) && /^[\s>]*\{[^{}]*\}\s*$/.test(lines[l] ?? "");
+    const ends = (l) => !code.has(l) && /\{[^{}]*\}\s*$/.test(lines[l] ?? "");
+    const last = Math.min(to, lines.length - 1);
+    for (let l = last; l >= from; l--)
+        if (only(l))
+            return l;
+    for (let l = last; l >= from; l--)
+        if (ends(l))
+            return l;
+    if (after) {
+        let l = to;
+        while (l < lines.length && (lines[l] ?? "").trim() === "")
+            l++;
+        if (only(l))
+            return l;
+    }
+    return from;
+}
+/** A line with its inline code spans and `<…>` (raw HTML, autolinks) blanked, keeping offsets. */
+function blankCodeAndTags(line) {
+    return line.replace(/(`+)[\s\S]*?\1|<[^<>]*>/g, (c) => " ".repeat(c.length));
+}
+/** Lines inside fenced or indented code, from the tokens. */
+function codeLineSet(tokens) {
+    const out = new Set();
+    const walk = (list) => {
+        for (const t of list) {
+            if ((t.type === "fence" || t.type === "code_block") && t.map)
+                for (let l = t.map[0]; l < t.map[1]; l++)
+                    out.add(l);
+            if (t.children)
+                walk(t.children);
+        }
+    };
+    walk(tokens);
+    return out;
+}
 /** The inline directives the parser turns into nodes (parse.ts inlineDirectiveToNode); any other name stays literal text. */
 export const KNOWN_INLINE_DIRECTIVES = new Set(["kbd", "icon", "math", "mark", "highlight", "button", "badge"]);
 /** Directives that are blocks: `::name{…}` draws one only on a line of its own (parse.ts mapContainerToTreeNode). */
-const BLOCK_DIRECTIVES = new Set([...KNOWN_BLOCK_DIRECTIVES, "avatar", "child-links", "link-card", "openapi", "autodoc"]);
+const BLOCK_DIRECTIVES = new Set(BLOCK_LEAF_DIRECTIVES);
 /** Inline tokens markdown-it-attrs can give attributes to that the parser has no field for (links and images keep theirs). */
 const ATTRLESS_INLINE = { strong_open: "bold text", em_open: "italic text", s_open: "struck-through text", code_inline: "inline code" };
 /**
@@ -56,6 +100,20 @@ export function attributeProblem(block) {
  * Diagnostics for a token stream. `lines` is the parsed text split at `\n`;
  * `lineOf` maps a 0-based line of it to a 1-based source line.
  */
+/** Why a `:::youtube` block is wrong (its own body, or another block's closer), or undefined if it is the empty block with its own closer. */
+function youtubeAsBlock(map, closed, lines, around, lineOf) {
+    if (!closed)
+        return "is never closed, so it takes in everything after it";
+    if (lines.slice(map[0] + 1, map[1]).some((l) => l.replace(/^[\s>]*/, "") !== "")) {
+        return "is a block, and the lines up to its closer are dropped (a video shows no content)";
+    }
+    const parent = around[around.length - 1];
+    if (around.some((a) => a.map[1] === map[1]))
+        return `has no closer of its own: it ends with the :::${parent?.name ?? "block"} around it`;
+    if (parent && !parent.closed)
+        return `takes the closer on line ${lineOf(map[1]) ?? "?"}, which leaves :::${parent.name} open`;
+    return undefined;
+}
 export function collectDiagnostics(tokens, lines, lineOf) {
     const out = [];
     const add = (line0, code, message) => {
@@ -63,8 +121,16 @@ export function collectDiagnostics(tokens, lines, lineOf) {
         if (line !== undefined)
             out.push({ line, code, message });
     };
+    const code = codeLineSet(tokens);
+    let row;
+    // The `:::` blocks around the current token, outermost first
+    const around = [];
     const walk = (list) => {
-        for (const tok of list) {
+        // Indexed: i per token made the diagnostics quadratic in the page's length
+        for (let i = 0; i < list.length; i++) {
+            const tok = list[i];
+            if (/^container_.+_close$/.test(tok.type))
+                around.pop();
             const open = /^container_(.+)_open$/.exec(tok.type);
             if (open && tok.map) {
                 const generic = open[1] === GENERIC_CONTAINER;
@@ -74,7 +140,14 @@ export function collectDiagnostics(tokens, lines, lineOf) {
                 const closed = closesContainer(lines[tok.map[1]], colons);
                 const skipped = tok.meta?.skippedCloser;
                 const legacy = tok.meta?.legacyCloser;
-                if (!closed && legacy !== undefined && !generic) {
+                // A video has no body, so `:::youtube` is a block that has taken in what follows it, or a
+                // closer meant for another block. The leaf form says "no body" in the syntax
+                // (plans/youtube-leaf.md). A blank line in a quote is `>`, so quote markers are not content.
+                const leafAsBlock = name === "youtube" ? youtubeAsBlock(tok.map, closed, lines, around, lineOf) : undefined;
+                if (leafAsBlock) {
+                    add(tok.map[0], "leaf-as-block", `a video has no body: write ::youtube{…} on one line, with no closer — as :::youtube it ${leafAsBlock}`);
+                }
+                else if (!closed && legacy !== undefined && !generic) {
                     // Before the nesting stack, the closer on that line ended this block and the ones inside it
                     add(tok.map[0], "unclosed-container", `:::${name} is never closed — the ${lines[legacy]?.trim()} on line ${lineOf(legacy) ?? "?"} closes only the innermost open block; each block needs its own closer (one \`:::\` used to close several)`);
                 }
@@ -89,6 +162,9 @@ export function collectDiagnostics(tokens, lines, lineOf) {
                 else if (generic) {
                     add(tok.map[0], "unknown-container", `:::${name} is not a known directive — it is shown as a plain box`);
                 }
+                if (tok.meta?.unverified) {
+                    add(tok.map[0], "nesting-unchecked", `the parser stopped re-checking the nested blocks on this page here, so where :::${name} ends may be wrong — check that each block inside it has its own closer, or split the page`);
+                }
                 if (closed) {
                     // The closer's end-tag label: it closes this container whatever it says, so a wrong
                     // name means the author thinks it closes another one
@@ -103,6 +179,8 @@ export function collectDiagnostics(tokens, lines, lineOf) {
                     if (problem)
                         add(tok.map[0], "bad-attributes", `the attributes of :::${name} ${problem} — they are ignored`);
                 }
+                // An unknown block never closed is read back as text, so it is no parent (but still popped)
+                around.push({ map: tok.map, closed: closed || (generic && tok.meta?.unclosed === true), name });
             }
             // A `:::` line no open block took: every block it could close is already closed
             if (tok.type === "inline" && tok.map) {
@@ -136,13 +214,13 @@ export function collectDiagnostics(tokens, lines, lineOf) {
             // Attribute blocks markdown-it-attrs read and the tree has nowhere to keep
             if (tok.type === "list_item_open" && tok.map && tok.attrs?.length) {
                 // parse.ts keepListItemBraces puts trailing braces back as text, or on a heading; what is left had nowhere to go
-                add(tok.map[0], "dropped-attributes", `the attribute block on this list item is dropped — list items take no attributes`);
+                add(braceLine(lines, code, tok.map[0], tok.map[1] - 1), "dropped-attributes", `the attribute block on this list item is dropped — list items take no attributes`);
             }
             // A table row that is only an attribute block, where the parser could not move it onto the
             // table (not the last row, or text follows the table with no blank line): an empty row
             if (tok.type === "tr_open" && tok.map) {
                 const cells = [];
-                for (let k = list.indexOf(tok) + 1; k < list.length && list[k].type !== "tr_close"; k++)
+                for (let k = i + 1; k < list.length && list[k].type !== "tr_close"; k++)
                     cells.push(list[k]);
                 const inlines = cells.filter((c) => c.type === "inline");
                 if (cells[0]?.attrs?.length && /^\{[^{}]*\}$/.test((inlines[0]?.content ?? "").trim()) && inlines.slice(1).every((c) => c.content.trim() === "")) {
@@ -153,11 +231,11 @@ export function collectDiagnostics(tokens, lines, lineOf) {
             // Only real attribute names: markdown-it-attrs also reads a leftover include (`{* src.py hl[4] *}`, FastAPI) as keys
             const own = tok.attrs?.filter(([k]) => k !== "start") ?? [];
             if ((tok.type === "bullet_list_open" || tok.type === "ordered_list_open") && tok.map && own.length > 0 && own.every(([k]) => /^[A-Za-z_][\w:.-]*$/.test(k))) {
-                add(tok.map[0], "dropped-attributes", `the attribute block on this list is dropped — lists take no attributes`);
+                add(braceLine(lines, code, tok.map[0], tok.map[1], true), "dropped-attributes", `the attribute block on this list is dropped — lists take no attributes`);
             }
             // An attribute block alone on its line after a blank line: an empty paragraph that carries it
             if (tok.type === "paragraph_open" && tok.map && tok.attrs?.length) {
-                const inline = list[list.indexOf(tok) + 1];
+                const inline = list[i + 1];
                 // Only what an author writes as attributes: `{#id}`, `{.class}`, `{key=…}`. markdown-it-attrs also eats a
                 // leftover MDX expression (`{/* prettier-ignore */}`), which is an importer's problem, not the author's
                 const looksLikeAttrs = /^\{\s*(?:[#.][^\s{}]|[\w-]+\s*=)/.test(inline?.content.trim() ?? "");
@@ -185,20 +263,58 @@ export function collectDiagnostics(tokens, lines, lineOf) {
                     }
                 }
                 // `:kbd{…}` with no `[label]` is not a directive: the label is what it shows
+                const missing = (name) => `:${name}{…} has no [label] — it is shown as text; write :${name}[…]{…}`;
+                const inText = new Set();
+                // An autolink's text is its URL, not prose
+                let autolink = 0;
                 for (const child of tok.children) {
-                    if (child.type !== "text")
+                    if (child.type === "link_open" && (child.markup === "autolink" || child.markup === "linkify"))
+                        autolink++;
+                    if (child.type === "link_close" && autolink > 0)
+                        autolink--;
+                    if (child.type !== "text" || autolink > 0)
                         continue;
                     for (const m of child.content.matchAll(/:([a-z]+)\{/g)) {
                         if (m.index > 0 && PRECEDES_TEXT.test(child.content[m.index - 1]))
                             continue;
-                        if (KNOWN_INLINE_DIRECTIVES.has(m[1]))
-                            add(tok.map[0], "missing-label", `:${m[1]}{…} has no [label] — it is shown as text; write :${m[1]}[…]{…}`);
+                        if (KNOWN_INLINE_DIRECTIVES.has(m[1])) {
+                            inText.add(m[1]);
+                            let at = tok.map[0];
+                            while (at < tok.map[1] - 1 && !(lines[at] ?? "").includes(`:${m[1]}{`))
+                                at++;
+                            add(at, "missing-label", missing(m[1]));
+                        }
                     }
                 }
+                // At the end of a paragraph, heading or cell, markdown-it-attrs takes the braces for the
+                // block's own, leaving `:kbd` in the text: read the source lines for what is no longer there
+                if (list[i - 1]?.attrs?.length) {
+                    for (let l = tok.map[0]; l < tok.map[1]; l++) {
+                        const line = blankCodeAndTags(lines[l] ?? "");
+                        for (const m of line.matchAll(/:([a-z]+)\{/g)) {
+                            if (m.index > 0 && PRECEDES_TEXT.test(line[m.index - 1]))
+                                continue;
+                            if (KNOWN_INLINE_DIRECTIVES.has(m[1]) && !inText.has(m[1]) && !line.startsWith(`:${m[1]}[`, m.index)) {
+                                inText.add(m[1]);
+                                add(l, "missing-label", missing(m[1]));
+                            }
+                        }
+                    }
+                }
+            }
+            // A table cell's inline token has no line map: its row's has
+            if (tok.type === "tr_open" && tok.map)
+                row = tok.map[0];
+            if (tok.type === "inline" && !tok.map && row !== undefined && /^t[hd]_open$/.test(list[i - 1]?.type ?? "") && list[i - 1]?.attrs?.length) {
+                const cell = blankCodeAndTags(tok.content);
+                const m = /:([a-z]+)\{/.exec(cell);
+                if (m && KNOWN_INLINE_DIRECTIVES.has(m[1]) && !(m.index > 0 && PRECEDES_TEXT.test(cell[m.index - 1]))) {
+                    add(row, "missing-label", `:${m[1]}{…} has no [label] — it is shown as text; write :${m[1]}[…]{…}`);
+                }
             }
             // A heading's attribute block that markdown-it-attrs could not read stays in its text
             if (tok.type === "heading_open" && tok.map) {
-                const inline = list[list.indexOf(tok) + 1];
+                const inline = list[i + 1];
                 // markdown-it-attrs takes a block it reads out of the text tokens (not out of `content`)
                 const last = [...(inline?.children ?? [])].reverse().find((c) => c.type === "text");
                 const tail = /\{\s*(?:[#.][^{}]*|[\w-]+\s*=[^{}]*)\}?\s*$/.exec(last?.content ?? "");

package/dist/index.d.ts

@@ -8,12 +8,13 @@ export { transformCodeRegions, transformProseLines, transformProseSegments, fenc
 export { maskMinjaInCode, unmaskMinjaInCode, maskAllMinjaOpeners, isMinjaProcessedFence, stripInlineMinjaMarkers, stripFenceMinjaMarkers } from "./minja-mask.js";
 export type { ParseResult, ParseOptions } from "./parse.js";
 export { KNOWN_INLINE_DIRECTIVES, type ParseDiagnostic } from "./diagnostics.js";
-export { KNOWN_BLOCK_DIRECTIVES } from "./plugin-containers.js";
+export { KNOWN_BLOCK_DIRECTIVES, LEAF_ONLY_DIRECTIVES, BLOCK_LEAF_DIRECTIVES } from "./plugin-containers.js";
 export { buildNavFromDirectory } from "./nav.js";
 export type { BuildNavOptions } from "./nav.js";
 export { loadNavFile } from "./nav-file.js";
 export type { NavFile, NavFileItem, LoadNavFileOptions, MissingNavTarget, } from "./nav-file.js";
 export { renderDiagrams } from "./renderers/diagrams.js";
-export type { RenderDiagramsOptions } from "./renderers/diagrams.js";
+export type { RenderDiagramsOptions, DiagramEngine } from "./renderers/diagrams.js";
+export { renderPeleSvg, diagramId } from "./renderers/pele.js";
 export { renderMermaidSvg, setMmdcOverride, findMmdc } from "./renderers/mermaid.js";
 export { TemplatePages, TemplatePageError, declaresParams, ATTRIBUTE_BLOCK_OPEN, type TemplatePagesOptions } from "./template-pages.js";

package/dist/index.js

@@ -11,9 +11,10 @@ export { transformCodeRegions, transformProseLines, transformProseSegments, fenc
 export { maskMinjaInCode, unmaskMinjaInCode, maskAllMinjaOpeners, isMinjaProcessedFence, stripInlineMinjaMarkers, stripFenceMinjaMarkers } from "./minja-mask.js";
 export { KNOWN_INLINE_DIRECTIVES } from "./diagnostics.js";
 // The `:::name` blocks the parser knows (an editor completes names from it)
-export { KNOWN_BLOCK_DIRECTIVES } from "./plugin-containers.js";
+export { KNOWN_BLOCK_DIRECTIVES, LEAF_ONLY_DIRECTIVES, BLOCK_LEAF_DIRECTIVES } from "./plugin-containers.js";
 export { buildNavFromDirectory } from "./nav.js";
 export { loadNavFile } from "./nav-file.js";
 export { renderDiagrams } from "./renderers/diagrams.js";
+export { renderPeleSvg, diagramId } from "./renderers/pele.js";
 export { renderMermaidSvg, setMmdcOverride, findMmdc } from "./renderers/mermaid.js";
 export { TemplatePages, TemplatePageError, declaresParams, ATTRIBUTE_BLOCK_OPEN } from "./template-pages.js";

package/dist/parse-attrs.d.ts

@@ -21,3 +21,12 @@ export declare function parseAttrs(inner: string): ParsedAttrs;
  * `id` and `classes` become `id` and `class`; other props flow through.
  */
 export declare function attrsToProps(attrs: ParsedAttrs): Record<string, unknown>;
+/**
+ * The index of the `}` that closes an attribute block whose `{` is just before `start`, or -1.
+ * Braces inside a double-quoted value (`title="a } b"`, with `\"` escapes, as escapeAttrValue
+ * writes them) do not count: a brace-only count ended a leaf `::youtube{#a title="a } b"}` at the
+ * first `}` and lost the video. A `"` opens a value only straight after `=`, as parseAttrs reads
+ * it: a stray `"` in an unquoted value (`title=5"`) is a character, or the scan would run on through
+ * the paragraph. Single quotes are not quotes here, so an apostrophe reads as before.
+ */
+export declare function attrBlockEnd(src: string, start: number, max: number): number;

package/dist/parse-attrs.js

@@ -114,3 +114,31 @@ export function attrsToProps(attrs) {
     }
     return props;
 }
+/**
+ * The index of the `}` that closes an attribute block whose `{` is just before `start`, or -1.
+ * Braces inside a double-quoted value (`title="a } b"`, with `\"` escapes, as escapeAttrValue
+ * writes them) do not count: a brace-only count ended a leaf `::youtube{#a title="a } b"}` at the
+ * first `}` and lost the video. A `"` opens a value only straight after `=`, as parseAttrs reads
+ * it: a stray `"` in an unquoted value (`title=5"`) is a character, or the scan would run on through
+ * the paragraph. Single quotes are not quotes here, so an apostrophe reads as before.
+ */
+export function attrBlockEnd(src, start, max) {
+    let depth = 1;
+    let quoted = false;
+    for (let i = start; i < max; i++) {
+        const c = src.charCodeAt(i);
+        if (quoted) {
+            if (c === 0x5c /* \ */)
+                i++;
+            else if (c === 0x22 /* " */)
+                quoted = false;
+        }
+        else if (c === 0x22 && i > start && src.charCodeAt(i - 1) === 0x3d /* = */)
+            quoted = true;
+        else if (c === 0x7b /* { */)
+            depth++;
+        else if (c === 0x7d /* } */ && --depth === 0)
+            return i;
+    }
+    return -1;
+}

package/dist/plugin-block-leaf.js

@@ -1,4 +1,4 @@
-import { parseAttrs } from "./parse-attrs.js";
+import { attrBlockEnd, parseAttrs } from "./parse-attrs.js";
 export function blockLeafDirectivePlugin(md) {
     md.block.ruler.before("paragraph", "dogsbay_block_leaf_directive", blockLeafRule);
 }
@@ -42,20 +42,8 @@ function blockLeafRule(state, startLine, endLine, silent) {
     let attrsStr = "";
     if (state.src.charCodeAt(pos) === 0x7b /* { */) {
         const attrStart = pos + 1;
-        let depth = 1;
-        let ap = attrStart;
-        while (ap < max) {
-            const c = state.src.charCodeAt(ap);
-            if (c === 0x7b)
-                depth++;
-            else if (c === 0x7d) {
-                depth--;
-                if (depth === 0)
-                    break;
-            }
-            ap++;
-        }
-        if (ap >= max)
+        const ap = attrBlockEnd(state.src, attrStart, max);
+        if (ap < 0)
             return false; // unterminated
         attrsStr = state.src.slice(attrStart, ap);
         pos = ap + 1;

package/dist/plugin-containers.d.ts

@@ -7,6 +7,19 @@
  */
 import type MarkdownIt from "markdown-it";
 export declare const KNOWN_BLOCK_DIRECTIVES: readonly ["tabs", "tab", "steps", "step", "cards", "card", "grid", "grid-item", "details", "callout", "note", "tip", "info", "important", "warning", "caution", "danger", "success", "hint", "attention", "error", "failure", "bug", "question", "abstract", "quote", "button", "figure", "math", "api-endpoint", "api-params", "api-response", "config", "files", "example", "accordion", "accordion-item", "link-card", "autodoc", "api-class", "api-member", "api-doc", "api-source", "youtube", "openapi", "theme"];
+/**
+ * Directives with no body, written only as the leaf `::name{…}` (parse.ts mapContainerToTreeNode
+ * drops any children; the serializer writes `::`). `youtube` is also a container above, for the
+ * empty `:::youtube{…}` + `:::` older serializers wrote; `:::avatar` and `:::child-links` are not
+ * blocks at all. Exported for editors, so completion does not offer `:::` or a closer for them.
+ */
+export declare const LEAF_ONLY_DIRECTIVES: readonly string[];
+/**
+ * Every name `::name{…}` draws as a block on a line of its own: the containers (an empty one,
+ * `::grid-item{…}` = `:::grid-item{…}` + `:::`) and the body-less leaves. Inside a line, these
+ * are reported (`block-directive-inline`) and kept as text.
+ */
+export declare const BLOCK_LEAF_DIRECTIVES: readonly string[];
 /**
  * The token name for a `:::name` block with a name no renderer knows. It becomes a node of that
  * type (parse.ts), which renderers show as a plain container and report, rather than literal text.

package/dist/plugin-containers.js

@@ -54,8 +54,9 @@ export const KNOWN_BLOCK_DIRECTIVES = [
     "api-member",
     "api-doc",
     "api-source",
-    // Lazy-loading video embed (YouTube). Leaf component — no body, just
-    // `:::youtube{#<videoId> title="…"}`. Renders via @ui/youtube/YouTube.astro.
+    // Lazy-loading video embed (YouTube). No body, so written as the leaf
+    // `::youtube{#<videoId> title="…"}`; the block form here is the empty
+    // `:::youtube{…}` + `:::` earlier serializers wrote. Renders via @ui/youtube/YouTube.astro.
     "youtube",
     // An OpenAPI spec embedded in a page: `:::openapi{spec="api.yaml"}`,
     // expanded into endpoint cards from the spec at build time (the
@@ -65,6 +66,19 @@ export const KNOWN_BLOCK_DIRECTIVES = [
     // set (plans/dita-variants-themes.md). A wrapper, so it takes blocks.
     "theme",
 ];
+/**
+ * Directives with no body, written only as the leaf `::name{…}` (parse.ts mapContainerToTreeNode
+ * drops any children; the serializer writes `::`). `youtube` is also a container above, for the
+ * empty `:::youtube{…}` + `:::` older serializers wrote; `:::avatar` and `:::child-links` are not
+ * blocks at all. Exported for editors, so completion does not offer `:::` or a closer for them.
+ */
+export const LEAF_ONLY_DIRECTIVES = ["youtube", "avatar", "child-links"];
+/**
+ * Every name `::name{…}` draws as a block on a line of its own: the containers (an empty one,
+ * `::grid-item{…}` = `:::grid-item{…}` + `:::`) and the body-less leaves. Inside a line, these
+ * are reported (`block-directive-inline`) and kept as text.
+ */
+export const BLOCK_LEAF_DIRECTIVES = [...KNOWN_BLOCK_DIRECTIVES, ...LEAF_ONLY_DIRECTIVES.filter((n) => !KNOWN_BLOCK_DIRECTIVES.includes(n))];
 /**
  * The token name for a `:::name` block with a name no renderer knows. It becomes a node of that
  * type (parse.ts), which renderers show as a plain container and report, rather than literal text.
@@ -72,8 +86,7 @@ export const KNOWN_BLOCK_DIRECTIVES = [
 export const GENERIC_CONTAINER = "dogsbay_generic";
 export function containersPlugin(md) {
     for (const name of KNOWN_BLOCK_DIRECTIVES) {
-        // `:::youtube{#id}` has no body, and is often written with no closer
-        registerOpener(name, { leaf: name === "youtube" });
+        registerOpener(name);
         containerRule(md, name, {
             validate: (params) => {
                 const trimmed = params.trim();

package/dist/plugin-inline-directives.js

@@ -1,4 +1,4 @@
-import { parseAttrs } from "./parse-attrs.js";
+import { attrBlockEnd, parseAttrs } from "./parse-attrs.js";
 /** A character a directive cannot follow directly (see inlineDirectiveRule). */
 export const PRECEDES_TEXT = /[\p{Script=Latin}\p{Script=Greek}\p{Script=Cyrillic}0-9:]/u;
 export function inlineDirectivesPlugin(md) {
@@ -78,20 +78,8 @@ function inlineDirectiveRule(state, silent) {
     let attrs = "";
     if (src.charCodeAt(pos) === 0x7b /* { */) {
         const attrStart = pos + 1;
-        let depth = 1;
-        let ap = attrStart;
-        while (ap < src.length) {
-            const c = src.charCodeAt(ap);
-            if (c === 0x7b)
-                depth++;
-            else if (c === 0x7d) {
-                depth--;
-                if (depth === 0)
-                    break;
-            }
-            ap++;
-        }
-        if (ap < src.length) {
+        const ap = attrBlockEnd(src, attrStart, src.length);
+        if (ap >= 0) {
             attrs = src.slice(attrStart, ap);
             pos = ap + 1;
         }

package/dist/renderers/diagrams.d.ts

@@ -1,5 +1,9 @@
 import type { TreeNode } from "@dogsbay/types";
+/** Who draws Mermaid fences (`content.diagrams`): mmdc, as Mermaid draws them, or Pele, themed. */
+export type DiagramEngine = "mermaid-cli" | "pele";
 export interface RenderDiagramsOptions {
+    /** Default `mermaid-cli`. */
+    engine?: DiagramEngine;
     /**
      * Suppress the one-time "mmdc not found" warning printed when
      * the binary can't be resolved. Default false. Tests pass true

package/dist/renderers/diagrams.js

@@ -1,4 +1,5 @@
 import { renderMermaidSvg } from "./mermaid.js";
+import { diagramId, renderPeleSvg } from "./pele.js";
 const DIAGRAM_LANGS = new Set(["mermaid"]);
 /**
  * Walk a TreeNode tree and replace `code` blocks with a diagram
@@ -16,6 +17,10 @@ const DIAGRAM_LANGS = new Set(["mermaid"]);
  */
 export async function renderDiagrams(tree, options) {
     let warned = false;
+    const pele = options?.engine === "pele";
+    // Pele: a diagram shown twice on the page gets its own ids the second time
+    const seen = new Map();
+    const failed = [];
     async function walk(nodes) {
         for (const node of nodes) {
             if (node.children)
@@ -42,7 +47,20 @@ export async function renderDiagrams(tree, options) {
                     : "";
             if (!code)
                 continue;
-            const svg = await renderMermaidSvg(code);
+            let svg;
+            if (pele) {
+                const base = diagramId(code);
+                const n = (seen.get(base) ?? 0) + 1;
+                seen.set(base, n);
+                const r = await renderPeleSvg(code, n === 1 ? base : `${base}-${n}`);
+                if ("error" in r) {
+                    failed.push(r.error);
+                    continue;
+                }
+                svg = r.svg;
+            }
+            else
+                svg = await renderMermaidSvg(code);
             if (svg === null) {
                 if (!warned && !options?.silent) {
                     console.warn("[diagrams] mmdc (mermaid-cli) not installed or render " +
@@ -67,4 +85,8 @@ export async function renderDiagrams(tree, options) {
         }
     }
     await walk(tree);
+    if (failed.length > 0 && !options?.silent) {
+        console.warn(`[diagrams] Pele could not draw ${failed.length} diagram(s), left as code blocks: ` +
+            failed[0].split("\n")[0].slice(0, 160));
+    }
 }

package/dist/renderers/pele.d.ts

@@ -0,0 +1,13 @@
+/** Longest diagram source drawn; a longer one is refused rather than laid out (as dogsbay-ssg). */
+export declare const MAX_DIAGRAM_CHARS = 100000;
+/**
+ * Draw one diagram. `id` prefixes the ids Pele writes (a title and description, for
+ * aria-labelledby), so two diagrams on a page do not share them.
+ */
+export declare function renderPeleSvg(code: string, id: string): Promise<{
+    svg: string;
+} | {
+    error: string;
+}>;
+/** A stable id from the source, valid in XML (`dg-` and hex). */
+export declare function diagramId(code: string): string;

package/dist/renderers/pele.js

@@ -0,0 +1,42 @@
+/**
+ * Mermaid drawn by Pele (`content.diagrams: pele`; plans/pele-diagrams.md): plain JavaScript,
+ * synchronous, no DOM and no browser, unlike mmdc. Its colours and fonts are CSS variables
+ * (`--pele-*`), which DocsLayout maps to the site theme, so a diagram follows light and dark mode
+ * instead of being inverted.
+ *
+ * Loaded with import() on the first diagram: a site without diagrams, or one drawn by mmdc,
+ * never loads it. dogsbay-ssg draws diagrams the same way (its core/pele.ts).
+ */
+import { createHash } from "node:crypto";
+/** Longest diagram source drawn; a longer one is refused rather than laid out (as dogsbay-ssg). */
+export const MAX_DIAGRAM_CHARS = 100_000;
+let pele;
+/**
+ * Draw one diagram. `id` prefixes the ids Pele writes (a title and description, for
+ * aria-labelledby), so two diagrams on a page do not share them.
+ */
+export async function renderPeleSvg(code, id) {
+    if (code.length > MAX_DIAGRAM_CHARS)
+        return { error: `the diagram is longer than ${MAX_DIAGRAM_CHARS} characters` };
+    let p;
+    try {
+        p = await (pele ??= import("pele"));
+    }
+    catch (e) {
+        pele = undefined;
+        return { error: `could not load Pele (pele): ${e instanceof Error ? e.message : String(e)}` };
+    }
+    try {
+        // No images: an `img:` node would have every reader fetch its URL (a third-party one too),
+        // and a local path is neither copied as an asset nor given the site's base path
+        const { svg } = p.render(code, { idPrefix: id, limit: MAX_DIAGRAM_CHARS, images: false });
+        return svg ? { svg } : { error: "Pele returned no SVG" };
+    }
+    catch (e) {
+        return { error: e instanceof Error ? e.message : String(e) };
+    }
+}
+/** A stable id from the source, valid in XML (`dg-` and hex). */
+export function diagramId(code) {
+    return "dg-" + createHash("sha256").update(code).digest("hex").slice(0, 12);
+}

package/dist/serialize.js

@@ -116,8 +116,9 @@ function renderNodeBody(node, ctx) {
         case "button":
             return renderButton(node, ctx);
         case "youtube":
-            // Leaf embed — `:::youtube{#<id> title="…"}` with no body.
-            return renderBlockDirective({ name: "youtube", props: { ...(node.props ?? {}), id: node.props?.id }, body: "" }, ctx);
+            // A video has no body, so it is a leaf: `::youtube{#<id> title="…"}`. `:::` always opens a
+            // block that needs a closer (the empty `:::youtube` … `:::` form still reads).
+            return `::youtube${renderAttrs(splitProps({ ...(node.props ?? {}), id: node.props?.id }, []))}`;
         case "deflist":
             return renderDeflist(node, ctx);
         case "theme":

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@dogsbay/format-dogsbay-md",
-  "version": "0.2.0-beta.127",
+  "version": "0.2.0-beta.129",
   "description": "Dogsbay Markdown dialect — canonical format for TreeNode[] with directives, YAML bodies, and intelligent fallbacks",
   "type": "module",
   "main": "dist/index.js",
@@ -24,12 +24,12 @@
     "README.md"
   ],
   "devDependencies": {
+    "@mermaid-js/mermaid-cli": "^11.16.0",
     "@types/js-yaml": "^4.0.9",
     "@types/markdown-it": "^14.1.2",
     "@types/node": "^25.9.5",
     "typescript": "^5.9.3",
-    "vitest": "^4.1.10",
-    "@mermaid-js/mermaid-cli": "^11.16.0"
+    "vitest": "^4.1.10"
   },
   "dependencies": {
     "gray-matter": "^4.0.3",
@@ -39,9 +39,10 @@
     "markdown-it-deflist": "^3.0.1",
     "markdown-it-footnote": "^4.0.0",
     "markdown-it-front-matter": "^0.2.4",
-    "@dogsbay/minja": "0.2.0-beta.127",
-    "@dogsbay/serialize-core": "0.2.0-beta.127",
-    "@dogsbay/types": "0.2.0-beta.127"
+    "pele": "1.6.0",
+    "@dogsbay/minja": "0.2.0-beta.129",
+    "@dogsbay/serialize-core": "0.2.0-beta.129",
+    "@dogsbay/types": "0.2.0-beta.129"
   },
   "license": "MIT",
   "repository": {