@dogsbay/format-dogsbay-md 0.2.0-beta.136 → 0.2.0-beta.138

package/dist/data-directives.js

@@ -192,9 +192,19 @@ export function literalCode(value) {
 }
 const list = (v) => typeof v === "string" && v.trim() ? v.split(",").map((s) => s.trim()) : undefined;
 function tableNode(rows, props, file) {
+    // A page never shows an empty table (docs/data-files.md): a file with no entries is reported.
+    if (rows.length === 0)
+        throw new DirectiveError(`${file} has no entries to show`);
     const columns = list(props.columns) ?? [...new Set(rows.flatMap((r) => Object.keys(r)))];
     if (columns.length === 0)
         throw new DirectiveError(`${file} has no columns to show`);
+    // A column no row has is a typo, not an optional field: it showed as an empty column.
+    const known = [...new Set(rows.flatMap((r) => Object.keys(r)))];
+    const missing = columns.filter((c) => !known.includes(c));
+    if (missing.length > 0) {
+        const has = known.length === 0 ? "it has no fields" : `it has ${known.slice(0, 12).join(", ")}${known.length > 12 ? `, … ${known.length - 12} more` : ""}`;
+        throw new DirectiveError(`${file} has no ${missing.map((c) => `"${c}"`).join(", ")} column (${has})`);
+    }
     const headers = list(props.headers) ?? columns;
     if (headers.length !== columns.length) {
         throw new DirectiveError(`headers names ${headers.length} column(s), columns ${columns.length}`);

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" | "leaf-as-block" | "nesting-unchecked";
+    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" | "unknown-prop";
     message: string;
     /**
      * The directive's name, without colons, on `unknown-container` and `unknown-inline`: a host that

package/dist/diagnostics.js

@@ -9,7 +9,9 @@
  * renderer knows whether it can draw it (render-html reports the ones it can't).
  */
 import { BLOCK_LEAF_DIRECTIVES, GENERIC_CONTAINER } from "./plugin-containers.js";
-import { PRECEDES_TEXT } from "./plugin-inline-directives.js";
+import { LABEL_PROP } from "./plugin-inline-directives.js";
+import { unknownProps } from "./directive-props.js";
+import * as yaml from "js-yaml";
 /**
  * Whether a source line closes a container opened with `colons` colons. The
  * line may sit in a blockquote or a list item: its `>` markers and
@@ -119,6 +121,22 @@ const clip = (line) => {
     const t = (line ?? "").trim();
     return t.length > 60 ? `${t.slice(0, 59)}…` : t;
 };
+/** The keys of a known container's parsed attrs (`tok.meta.attrs`), the lifted YAML block's included. */
+function propKeysOfAttrs(props) {
+    const keys = Object.keys(props).filter((k) => k !== "__yaml__");
+    const encoded = props.__yaml__;
+    if (typeof encoded === "string") {
+        try {
+            const loaded = yaml.load(decodeURIComponent(encoded));
+            if (loaded && typeof loaded === "object" && !Array.isArray(loaded))
+                keys.push(...Object.keys(loaded));
+        }
+        catch {
+            /* not YAML: nothing to check */
+        }
+    }
+    return keys;
+}
 export function collectDiagnostics(tokens, lines, lineOf) {
     const out = [];
     const add = (line0, code, message, name) => {
@@ -167,6 +185,16 @@ 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`, name);
                 }
+                else {
+                    // A prop no renderer of this directive reads is carried, never drawn: say so (a typo
+                    // in a `{…}` or `---` block was silent). Keys from both forms; the YAML block arrives
+                    // lifted into `__yaml__` by preprocessYamlBodies.
+                    // markdown-it-attrs put the opener's `{…}` on the token's attrs; the lifted YAML block is `__yaml__`
+                    const pairs = (tok.attrs ?? []);
+                    for (const key of unknownProps(name, propKeysOfAttrs(Object.fromEntries(pairs)))) {
+                        add(tok.map[0], "unknown-prop", `${key} is not a prop of :::${name} — it is kept but not drawn`, name);
+                    }
+                }
                 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`);
                 }
@@ -195,24 +223,48 @@ export function collectDiagnostics(tokens, lines, lineOf) {
                     }
                 });
             }
-            if (tok.type === "inline" && tok.map && tok.children) {
+            // A table cell's inline token has no line map: its row's line stands in
+            if (tok.type === "inline" && (tok.map || row !== undefined) && tok.children) {
+                const base = tok.map ? tok.map[0] : row;
                 const text = tok.content ?? "";
                 let from = 0;
                 for (const child of tok.children) {
                     if (child.type !== "dogsbay_inline_directive_open" && child.type !== "dogsbay_leaf_directive")
                         continue;
+                    // `:kbd{…}` with no `[label]` and no `value=`: nothing to show, so it stays as written
+                    if (child.type === "dogsbay_inline_directive_open" && child.meta?.labelless && KNOWN_INLINE_DIRECTIVES.has(child.tag)) {
+                        const key = LABEL_PROP[child.tag];
+                        let props = {};
+                        try {
+                            props = JSON.parse(child.info || "{}").props ?? {};
+                        }
+                        catch {
+                            /* no attrs */
+                        }
+                        if (key && typeof props[key] !== "string") {
+                            const form = `:${child.tag}{`;
+                            const at = text.indexOf(form, from);
+                            from = at >= 0 ? at + form.length : from;
+                            const offset = at >= 0 ? (text.slice(0, at).match(/\n/g) ?? []).length : 0;
+                            add(base + offset, "missing-label", `:${child.tag}{…} has no label — it is shown as text; write :${child.tag}[…]{…} or :${child.tag}{${key}="…"}`);
+                        }
+                        continue;
+                    }
                     if (KNOWN_INLINE_DIRECTIVES.has(child.tag))
                         continue;
+                    // an unknown `:name{…}` (a CSS `:root{…}` in prose) is kept as written: nothing to report
+                    if (child.type === "dogsbay_inline_directive_open" && child.meta?.labelless)
+                        continue;
                     const form = child.type === "dogsbay_leaf_directive" ? `::${child.tag}` : `:${child.tag}[`;
                     const at = text.indexOf(form, from);
                     from = at >= 0 ? at + form.length : from;
                     const offset = at >= 0 ? (text.slice(0, at).match(/\n/g) ?? []).length : 0;
                     const shown = child.type === "dogsbay_leaf_directive" ? `::${child.tag}` : `:${child.tag}[…]`;
                     if (child.type === "dogsbay_leaf_directive" && BLOCK_DIRECTIVES.has(child.tag)) {
-                        add(tok.map[0] + offset, "block-directive-inline", `${shown} is a block directive — inside a line of text it is shown as text; put it on a line of its own`);
+                        add(base + offset, "block-directive-inline", `${shown} is a block directive — inside a line of text it is shown as text; put it on a line of its own`);
                     }
                     else {
-                        add(tok.map[0] + offset, "unknown-inline", `${shown} is not a known inline directive — it is shown as text`, child.tag);
+                        add(base + offset, "unknown-inline", `${shown} is not a known inline directive — it is shown as text`, child.tag);
                     }
                 }
             }
@@ -263,60 +315,24 @@ export function collectDiagnostics(tokens, lines, lineOf) {
                         parsed = JSON.parse(child.info || "{}");
                     }
                     catch { /* not ours */ }
-                    if (parsed.id || parsed.classes?.length || Object.keys(parsed.props ?? {}).length) {
-                        add(tok.map[0], "dropped-attributes", `the attribute block on :${child.tag}[…] is dropped — of the inline directives only :badge and :button take attributes`);
-                    }
-                }
-                // `: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 === "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]))
+                    const props = { ...(parsed.props ?? {}) };
+                    // the label-less form's naming prop IS the label (`:kbd{value="Ctrl"}`); without it the
+                    // directive stays as written and `missing-label` has said so
+                    if (child.meta?.labelless) {
+                        const key = LABEL_PROP[child.tag];
+                        if (key && typeof props[key] !== "string")
                             continue;
-                        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]));
-                        }
+                        if (key)
+                            delete props[key];
                     }
-                }
-                // 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]));
-                            }
-                        }
+                    if (parsed.id || parsed.classes?.length || Object.keys(props).length) {
+                        add(tok.map[0], "dropped-attributes", `the attribute block on :${child.tag}[…] is dropped — of the inline directives only :badge and :button take attributes`);
                     }
                 }
             }
             // 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[i + 1];

package/dist/directive-props.d.ts

@@ -0,0 +1,15 @@
+/**
+ * The props each known directive DRAWS, for the `unknown-prop` diagnostic (2026-10-27): a key
+ * a renderer does not read is carried through every round trip but drawn by nothing, and a
+ * typo in a `{…}` block or a `---` props block was silent. The lists are the union of what
+ * docs/dogsbay-md.md documents and what format-astro's and render-html's renderers read; a
+ * directive not listed here is not checked (api-*, autodoc, openapi, config, theme, example:
+ * their props are open-ended or read from a spec).
+ *
+ * Always allowed on anything: `id`, `class`, `style`, `role`, `data-*`, `aria-*` (passed
+ * through to the element), and `type`/`title`/`icon` on the callout names.
+ */
+export declare const PASSTHROUGH_PROP: RegExp;
+export declare const DIRECTIVE_PROPS: Readonly<Record<string, readonly string[]>>;
+/** Keys of `props` that `name` does not draw; empty when the directive is not checked. */
+export declare function unknownProps(name: string, props: Iterable<string>): string[];

package/dist/directive-props.js

@@ -0,0 +1,50 @@
+/**
+ * The props each known directive DRAWS, for the `unknown-prop` diagnostic (2026-10-27): a key
+ * a renderer does not read is carried through every round trip but drawn by nothing, and a
+ * typo in a `{…}` block or a `---` props block was silent. The lists are the union of what
+ * docs/dogsbay-md.md documents and what format-astro's and render-html's renderers read; a
+ * directive not listed here is not checked (api-*, autodoc, openapi, config, theme, example:
+ * their props are open-ended or read from a spec).
+ *
+ * Always allowed on anything: `id`, `class`, `style`, `role`, `data-*`, `aria-*` (passed
+ * through to the element), and `type`/`title`/`icon` on the callout names.
+ */
+export const PASSTHROUGH_PROP = /^(?:id|class|style|role|data-[\w-]+|aria-[\w-]+)$/;
+const CALLOUT = ["type", "title", "icon", "collapsed", "collapsible", "open", "tone", "variant", "href"];
+const CALLOUT_NAMES = ["callout", "note", "tip", "info", "important", "warning", "caution", "danger", "success", "hint", "attention", "error", "failure", "bug", "question", "abstract", "quote"];
+export const DIRECTIVE_PROPS = {
+    ...Object.fromEntries(CALLOUT_NAMES.map((n) => [n, CALLOUT])),
+    details: ["title", "summary", "icon", "open", "variant", "type", "sheet"],
+    tabs: ["variant", "sync", "syncKey", "group", "title", "value", "label"],
+    tab: ["title", "label", "icon", "value"],
+    steps: ["title"],
+    step: ["title"],
+    cards: ["cols", "tone", "variant"],
+    card: ["title", "href", "icon", "description", "tone", "variant", "image", "alt"],
+    "link-card": ["href", "title", "description", "icon"],
+    grid: ["cols", "gap"],
+    "grid-item": ["span", "rowSpan", "label", "tone"],
+    figure: ["caption", "src", "alt"],
+    files: [],
+    button: ["href", "variant", "label", "size"],
+    youtube: ["id", "title", "poster"],
+    avatar: ["src", "alt", "fallback", "source", "size"],
+    accordion: ["type", "defaultValue", "variant"],
+    "accordion-item": ["title", "label", "value", "open"],
+    math: [],
+    "data-table": ["src", "columns", "caption", "sortable", "filter", "paginate"],
+    "data-cards": ["src", "cols", "tone"],
+    "child-links": ["depth", "title"],
+};
+/** Keys of `props` that `name` does not draw; empty when the directive is not checked. */
+export function unknownProps(name, props) {
+    const known = DIRECTIVE_PROPS[name];
+    if (!known)
+        return [];
+    const set = new Set(known);
+    const out = [];
+    for (const key of props)
+        if (!set.has(key) && !PASSTHROUGH_PROP.test(key) && key !== "__yaml__")
+            out.push(key);
+    return out;
+}

package/dist/directives.d.ts

@@ -16,3 +16,5 @@ export interface DirectiveRenderInput {
  * the component, option threshold, and prop complexity.
  */
 export declare function renderBlockDirective(input: DirectiveRenderInput, ctx: ResolvedOptions): string;
+/** A body whose first line is `---` gets a blank line before it, so the parser reads a rule, not props. */
+export declare function guardRule(body: string): string;

package/dist/directives.js

@@ -11,7 +11,7 @@
  */
 import { renderAttrs, splitProps } from "./attributes.js";
 import { pickDirectiveFence } from "./escape.js";
-import { renderYaml } from "./yaml.js";
+import { renderYamlReadable } from "./yaml.js";
 /**
  * Render a block directive. Chooses attrs-form vs yaml-body form based on
  * the component, option threshold, and prop complexity.
@@ -20,16 +20,20 @@ export function renderBlockDirective(input, ctx) {
     const { name, props, excludeProps = [], body = "" } = input;
     const yamlEligible = input.yamlEligible ?? ctx.yamlComponents.has(name);
     const attrs = splitProps(props, excludeProps);
-    const useYaml = yamlEligible && shouldUseYaml(attrs, ctx);
+    // The parser reads a `---` props block on every directive (2026-10-27), so a nested value —
+    // which the inline form cannot carry and used to be dropped — takes the YAML form anywhere.
+    const useYaml = (yamlEligible && shouldUseYaml(attrs, ctx)) || needsYamlForm(attrs);
     const fence = pickDirectiveFence(useYaml ? body + "\n---" : body);
     if (!useYaml) {
         const attrStr = renderAttrs(attrs);
         const opener = attrStr ? `${fence}${name}${attrStr}` : `${fence}${name}`;
-        return `${opener}\n${body}\n${fence}`;
+        // A body that opens with a horizontal rule would read as a `---` props block on the way
+        // back (the parser reads one on every directive): a blank line keeps it a rule.
+        return `${opener}\n${guardRule(body)}\n${fence}`;
     }
     // YAML body form — emit all props (including id, classes) as yaml keys
     const yamlData = attrsToYaml(attrs);
-    const yaml = renderYaml(yamlData);
+    const yaml = renderYamlReadable(yamlData);
     const header = yaml.length > 0 ? `---\n${yaml}\n---` : "";
     if (!body) {
         return `${fence}${name}\n${header}\n${fence}`;
@@ -50,6 +54,14 @@ export function renderBlockDirective(input, ctx) {
  *     form has no syntax for those — without YAML they get
  *     dropped by `renderAttrs`).
  */
+/** A value the inline form cannot carry: nested, or a string with a newline (the inline form flattens it to spaces). */
+function needsYamlForm(attrs) {
+    return Object.values(attrs.props ?? {}).some((v) => (v !== null && typeof v === "object") || (typeof v === "string" && v.includes("\n")));
+}
+/** A body whose first line is `---` gets a blank line before it, so the parser reads a rule, not props. */
+export function guardRule(body) {
+    return /^---[ \t]*(\r?\n|$)/.test(body) ? `\n${body}` : body;
+}
 function shouldUseYaml(attrs, ctx) {
     const propCount = (attrs.id ? 1 : 0) +
         (attrs.classes?.length ?? 0) +

package/dist/index.d.ts

@@ -9,6 +9,7 @@ export { maskMinjaInCode, unmaskMinjaInCode, maskAllMinjaOpeners, isMinjaProcess
 export type { ParseResult, ParseOptions } from "./parse.js";
 export { KNOWN_INLINE_DIRECTIVES, type ParseDiagnostic } from "./diagnostics.js";
 export { KNOWN_BLOCK_DIRECTIVES, LEAF_ONLY_DIRECTIVES, BLOCK_LEAF_DIRECTIVES } from "./plugin-containers.js";
+export { DIRECTIVE_PROPS, PASSTHROUGH_PROP, unknownProps } from "./directive-props.js";
 export { buildNavFromDirectory } from "./nav.js";
 export type { BuildNavOptions } from "./nav.js";
 export { loadNavFile } from "./nav-file.js";

package/dist/index.js

@@ -12,6 +12,7 @@ export { maskMinjaInCode, unmaskMinjaInCode, maskAllMinjaOpeners, isMinjaProcess
 export { KNOWN_INLINE_DIRECTIVES } from "./diagnostics.js";
 // The `:::name` blocks the parser knows (an editor completes names from it)
 export { KNOWN_BLOCK_DIRECTIVES, LEAF_ONLY_DIRECTIVES, BLOCK_LEAF_DIRECTIVES } from "./plugin-containers.js";
+export { DIRECTIVE_PROPS, PASSTHROUGH_PROP, unknownProps } from "./directive-props.js";
 export { buildNavFromDirectory } from "./nav.js";
 export { loadNavFile } from "./nav-file.js";
 export { renderDiagrams } from "./renderers/diagrams.js";

package/dist/inline.js

@@ -194,7 +194,7 @@ function renderInline(node) {
         case "highlight":
             return `==${inlineToDogsbayMd(node.children)}==`;
         case "kbd":
-            return `:kbd[${node.keys.join("+")}]`;
+            return `:kbd[${node.keys.join("+").replace(/[\\[\]]/g, "\\$&")}]`;
         case "badge":
             return `:badge[${node.text.replace(/[\\[\]]/g, "\\$&")}]${renderInlineAttrs(node.variant !== undefined ? { variant: node.variant, ...node.attrs } : node.attrs)}`;
         case "icon":
@@ -307,9 +307,9 @@ function renderIcon(node) {
         }
     }
     if (extraAttrs.length === 0) {
-        return `:icon[${fullName}]`;
+        return `:icon[${fullName.replace(/[\\[\]]/g, "\\$&")}]`;
     }
-    return `:icon[${fullName}]{${extraAttrs.join(" ")}}`;
+    return `:icon[${fullName.replace(/[\\[\]]/g, "\\$&")}]{${extraAttrs.join(" ")}}`;
 }
 /**
  * Escape markdown-active characters in inline text.
@@ -327,6 +327,9 @@ function escapeInlineTextSegment(text) {
     return text
         .replace(/\\/g, "\\\\")
         .replace(/([*`\[\]])/g, "\\$1")
+        // `:name{` would read as a label-less inline directive (2026-10-27): the brace is escaped the
+        // way `[` is for `:name[`. Text is literal; a round trip must never make a directive of it.
+        .replace(/(^|[^\w:]):([A-Za-z][\w-]*)\{/g, "$1:$2\\{")
         // Text that looks like a tag or autolink (`<draft-comment>`) would render as HTML
         .replace(/<(?=[A-Za-z/!?])/g, "\\<")
         // One pass: escaping `_` at a word start and then at a word end double-escaped `(_)`

package/dist/parse-attrs.d.ts

@@ -16,6 +16,12 @@ export interface ParsedAttrs {
     props: Record<string, string | boolean>;
 }
 export declare function parseAttrs(inner: string): ParsedAttrs;
+/**
+ * Whether `inner` is ONLY a list of attributes, as parseAttrs reads them. parseAttrs never fails,
+ * so text that only looks like a block (CSS in prose, `{--x: 1}`) comes out reordered; a reader
+ * that may meet such text (the label-less inline form) asks this first and leaves it as text.
+ */
+export declare function isAttrList(inner: string): boolean;
 /**
  * Merge ParsedAttrs into a props dict suitable for TreeNode.props.
  * `id` and `classes` become `id` and `class`; other props flow through.

package/dist/parse-attrs.js

@@ -99,6 +99,23 @@ export function parseAttrs(inner) {
     }
     return result;
 }
+/** One item of an attribute list: `#id`, `.class`, `key`, `key=bare`, `key="…"`, `key='…'`. */
+const ATTR_ITEM = /\s*(?:[#.][\w-]+|[A-Za-z_][\w-]*(?:=(?:"(?:[^"\\]|\\.)*"|'[^']*'|[^\s"'=]+))?)(?=\s|$)/y;
+/**
+ * Whether `inner` is ONLY a list of attributes, as parseAttrs reads them. parseAttrs never fails,
+ * so text that only looks like a block (CSS in prose, `{--x: 1}`) comes out reordered; a reader
+ * that may meet such text (the label-less inline form) asks this first and leaves it as text.
+ */
+export function isAttrList(inner) {
+    let pos = 0;
+    ATTR_ITEM.lastIndex = 0;
+    while (ATTR_ITEM.lastIndex < inner.length) {
+        if (!ATTR_ITEM.test(inner))
+            return /^\s*$/.test(inner.slice(pos));
+        pos = ATTR_ITEM.lastIndex;
+    }
+    return true;
+}
 /**
  * Merge ParsedAttrs into a props dict suitable for TreeNode.props.
  * `id` and `classes` become `id` and `class`; other props flow through.

package/dist/parse.js

@@ -11,7 +11,9 @@ import mdAttrs from "markdown-it-attrs";
 import mdDeflist from "markdown-it-deflist";
 import mdFootnote from "markdown-it-footnote";
 import * as yaml from "js-yaml";
-import { inlineDirectivesPlugin } from "./plugin-inline-directives.js";
+import { createFenceTracker } from "./code-regions.js";
+import { expandedSize } from "./yaml.js";
+import { LABEL_PROP, inlineDirectivesPlugin } from "./plugin-inline-directives.js";
 import { containersPlugin, GENERIC_CONTAINER } from "./plugin-containers.js";
 import { inlineToDogsbayMd } from "./inline.js";
 import { markPlugin } from "./plugin-mark.js";
@@ -163,6 +165,38 @@ function foldRelated(nodes) {
  * names so existing valid markdown that uses `---` as a horizontal
  * rule inside (e.g.) a `:::callout` body isn't accidentally consumed.
  */
+/** An UNINDENTED container line ends the search for a YAML body's closing `---`: a block scalar's lines are indented and may hold `:::`. */
+const CONTAINER_LINE = /^:{3,}/;
+/** What a directive's props may expand to (a YAML alias bomb parses in a millisecond and is 9^9 elements when walked). */
+const MAX_PROPS_VALUES = 20_000;
+/**
+ * Whether `---` … `---` right after an opener is a props block for a directive outside
+ * YAML_BODY_COMPONENTS (2026-10-27, the Comark idea: props on ANY directive). The text must be
+ * YAML that is a mapping with prop-shaped keys — a body that opens with a horizontal rule and
+ * later has another is not that — and the closing `---` must come before any container line.
+ */
+function isYamlPropsBody(lines, from, to) {
+    for (let k = from; k < to; k++)
+        if (CONTAINER_LINE.test(lines[k]))
+            return false;
+    const text = lines.slice(from, to).join("\n");
+    if (text.trim() === "")
+        return false;
+    try {
+        const parsed = yaml.load(text);
+        if (!parsed || typeof parsed !== "object" || Array.isArray(parsed))
+            return false;
+        if (expandedSize(parsed, MAX_PROPS_VALUES) > MAX_PROPS_VALUES)
+            return false;
+        const keys = Object.keys(parsed);
+        // prop-shaped keys, or keys the author quoted (`"a b":`), which the serializer writes for the rest
+        const quoted = new Set([...text.matchAll(/^(?:"((?:[^"\\]|\\.)*)"|'([^']*)'):/gm)].map((m) => (m[1] !== undefined ? JSON.parse(`"${m[1]}"`) : m[2])));
+        return keys.length > 0 && keys.every((k) => /^[A-Za-z_][\w.-]*$/.test(k) || quoted.has(k));
+    }
+    catch {
+        return false;
+    }
+}
 const YAML_BODY_COMPONENTS = new Set([
     "card",
     "api-endpoint",
@@ -209,22 +243,29 @@ function preprocessYamlBodies(source) {
     const lines = source.split("\n");
     const out = [];
     const lineMap = [];
+    // Which lines are fenced code: a `:::card` shown inside a ```markdown example is text, and the
+    // lift must not read its `---` block (it rewrote a docs page's example, 2026-10-27).
+    const fence = createFenceTracker();
+    const code = lines.map((l) => fence.step(l) !== "prose");
     let i = 0;
     while (i < lines.length) {
         const line = lines[i];
         // Match an opener: 3+ colons, name, optional {existing attrs}
-        const opener = line.match(/^(:{3,})([a-zA-Z][\w-]*)(\{[^}]*\})?\s*$/);
+        const opener = code[i] ? null : line.match(/^(:{3,})([a-zA-Z][\w-]*)(\{.*\})?\s*$/);
         if (opener &&
-            YAML_BODY_COMPONENTS.has(opener[2]) &&
             i + 1 < lines.length &&
             lines[i + 1].trim() === "---") {
             // Find closing `---` line. YAML doesn't allow a bare `---` as
             // value content (it's a document separator), so the next match
             // is unambiguously the closing fence.
+            // Only an UNINDENTED `---` closes: a block scalar's line may be `  ---`
             let j = i + 2;
-            while (j < lines.length && lines[j].trim() !== "---")
+            while (j < lines.length && !(/^---[ \t]*\r?$/.test(lines[j]) && !code[j]))
                 j++;
-            if (j < lines.length) {
+            // The YAML directives take the block as they always did; any other directive takes it
+            // only when it reads as props (isYamlPropsBody), so an `---` rule in a callout stays a rule.
+            const fenced = lines.slice(i + 2, j).some((_, k) => code[i + 2 + k]);
+            if (j < lines.length && !fenced && (YAML_BODY_COMPONENTS.has(opener[2]) || isYamlPropsBody(lines, i + 2, j))) {
                 const yamlText = lines.slice(i + 2, j).join("\n");
                 const encoded = encodeURIComponent(yamlText);
                 const fence = opener[1];
@@ -1104,9 +1145,11 @@ function consumeContainer(ctx) {
         // block serializes back as written.
         // (A bracketed `[Title]` was already lifted into props.title above.)
         const title = infoRest.startsWith("[") ? "" : infoRest.replace(/\{[\s\S]*\}\s*$/, "").trim();
+        const unknownProps = attrs ? attrsToProps(attrs) : {};
+        mergeYamlProps(unknownProps);
         return {
             type: "container",
-            props: attrs ? attrsToProps(attrs) : {},
+            props: unknownProps,
             children,
             meta: { container: true, name, ...(title ? { title } : {}), ...(closer ? { closer } : {}) },
         };
@@ -1118,33 +1161,37 @@ function consumeContainer(ctx) {
  * Convert a container + children into the appropriate TreeNode(s).
  * Handles callout type aliases, tabs definition-list recovery, cards list form, etc.
  */
-function mapContainerToTreeNode(name, attrs, children) {
-    const props = attrs ? attrsToProps(attrs) : {};
-    // YAML body lift-up: `preprocessYamlBodies` (run during
-    // dogsbayMdToTree) stashed the directive's YAML body as a
-    // URL-encoded `__yaml__` prop. Decode + parse + merge into props.
-    // Anything malformed is silently dropped — better to lose the YAML
-    // than to fail the whole parse on a typo.
-    if (typeof props.__yaml__ === "string") {
-        const encoded = props.__yaml__;
-        delete props.__yaml__;
-        try {
-            const yamlText = decodeURIComponent(encoded);
-            const parsed = yaml.load(yamlText);
-            if (parsed && typeof parsed === "object" && !Array.isArray(parsed)) {
-                // YAML wins on conflict — the serializer emits ALL props in
-                // the YAML body, so any inline attrs in addition came from a
-                // hand-edit and are likely meant as overrides; but conflicts
-                // here are fringe. Going with YAML for round-trip stability.
-                for (const [k, v] of Object.entries(parsed)) {
-                    props[k] = v;
-                }
+/**
+ * YAML body lift-up: `preprocessYamlBodies` (run during dogsbayMdToTree) stashed a directive's
+ * YAML body as a URL-encoded `__yaml__` prop. Decode + parse + merge into props. Anything
+ * malformed is silently dropped — better to lose the YAML than to fail the whole parse on a
+ * typo. Every directive, known or not, reads it (2026-10-27).
+ */
+function mergeYamlProps(props) {
+    if (typeof props.__yaml__ !== "string")
+        return;
+    const encoded = props.__yaml__;
+    delete props.__yaml__;
+    try {
+        const yamlText = decodeURIComponent(encoded);
+        const parsed = yaml.load(yamlText);
+        if (parsed && typeof parsed === "object" && !Array.isArray(parsed) && expandedSize(parsed, MAX_PROPS_VALUES) <= MAX_PROPS_VALUES) {
+            // YAML wins on conflict — the serializer emits ALL props in
+            // the YAML body, so any inline attrs in addition came from a
+            // hand-edit and are likely meant as overrides; but conflicts
+            // here are fringe. Going with YAML for round-trip stability.
+            for (const [k, v] of Object.entries(parsed)) {
+                props[k] = v;
             }
         }
-        catch {
-            // Malformed encoding or YAML — leave props as-is sans __yaml__.
-        }
     }
+    catch {
+        // Malformed encoding or YAML — leave props as-is sans __yaml__.
+    }
+}
+function mapContainerToTreeNode(name, attrs, children) {
+    const props = attrs ? attrsToProps(attrs) : {};
+    mergeYamlProps(props);
     // Callout type aliases — :::note, :::tip, etc. map to callout with type
     const CALLOUT_TYPES = new Set([
         "note",
@@ -1748,7 +1795,14 @@ function tokensToInline(tokens, inheritedFmt = []) {
                 }
                 const labelInline = tokensToInline(labelTokens);
                 const labelText = inlineText(labelInline);
-                const node = inlineDirectiveToNode(name, labelText, labelInline, attrs);
+                const meta = tok.meta;
+                const labelless = meta?.labelless === true;
+                let node = meta?.literal && meta.source ? { type: "text", text: meta.source } : inlineDirectiveToNode(name, labelText, labelInline, attrs, labelless);
+                // A label-less directive that makes nothing (unknown, or a known one without its naming
+                // prop) stays exactly as written, as TEXT: its attrs may carry a tag, html-inline is written
+                // raw by every consumer, and re-rendering the attrs reordered them
+                if (labelless && meta?.source && ((node?.type === "html-inline" && node.html.startsWith(`:${name}[]`)) || (node?.type === "text" && node.text.startsWith(`:${name}{`))))
+                    node = { type: "text", text: meta.source };
                 if (node)
                     result.push(node);
                 break;
@@ -1857,7 +1911,24 @@ function inlineAttrsOf(attrs, props) {
         out[k] = v === true ? "" : String(v);
     return Object.keys(out).length ? out : undefined;
 }
-function inlineDirectiveToNode(name, labelText, labelInline, attrs) {
+function inlineDirectiveToNode(name, labelText, labelInline, attrs, labelless = false) {
+    // Label-less form: the naming prop is the label, and leaves the attrs. Without that prop a
+    // known directive has nothing to show, so it stays as written (and diagnostics say so).
+    const labelKey = LABEL_PROP[name];
+    if (labelless && labelKey) {
+        if (attrs && typeof attrs.props[labelKey] === "string") {
+            labelText = attrs.props[labelKey];
+            labelInline = [{ type: "text", text: labelText }];
+            const { [labelKey]: _dropped, ...props } = attrs.props;
+            attrs = { ...attrs, props };
+        }
+        else {
+            // Text, not html-inline: the attrs may hold `<img onerror=…>`, and a consumer writes
+            // html-inline raw. The serializer escapes the brace, so it stays text on the way back.
+            const block = attrs ? renderAttrs({ id: attrs.id, classes: attrs.classes, props: attrs.props }).trim() : "";
+            return { type: "text", text: `:${name}${block || "{}"}` };
+        }
+    }
     switch (name) {
         case "kbd": {
             const keys = labelText.split(/\s*\+\s*/).filter(Boolean);

package/dist/plugin-inline-directives.d.ts

@@ -4,6 +4,12 @@
  * Recognizes:
  *   :name[text]{attrs}   — text directive (label can contain inline markdown)
  *   :name[text]          — text directive, no attrs
+ *   :name{attrs}         — text directive with no label (Comark's "properties only" form,
+ *                          2026-10-27): a known directive takes its label from the prop that
+ *                          names it (`:kbd{value="Ctrl"}`, `:icon{name="lucide:star"}`); an
+ *                          unknown one is kept as written. Before, the rule declined it and
+ *                          markdown-it-attrs then read a trailing `{…}` as the PARAGRAPH's
+ *                          attributes, so the props vanished.
  *   ::name{attrs}        — leaf directive (self-closing)
  *   ::name               — leaf directive, no attrs
  *
@@ -16,4 +22,6 @@
 import type MarkdownIt from "markdown-it";
 /** A character a directive cannot follow directly (see inlineDirectiveRule). */
 export declare const PRECEDES_TEXT: RegExp;
+/** The prop that labels a known inline directive written without `[text]` (`:kbd{value="Ctrl"}`). */
+export declare const LABEL_PROP: Readonly<Record<string, string>>;
 export declare function inlineDirectivesPlugin(md: MarkdownIt): void;

package/dist/plugin-inline-directives.js

@@ -1,6 +1,8 @@
-import { attrBlockEnd, parseAttrs } from "./parse-attrs.js";
+import { attrBlockEnd, isAttrList, 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;
+/** The prop that labels a known inline directive written without `[text]` (`:kbd{value="Ctrl"}`). */
+export const LABEL_PROP = { kbd: "value", icon: "name", badge: "label", button: "label", mark: "text", highlight: "text", math: "latex" };
 export function inlineDirectivesPlugin(md) {
     md.inline.ruler.before("emphasis", "dogsbay_inline_directive", inlineDirectiveRule);
 }
@@ -45,13 +47,23 @@ function inlineDirectiveRule(state, silent) {
     let label = "";
     let labelStart = -1;
     let labelEnd = -1;
-    if (!isLeaf) {
+    /** `:name{attrs}`: no `[label]` at all. */
+    let labelless = false;
+    if (!isLeaf && src.charCodeAt(pos) === 0x7b /* { */) {
+        labelless = true;
+    }
+    else if (!isLeaf) {
         // Text directive requires a [label]
         if (src.charCodeAt(pos) !== 0x5b /* [ */)
             return false;
         pos++;
         labelStart = pos;
-        // Find matching closing bracket (ignore escapes)
+        // Find matching closing bracket (ignore escapes). A scan that reached the end without one
+        // is remembered for the parse: every later candidate on the input would scan the same tail
+        // (a run of `:a[` was quadratic, 80 KB in 8 s)
+        const noLabel = state.env.__dbNoLabelClose;
+        if (noLabel !== undefined && labelStart >= noLabel)
+            return false;
         let depth = 1;
         while (pos < src.length) {
             const c = src.charCodeAt(pos);
@@ -68,27 +80,46 @@ function inlineDirectiveRule(state, silent) {
             }
             pos++;
         }
-        if (pos >= src.length)
+        if (pos >= src.length) {
+            state.env.__dbNoLabelClose = labelStart;
             return false;
+        }
         labelEnd = pos;
         label = src.slice(labelStart, labelEnd);
         pos++; // consume ]
     }
-    // Optional { attrs }
+    // Optional { attrs } — required in the label-less form
     let attrs = "";
     if (src.charCodeAt(pos) === 0x7b /* { */) {
         const attrStart = pos + 1;
-        const ap = attrBlockEnd(src, attrStart, src.length);
+        // An attribute block ends on its line: scanning to the end of the input made a run of `:a{ `
+        // quadratic (80 KB took 4 s)
+        const lineEnd = src.indexOf("\n", attrStart);
+        const max = lineEnd < 0 ? src.length : lineEnd;
+        // the same memo for a `{` with no `}` on its line
+        const env = state.env;
+        const known = env.__dbNoAttrClose && env.__dbNoAttrClose.max === max && attrStart >= env.__dbNoAttrClose.from;
+        const ap = known ? -1 : attrBlockEnd(src, attrStart, max);
         if (ap >= 0) {
             attrs = src.slice(attrStart, ap);
             pos = ap + 1;
         }
+        else {
+            if (!known)
+                env.__dbNoAttrClose = { max, from: attrStart };
+            if (labelless)
+                return false;
+        }
     }
     if (silent) {
         state.pos = pos;
         return true;
     }
-    const parsedAttrs = parseAttrs(attrs);
+    // `:root{--x: 1}` in prose is CSS, not attributes: read leniently it came out reordered
+    // (`:root{1 --x:}`). It is still taken here, as literal text: left to the paragraph, a trailing
+    // `{…}` would be read as the paragraph's attributes and vanish.
+    const literal = labelless && !isAttrList(attrs);
+    const parsedAttrs = literal ? { classes: [], props: {} } : parseAttrs(attrs);
     const attrsStr = JSON.stringify(parsedAttrs);
     if (isLeaf) {
         const t = state.push("dogsbay_leaf_directive", "", 0);
@@ -99,14 +130,19 @@ function inlineDirectiveRule(state, silent) {
         const openT = state.push("dogsbay_inline_directive_open", "", 1);
         openT.tag = name;
         openT.info = attrsStr;
-        // Parse label as inline content (recursive)
-        const oldPos = state.pos;
-        const oldPosMax = state.posMax;
-        state.pos = labelStart;
-        state.posMax = labelEnd;
-        state.md.inline.tokenize(state);
-        state.pos = oldPos;
-        state.posMax = oldPosMax;
+        // the source as written: an unknown label-less directive stays these bytes, not a re-rendering
+        if (labelless)
+            openT.meta = { labelless: true, literal, source: src.slice(start, pos) };
+        if (!labelless) {
+            // Parse label as inline content (recursive)
+            const oldPos = state.pos;
+            const oldPosMax = state.posMax;
+            state.pos = labelStart;
+            state.posMax = labelEnd;
+            state.md.inline.tokenize(state);
+            state.pos = oldPos;
+            state.posMax = oldPosMax;
+        }
         const closeT = state.push("dogsbay_inline_directive_close", "", -1);
         closeT.tag = name;
     }

package/dist/project.d.ts

@@ -5,6 +5,7 @@
  * browser imports (`@dogsbay/format-vitepress/migrate`) return them, so a migration in the
  * browser is the one `convert` does.
  */
+import type { SerializeOptions } from "./types.js";
 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>;
@@ -29,7 +30,7 @@ export declare function carriedFrontmatter(fm: Record<string, unknown> | undefin
 /** 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>;
+export declare function dogsbayMdPageFiles(pages: ExportPage[], nav: NavItem[], serialize?: SerializeOptions): Map<string, string>;
 /** An importer's asset directory, as `ImportResult.assetMounts` declares it, relative to the corpus. */
 export interface AssetMount {
     dir: string;

package/dist/project.js

@@ -62,7 +62,7 @@ export function carriedFrontmatter(fm) {
 export function dogsbayMdPagePath(page) {
     return `${page.slug || "index"}.md`;
 }
-export function dogsbayMdPageFiles(pages, nav) {
+export function dogsbayMdPageFiles(pages, nav, serialize) {
     const files = new Map();
     for (const page of pages) {
         // A template partial keeps its `params:` and the template flag, so the
@@ -73,7 +73,7 @@ export function dogsbayMdPageFiles(pages, nav) {
         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);
+        const md = treeToDogsbayMd(page.tree, { ...serialize, ...(frontmatter ? { frontmatter } : {}) });
         files.set(dogsbayMdPagePath(page), md.endsWith("\n") ? md : md + "\n");
     }
     // Nav as nav.json at the content root (the dogsbay-md importer + runtime

package/dist/serialize.js

@@ -6,7 +6,7 @@ import { assertDirectiveField } from "./directive-guard.js";
 import { renderAttrs, splitProps } from "./attributes.js";
 import { pickCodeFence, pickDirectiveFence, normalizeTrailingWhitespace, } from "./escape.js";
 import { resolveOptions } from "./types.js";
-import { renderBlockDirective } from "./directives.js";
+import { guardRule, renderBlockDirective } from "./directives.js";
 import { renderFrontmatter } from "./yaml.js";
 // Captions are inline Markdown; parse.ts imports this module too, but parseInline
 // is only called at render time, after both modules have loaded
@@ -618,7 +618,8 @@ function renderCallout(node, ctx) {
     const labelled = typeof node.meta?.closer === "string";
     if (ctx.githubCallouts && hasOnlyTypeProp && !labelled && GITHUB_CALLOUT_TYPES.has(type)) {
         const tag = `[!${type.toUpperCase()}]`;
-        return [tag, body]
+        // a body opening with `---` under `[!NOTE]` made a setext heading of the tag: the callout was lost
+        return [tag, guardRule(body)]
             .join("\n")
             .split("\n")
             .map((l) => (l ? `> ${l}` : ">"))
@@ -1341,8 +1342,13 @@ function renderUnknown(node, ctx) {
     if (node.type === "container" && node.meta?.container === true && typeof name === "string" && /^[A-Za-z][\w-]*$/.test(name)) {
         const body = (node.children ?? []).map((c) => renderNode(c, ctx)).filter(Boolean).join("\n\n");
         const title = typeof node.meta?.title === "string" ? ` ${node.meta.title}` : "";
+        // A nested prop (a `---` block the parser read, 2026-10-27) has no inline form: the YAML form,
+        // which the parser reads on every directive, keeps it; the inline form dropped it silently.
+        if (!title && Object.values(node.props ?? {}).some((v) => (v !== null && typeof v === "object") || (typeof v === "string" && v.includes("\n")))) {
+            return renderBlockDirective({ name, props: node.props, body, yamlEligible: true }, ctx);
+        }
         const attrs = renderAttrs(splitProps(node.props, [])).trim();
-        return `:::${name}${title}${attrs ? (title ? " " : "") + attrs : ""}\n${body}\n:::`;
+        return `:::${name}${title}${attrs ? (title ? " " : "") + attrs : ""}\n${guardRule(body)}\n:::`;
     }
     switch (ctx.unknownNodes) {
         case "skip":

package/dist/yaml.d.ts

@@ -14,5 +14,14 @@ export type YamlValue = string | number | boolean | null | undefined | Date | Ya
  * Render a flat or shallow-nested object as YAML.
  * Keys emitted in insertion order.
  */
-export declare function renderYaml(value: Record<string, YamlValue>, indent?: number): string;
+/** `quoteStrings`: every string double-quoted (JSON), the form that always reads back. */
+export declare function renderYaml(value: Record<string, YamlValue>, indent?: number, quoteStrings?: boolean): string;
+/**
+ * `renderYaml`, and when js-yaml would not read the result back as the value (a shape the
+ * writer has no rule for), js-yaml's own dump instead: a directive's YAML body must always
+ * read back, or its props are a paragraph on the next parse.
+ */
+export declare function renderYamlReadable(value: Record<string, YamlValue>): string;
+/** What `v` expands to when every shared reference is written out, up to `cap` + 1. */
+export declare function expandedSize(v: unknown, cap: number, memo?: Map<object, number>, depth?: number): number;
 export declare function renderFrontmatter(value: Record<string, YamlValue>): string;

package/dist/yaml.js

@@ -12,12 +12,15 @@ import * as jsyaml from "js-yaml";
  * Render a flat or shallow-nested object as YAML.
  * Keys emitted in insertion order.
  */
-export function renderYaml(value, indent = 0) {
+/** `quoteStrings`: every string double-quoted (JSON), the form that always reads back. */
+export function renderYaml(value, indent = 0, quoteStrings = false) {
     const pad = " ".repeat(indent);
     const lines = [];
-    for (const [key, val] of Object.entries(value)) {
+    for (const [rawKey, val] of Object.entries(value)) {
         if (val === undefined)
             continue;
+        // A key that is not prop-shaped is quoted, which the parser's props-block rule accepts
+        const key = /^[A-Za-z_][\w.-]*$/.test(rawKey) ? rawKey : JSON.stringify(rawKey);
         if (val === null) {
             lines.push(`${pad}${key}: null`);
             continue;
@@ -31,7 +34,7 @@ export function renderYaml(value, indent = 0) {
             continue;
         }
         if (typeof val === "string") {
-            lines.push(`${pad}${key}: ${encodeScalar(val)}`);
+            lines.push(`${pad}${key}: ${quoteStrings ? JSON.stringify(val) : encodeScalar(val, indent)}`);
             continue;
         }
         if (val instanceof Date) {
@@ -46,7 +49,7 @@ export function renderYaml(value, indent = 0) {
             lines.push(`${pad}${key}:`);
             for (const item of val) {
                 if (item === null || typeof item !== "object" || Array.isArray(item) || item instanceof Date) {
-                    lines.push(`${pad}  - ${encodeItem(item)}`);
+                    lines.push(`${pad}  - ${quoteStrings && typeof item === "string" ? JSON.stringify(item) : encodeItem(item, indent + 2)}`);
                 }
                 else {
                     // Object in array — inline form
@@ -57,7 +60,7 @@ export function renderYaml(value, indent = 0) {
         }
         if (typeof val === "object") {
             lines.push(`${pad}${key}:`);
-            lines.push(renderYaml(val, indent + 2));
+            lines.push(renderYaml(val, indent + 2, quoteStrings));
             continue;
         }
     }
@@ -66,11 +69,18 @@ export function renderYaml(value, indent = 0) {
 /**
  * Encode a scalar value for YAML, picking the right quoting style.
  */
-function encodeScalar(value) {
-    // Multi-line string: use literal block scalar
+function encodeScalar(value, indent = 0) {
+    // Multi-line string: a literal block scalar, its content two past the KEY's indent (level with
+    // the key, a nested one did not read back); `|2` when the first line is blank or indented,
+    // since js-yaml takes the indentation from the first non-empty line otherwise; `|-` when the
+    // value has no trailing newline, so none is added on the way back.
     if (value.includes("\n")) {
-        const lines = value.split("\n");
-        return `|\n${lines.map((l) => "  " + l).join("\n")}`;
+        const chomp = value.endsWith("\n") ? "" : "-";
+        const body = value.endsWith("\n") ? value.slice(0, -1) : value;
+        const lines = body.split("\n");
+        const pad = " ".repeat(indent + 2);
+        const indicator = lines[0] === "" || /^\s/.test(lines[0]) ? "2" : "";
+        return `|${indicator}${chomp}\n${lines.map((l) => (l === "" ? "" : pad + l)).join("\n")}`;
     }
     // Strings that look like numbers, booleans, or special YAML values need quoting
     if (needsQuoting(value)) {
@@ -90,7 +100,7 @@ function encodeDate(d) {
     const iso = d.toISOString();
     return iso.endsWith("T00:00:00.000Z") ? iso.slice(0, 10) : iso;
 }
-function encodeItem(value) {
+function encodeItem(value, indent = 0) {
     if (value === null || value === undefined)
         return "null";
     if (value instanceof Date)
@@ -98,15 +108,45 @@ function encodeItem(value) {
     if (typeof value === "boolean" || typeof value === "number")
         return String(value);
     if (typeof value === "string")
-        return encodeScalar(value);
+        return encodeScalar(value, indent);
     return JSON.stringify(value);
 }
 function encodeInlineObject(obj) {
     const pairs = Object.entries(obj)
         .filter(([, v]) => v !== undefined)
-        .map(([k, v]) => `${k}: ${encodeItem(v)}`);
+        .map(([k, v]) => `${/^[\w.-]+$/.test(k) ? k : JSON.stringify(k)}: ${encodeFlowItem(v)}`);
     return `{ ${pairs.join(", ")} }`;
 }
+/** An item inside a flow mapping, where a comma, bracket or brace in a bare string would end the entry (Nuxt UI's FAQ items did). */
+function encodeFlowItem(value) {
+    if (typeof value === "string") {
+        if (value.includes("\n") || /[,{}\[\]]/.test(value) || needsQuoting(value))
+            return JSON.stringify(value);
+        return value;
+    }
+    if (value !== null && typeof value === "object" && !(value instanceof Date))
+        return JSON.stringify(value);
+    return encodeItem(value);
+}
+/**
+ * `renderYaml`, and when js-yaml would not read the result back as the value (a shape the
+ * writer has no rule for), js-yaml's own dump instead: a directive's YAML body must always
+ * read back, or its props are a paragraph on the next parse.
+ */
+export function renderYamlReadable(value) {
+    const text = renderYaml(value);
+    if (readsBackAs(text, value))
+        return text;
+    // js-yaml's dump, its one trailing newline removed (trimEnd took the newlines a `|+` keeps);
+    // and when even that does not read back, every string double-quoted (always reads back).
+    const dumped = stripOneNewline(jsyaml.dump(forDump(value), { lineWidth: -1, noRefs: true, skipInvalid: true }));
+    if (readsBackAs(dumped, value))
+        return dumped;
+    return renderYaml(value, 0, true);
+}
+function stripOneNewline(s) {
+    return s.endsWith("\n") ? s.slice(0, -1) : s;
+}
 function needsQuoting(value) {
     if (value === "")
         return true;
@@ -134,7 +174,7 @@ function needsQuoting(value) {
 /** 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) {
+export 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);
@@ -157,7 +197,9 @@ export function renderFrontmatter(value) {
     // 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---`;
+        return `---
+${stripOneNewline(jsyaml.dump(value, { lineWidth: -1, noRefs: false, skipInvalid: true }))}
+---`;
     }
     const yaml = renderYaml(value);
     if (readsBackAs(yaml, value))

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@dogsbay/format-dogsbay-md",
-  "version": "0.2.0-beta.136",
+  "version": "0.2.0-beta.138",
   "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/minja": "0.2.0-beta.136",
-    "@dogsbay/serialize-core": "0.2.0-beta.136",
-    "@dogsbay/types": "0.2.0-beta.136",
-    "@dogsbay/corpus": "0.2.0-beta.136"
+    "@dogsbay/corpus": "0.2.0-beta.138",
+    "@dogsbay/minja": "0.2.0-beta.138",
+    "@dogsbay/serialize-core": "0.2.0-beta.138",
+    "@dogsbay/types": "0.2.0-beta.138"
   },
   "license": "MIT",
   "repository": {