@dogsbay/format-dogsbay-md 0.2.0-beta.142 → 0.2.0-beta.144

package/dist/browser.d.ts

@@ -16,6 +16,7 @@ export { KNOWN_INLINE_DIRECTIVES, type ParseDiagnostic } from "./diagnostics.js"
 export { KNOWN_BLOCK_DIRECTIVES, LEAF_ONLY_DIRECTIVES, BLOCK_LEAF_DIRECTIVES } from "./plugin-containers.js";
 export { treeToDogsbayMd, nodeToDogsbayMd } from "./serialize.js";
 export { DIRECTIVE_PROPS, PASSTHROUGH_PROP, unknownProps } from "./directive-props.js";
+export { DIRECTIVE_DESCRIPTIONS, INLINE_DIRECTIVE_DESCRIPTIONS } from "./directive-descriptions.js";
 export type { SerializeOptions } from "./types.js";
 export { inlineToDogsbayMd } from "./inline.js";
 export { transformCodeRegions, transformProseLines, transformProseSegments, fenceOpenBefore, createFenceTracker, } from "./code-regions.js";

package/dist/browser.js

@@ -18,6 +18,7 @@ export { KNOWN_BLOCK_DIRECTIVES, LEAF_ONLY_DIRECTIVES, BLOCK_LEAF_DIRECTIVES } f
 export { treeToDogsbayMd, nodeToDogsbayMd } from "./serialize.js";
 // The props each known directive draws (an editor completes prop names from it)
 export { DIRECTIVE_PROPS, PASSTHROUGH_PROP, unknownProps } from "./directive-props.js";
+export { DIRECTIVE_DESCRIPTIONS, INLINE_DIRECTIVE_DESCRIPTIONS } from "./directive-descriptions.js";
 export { inlineToDogsbayMd } from "./inline.js";
 export { transformCodeRegions, transformProseLines, transformProseSegments, fenceOpenBefore, createFenceTracker, } from "./code-regions.js";
 export { maskMinjaInCode, unmaskMinjaInCode, maskAllMinjaOpeners, isMinjaProcessedFence, stripInlineMinjaMarkers, stripFenceMinjaMarkers } from "./minja-mask.js";

package/dist/diagnostics.d.ts

@@ -10,6 +10,14 @@ export interface ParseDiagnostic {
      * reading it out of the message.
      */
     name?: string;
+    /**
+     * 1-based column where the problem starts on `line`, and `endColumn` just past its end (also
+     * 1-based, exclusive), when the parser knows which part of the line it is about: the `:::name`
+     * opener, the prop key, the closer's comment, the `{…}` block. Found in the SOURCE line, so a
+     * pre-pass that rewrites the text cannot shift it. Left out, the whole line is meant.
+     */
+    column?: number;
+    endColumn?: number;
 }
 /**
  * Whether a source line closes a container opened with `colons` colons. The
@@ -47,5 +55,5 @@ type Token = {
  * missing brace or an unterminated quote loses attributes silently.
  */
 export declare function attributeProblem(block: string): string | undefined;
-export declare function collectDiagnostics(tokens: Token[], lines: string[], lineOf: (line0: number) => number | undefined): ParseDiagnostic[];
+export declare function collectDiagnostics(tokens: Token[], lines: string[], lineOf: (line0: number) => number | undefined, sourceLine?: (line: number) => string | undefined): ParseDiagnostic[];
 export {};

package/dist/diagnostics.js

@@ -12,6 +12,36 @@ import { BLOCK_LEAF_DIRECTIVES, GENERIC_CONTAINER, LEAF_ONLY_DIRECTIVES } from "
 import { LABEL_PROP } from "./plugin-inline-directives.js";
 import { DIRECTIVE_PROPS, unknownProps } from "./directive-props.js";
 import * as yaml from "js-yaml";
+/** The first match of `re` at or after `from`; a group named `at` narrows it (a key before its `=`). */
+function find(re, mask) {
+    const span = (text, from) => {
+        const g = new RegExp(re.source, re.flags.includes("g") ? re.flags : `${re.flags}g`);
+        g.lastIndex = from;
+        const m = g.exec(mask ? mask(text) : text);
+        if (!m || m[0].length === 0)
+            return undefined;
+        const at = m.groups?.at;
+        const start = at !== undefined ? m.index + m[0].indexOf(at) : m.index;
+        return [start, start + (at ?? m[0]).length];
+    };
+    span.pattern = re.source;
+    return span;
+}
+/** Inline code spans blanked, offsets kept: a directive shown in code is not the one meant. */
+const maskCode = (text) => text.replace(/(`+)[\s\S]*?\1/g, (c) => " ".repeat(c.length));
+/** Quoted attribute values blanked, offsets kept: a key's name inside another's value is not the key. */
+const maskQuotes = (text) => text.replace(/"[^"]*"|'[^']*'/g, (c) => " ".repeat(c.length));
+/**
+ * The attribute block a line ends with (`{…}`, maybe unclosed, then spaces), found from the last
+ * `{` so the test is linear: anchored at `$`, the regex backtracked quadratically on a long line.
+ */
+function trailingBraces(text, inner = /^\{[^{}]*\}?$/) {
+    const t = text.trimEnd();
+    const i = t.lastIndexOf("{");
+    return i >= 0 && inner.test(t.slice(i)) ? [i, t.length] : undefined;
+}
+const HEADING_ATTRS = /^\{\s*(?:[#.][^{}]*|[\w-]+\s*=[^{}]*)\}?$/;
+const escapeRe = (s) => s.replace(/[.*+?^${}()|[\]\\]/g, "\\$&");
 /**
  * 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
@@ -155,12 +185,32 @@ function propKeysOfAttrs(props) {
     }
     return keys;
 }
-export function collectDiagnostics(tokens, lines, lineOf) {
+export function collectDiagnostics(tokens, lines, lineOf, sourceLine) {
     const out = [];
-    const add = (line0, code, message, name) => {
+    // Where the last span of each (line, code) ended: two of one kind on a line take successive matches
+    const cursor = new Map();
+    const add = (line0, code, message, name, span) => {
         const line = line0 === undefined ? undefined : lineOf(line0);
-        if (line !== undefined)
-            out.push({ line, code, message, ...(name === undefined ? {} : { name }) });
+        if (line === undefined)
+            return;
+        const text = span && sourceLine?.(line);
+        let cols;
+        if (text !== undefined && span) {
+            const locate = span instanceof RegExp ? find(span) : span;
+            // Per pattern too: bold `{…}` and `:kbd[…]{…}` on one line are found independently
+            const key = `${line}\0${code}\0${locate.pattern ?? ""}`;
+            cols = locate(text, cursor.get(key) ?? 0);
+            if (cols)
+                cursor.set(key, cols[1]);
+        }
+        out.push({ line, code, message, ...(name === undefined ? {} : { name }), ...(cols ? { column: cols[0] + 1, endColumn: cols[1] + 1 } : {}) });
+    };
+    const opener = (name) => new RegExp(`:{3,}[ \\t]*${escapeRe(name)}(?![\\w-])`);
+    const BRACES = (text) => trailingBraces(text);
+    /** Lines into an inline token where each child starts: soft and hard breaks move to the next. */
+    const childLines = (children) => {
+        let n = 0;
+        return children.map((c) => (c.type === "softbreak" || c.type === "hardbreak" ? n++ : n));
     };
     const code = codeLineSet(tokens);
     let row;
@@ -186,22 +236,22 @@ export function collectDiagnostics(tokens, lines, lineOf) {
                 // (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}`);
+                    add(tok.map[0], "leaf-as-block", `a video has no body: write ::youtube{…} on one line, with no closer — as :::youtube it ${leafAsBlock}`, undefined, opener(name));
                 }
                 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 ${clip(lines[legacy])} on line ${lineOf(legacy) ?? "?"} closes only the innermost open block; each block needs its own closer (one \`:::\` used to close several)`);
+                    add(tok.map[0], "unclosed-container", `:::${name} is never closed — the ${clip(lines[legacy])} on line ${lineOf(legacy) ?? "?"} closes only the innermost open block; each block needs its own closer (one \`:::\` used to close several)`, undefined, opener(name));
                 }
                 else if (!closed && skipped !== undefined) {
-                    add(tok.map[0], "unclosed-container", `:::${name} is never closed — the ${clip(lines[skipped])} on line ${lineOf(skipped) ?? "?"} is inside a code block, so it does not close it (add a closer after the code)`);
+                    add(tok.map[0], "unclosed-container", `:::${name} is never closed — the ${clip(lines[skipped])} on line ${lineOf(skipped) ?? "?"} is inside a code block, so it does not close it (add a closer after the code)`, undefined, opener(name));
                 }
                 else if (!closed) {
                     add(tok.map[0], "unclosed-container", generic
                         ? `:::${name} is never closed — it is shown as text (close it with a line of ${":".repeat(colons)})`
-                        : `:::${name} is never closed — it takes in everything after it, to the end of the page or of the block it sits in (close it with a line of ${":".repeat(colons)})`);
+                        : `:::${name} is never closed — it takes in everything after it, to the end of the page or of the block it sits in (close it with a line of ${":".repeat(colons)})`, undefined, opener(name));
                 }
                 else if (generic) {
-                    add(tok.map[0], "unknown-container", `:::${name} is not a known directive — it is shown as a plain box`, name);
+                    add(tok.map[0], "unknown-container", `:::${name} is not a known directive — it is shown as a plain box`, name, opener(name));
                 }
                 else {
                     // A prop no renderer of this directive reads is carried, never drawn: say so (a typo
@@ -209,26 +259,28 @@ export function collectDiagnostics(tokens, lines, lineOf) {
                     // 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 ?? []);
+                    const inline = new Set(pairs.map(([k]) => k));
                     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);
+                        // A key from a `---` props block is on another line: no column
+                        add(tok.map[0], "unknown-prop", `${key} is not a prop of :::${name} — it is kept but not drawn`, name, inline.has(key) ? find(new RegExp(`(?<![\\w-])(?<at>${escapeRe(key)})\\s*=`), maskQuotes) : undefined);
                     }
                 }
                 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`);
+                    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`, undefined, opener(name));
                 }
                 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
                     const label = closerLabel((lines[tok.map[1]] ?? "").replace(/^[\s>]*:+/, ""));
                     if (label && label !== name) {
-                        add(tok.map[1], "closer-mismatch", `this closer is labelled ${label}, but it closes :::${name} (opened on line ${lineOf(tok.map[0]) ?? "?"}) — check which block you meant to end here`);
+                        add(tok.map[1], "closer-mismatch", `this closer is labelled ${label}, but it closes :::${name} (opened on line ${lineOf(tok.map[0]) ?? "?"}) — check which block you meant to end here`, undefined, /<!--[\s\S]*?-->/);
                     }
                 }
                 const rest = info.slice(name.length).trim();
                 if (rest.startsWith("{")) {
                     const problem = attributeProblem(rest);
                     if (problem)
-                        add(tok.map[0], "bad-attributes", `the attributes of :::${name} ${problem} — they are ignored`);
+                        add(tok.map[0], "bad-attributes", `the attributes of :::${name} ${problem} — they are ignored`, undefined, /\{.*$/);
                 }
                 // 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 });
@@ -237,7 +289,7 @@ export function collectDiagnostics(tokens, lines, lineOf) {
             if (tok.type === "inline" && tok.map) {
                 (tok.content ?? "").split("\n").forEach((l, k) => {
                     if (/^\s*:{3,}[ \t]*(?:<!--(?:(?!-->)[\s\S])*-->[ \t]*)?$/.test(l)) {
-                        add(tok.map[0] + k, "stray-closer", `stray \`${clip(l)}\` — it closes nothing and is shown as text: every block before it is already closed (each block takes one closer)`);
+                        add(tok.map[0] + k, "stray-closer", `stray \`${clip(l)}\` — it closes nothing and is shown as text: every block before it is already closed (each block takes one closer)`, undefined, /:{3,}/);
                     }
                 });
             }
@@ -264,7 +316,7 @@ export function collectDiagnostics(tokens, lines, lineOf) {
                             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}="…"}`);
+                            add(base + offset, "missing-label", `:${child.tag}{…} has no label — it is shown as text; write :${child.tag}[…]{…} or :${child.tag}{${key}="…"}`, undefined, find(new RegExp(`(?<!:):${escapeRe(child.tag)}\\{[^{}]*\\}?`), maskCode));
                         }
                         continue;
                     }
@@ -294,21 +346,21 @@ export function collectDiagnostics(tokens, lines, lineOf) {
                     const shown = child.type === "dogsbay_leaf_directive" ? `::${child.tag}` : `:${child.tag}[…]`;
                     if (child.type === "dogsbay_leaf_directive" && BLOCK_DIRECTIVES.has(child.tag)) {
                         if (labelled) {
-                            add(base + offset, "block-directive-inline", `${shown}[…] is shown as text: a block directive takes no [label]. ${blockForm(child.tag)}`);
+                            add(base + offset, "block-directive-inline", `${shown}[…] is shown as text: a block directive takes no [label]. ${blockForm(child.tag)}`, undefined, find(new RegExp(`::${escapeRe(child.tag)}\\[[^\\]]*\\]?`), maskCode));
                         }
                         else {
-                            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`);
+                            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`, undefined, find(new RegExp(`::${escapeRe(child.tag)}(?![\\w-])`), maskCode));
                         }
                     }
                     else {
-                        add(base + 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, find(child.type === "dogsbay_leaf_directive" ? new RegExp(`::${escapeRe(child.tag)}(?![\\w-])`) : new RegExp(`(?<!:):${escapeRe(child.tag)}\\[[^\\]]*\\]?`), maskCode));
                     }
                 }
             }
             // 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(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`);
+                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`, undefined, BRACES);
             }
             // 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
@@ -318,14 +370,14 @@ export function collectDiagnostics(tokens, lines, lineOf) {
                     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() === "")) {
-                    add(tok.map[0], "dropped-attributes", `this attribute block is read as an empty table row — put it on the line directly under the table's last row, or after a blank line`);
+                    add(tok.map[0], "dropped-attributes", `this attribute block is read as an empty table row — put it on the line directly under the table's last row, or after a blank line`, undefined, BRACES);
                 }
             }
             // markdown-it-attrs gives a list a block on the line after it (or after its last item's text); the tree keeps no list attributes
             // 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(braceLine(lines, code, tok.map[0], tok.map[1], true), "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`, undefined, BRACES);
             }
             // 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) {
@@ -334,17 +386,18 @@ export function collectDiagnostics(tokens, lines, lineOf) {
                 // 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() ?? "");
                 if (inline?.type === "inline" && looksLikeAttrs && (inline.children ?? []).every((c) => c.type === "text" && c.content.trim() === "")) {
-                    add(tok.map[0], "dropped-attributes", `this attribute block is on a line of its own and applies to nothing — put it at the end of the block's last line`);
+                    add(tok.map[0], "dropped-attributes", `this attribute block is on a line of its own and applies to nothing — put it at the end of the block's last line`, undefined, BRACES);
                 }
             }
             if (tok.type === "inline" && tok.map && tok.children) {
-                for (const child of tok.children) {
+                const at = childLines(tok.children);
+                for (const [k, child] of tok.children.entries()) {
                     const what = ATTRLESS_INLINE[child.type];
                     if (what && child.attrs?.length)
-                        add(tok.map[0], "dropped-attributes", `the attribute block on ${what} is dropped — only links, images and inline directives take attributes`);
+                        add(tok.map[0] + at[k], "dropped-attributes", `the attribute block on ${what} is dropped — only links, images and inline directives take attributes`, undefined, /(?<=[*_`~])\{[^{}]*\}/);
                 }
                 // Inline directives that keep no attributes (only badge and button do)
-                for (const child of tok.children) {
+                for (const [k, child] of tok.children.entries()) {
                     if (child.type !== "dogsbay_inline_directive_open" || child.tag === "badge" || child.tag === "button" || !KNOWN_INLINE_DIRECTIVES.has(child.tag))
                         continue;
                     let parsed = {};
@@ -363,7 +416,7 @@ export function collectDiagnostics(tokens, lines, lineOf) {
                             delete props[key];
                     }
                     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`);
+                        add(tok.map[0] + at[k], "dropped-attributes", `the attribute block on :${child.tag}[…] is dropped — of the inline directives only :badge and :button take attributes`, undefined, find(new RegExp(`:${escapeRe(child.tag)}\\[[^\\]]*\\](?<at>\\{[^{}]*\\})`), maskCode));
                     }
                 }
             }
@@ -375,10 +428,11 @@ export function collectDiagnostics(tokens, lines, lineOf) {
                 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 ?? "");
+                const content = last?.content ?? "";
+                const tail = trailingBraces(content, HEADING_ATTRS);
                 if (tail) {
-                    const problem = attributeProblem(tail[0]) ?? "could not be read";
-                    add(tok.map[0], "bad-attributes", `the heading's attribute block ${problem} — it is shown as text`);
+                    const problem = attributeProblem(content.slice(tail[0])) ?? "could not be read";
+                    add(tok.map[0], "bad-attributes", `the heading's attribute block ${problem} — it is shown as text`, undefined, (text) => trailingBraces(text, HEADING_ATTRS));
                 }
             }
         }

package/dist/directive-descriptions.d.ts

@@ -0,0 +1,11 @@
+/**
+ * One line per directive name, for an editor's completion detail (the VS Code extension asked,
+ * 2026-10-29): the name lists (`KNOWN_BLOCK_DIRECTIVES`, `LEAF_ONLY_DIRECTIVES`,
+ * `KNOWN_INLINE_DIRECTIVES`) are bare strings. Block and leaf names share one map; an inline
+ * directive (`:name[…]`) means something else under the same name (`:math[x]` vs `:::math`),
+ * so it has its own. A test fails on a listed name with no description.
+ */
+/** `:::name` / `::name` — block and leaf directives. */
+export declare const DIRECTIVE_DESCRIPTIONS: Readonly<Record<string, string>>;
+/** `:name[…]{…}` — inline directives. */
+export declare const INLINE_DIRECTIVE_DESCRIPTIONS: Readonly<Record<string, string>>;

package/dist/directive-descriptions.js

@@ -0,0 +1,71 @@
+/**
+ * One line per directive name, for an editor's completion detail (the VS Code extension asked,
+ * 2026-10-29): the name lists (`KNOWN_BLOCK_DIRECTIVES`, `LEAF_ONLY_DIRECTIVES`,
+ * `KNOWN_INLINE_DIRECTIVES`) are bare strings. Block and leaf names share one map; an inline
+ * directive (`:name[…]`) means something else under the same name (`:math[x]` vs `:::math`),
+ * so it has its own. A test fails on a listed name with no description.
+ */
+const CALLOUT = (kind) => `Callout: ${kind}. \`title\`, \`collapsed\` for a fold`;
+/** `:::name` / `::name` — block and leaf directives. */
+export const DIRECTIVE_DESCRIPTIONS = {
+    tabs: "Tab group; each `:::tab[Label]` is one tab. `syncKey` syncs groups across the site",
+    tab: "One tab of a `:::tabs` group, named by its label",
+    steps: "Numbered procedure; each `:::step[Title]` is one step",
+    step: "One step of a `:::steps` procedure",
+    cards: "Card grid; `:::card` children, or a list of links. `cols` sets the columns",
+    card: "Card with a title, optional `href`, `icon` and `image`",
+    "link-card": "Card that is one link: `href`, `title`, `description`",
+    grid: "Layout grid of `::grid-item` cells. `cols`, `gap`",
+    "grid-item": "One cell of a `:::grid`; `span`, `rowSpan`",
+    details: "Collapsible section; the label is the summary. `open` starts expanded",
+    callout: "Callout of a given `type` (note, tip, warning, …)",
+    note: CALLOUT("note"),
+    tip: CALLOUT("tip"),
+    info: CALLOUT("info"),
+    important: CALLOUT("important"),
+    warning: CALLOUT("warning"),
+    caution: CALLOUT("caution"),
+    danger: CALLOUT("danger"),
+    success: CALLOUT("success"),
+    hint: CALLOUT("hint"),
+    attention: CALLOUT("attention"),
+    error: CALLOUT("error"),
+    failure: CALLOUT("failure"),
+    bug: CALLOUT("bug"),
+    question: CALLOUT("question"),
+    abstract: CALLOUT("abstract"),
+    quote: CALLOUT("quote"),
+    button: "Link styled as a button: `href`, `variant`, `size`",
+    figure: "Image or content with a `caption`",
+    math: "Display math: the LaTeX as its body, or `::math{latex=\"…\"}`; same as `$$…$$`",
+    "api-endpoint": "API operation card (method, path, description)",
+    "api-params": "API parameter table",
+    "api-response": "API response with status and schema",
+    config: "Configuration reference block",
+    files: "File tree, from a nested list",
+    example: "Example: rendered output beside its source",
+    accordion: "Accordion; `:::accordion-item` children. `type` single or multiple",
+    "accordion-item": "One fold of an `:::accordion`, titled by its label",
+    autodoc: "Python API reference generated from source at build time",
+    "api-class": "Generated API reference: a class",
+    "api-member": "Generated API reference: a member",
+    "api-doc": "Generated API reference: a docstring",
+    "api-source": "Generated API reference: source code",
+    youtube: "YouTube video, loaded on click: `::youtube{#id title=\"…\"}`",
+    openapi: "API reference from an OpenAPI spec: `spec=\"/path/openapi.yaml\"`",
+    theme: "Content in another theme's tokens: `name=\"dark\"`",
+    avatar: "Avatar image with a fallback: `src`, `alt`, `fallback`, `size`",
+    "child-links": "Links to this page's children in the menu; `depth`",
+    "data-table": "Table from a data file: `src`, `path` to a list in it, `columns`, `headers`",
+    "data-cards": "Cards from a data file: `src`, `path`; `title`, `description`, `href`, `icon` name its keys",
+};
+/** `:name[…]{…}` — inline directives. */
+export const INLINE_DIRECTIVE_DESCRIPTIONS = {
+    kbd: "Keyboard key: `:kbd[Ctrl+C]`",
+    icon: "Icon by name: `:icon[check]`",
+    math: "Inline math: `:math[x^2]`",
+    mark: "Highlighted text",
+    highlight: "Highlighted text (same as `mark`)",
+    button: "Inline link button: `:button[Label]{href=\"…\"}`",
+    badge: "Badge: `:badge[New]{variant=\"…\"}`",
+};

package/dist/directive-props.js

@@ -31,9 +31,10 @@ export const DIRECTIVE_PROPS = {
     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"],
+    math: ["latex"],
+    // What data-directives.ts reads (docs/data-files.md)
+    "data-table": ["src", "path", "columns", "headers"],
+    "data-cards": ["src", "path", "title", "description", "href", "icon"],
     "child-links": ["depth", "title"],
 };
 /** Keys of `props` that `name` does not draw; empty when the directive is not checked. */

package/dist/index.d.ts

@@ -10,6 +10,7 @@ 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 { DIRECTIVE_DESCRIPTIONS, INLINE_DIRECTIVE_DESCRIPTIONS } from "./directive-descriptions.js";
 export { buildNavFromDirectory } from "./nav.js";
 export type { BuildNavOptions } from "./nav.js";
 export { loadNavFile } from "./nav-file.js";

package/dist/index.js

@@ -13,6 +13,7 @@ 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 { DIRECTIVE_DESCRIPTIONS, INLINE_DIRECTIVE_DESCRIPTIONS } from "./directive-descriptions.js";
 export { buildNavFromDirectory } from "./nav.js";
 export { loadNavFile } from "./nav-file.js";
 export { renderDiagrams } from "./renderers/diagrams.js";

package/dist/parse.js

@@ -25,6 +25,11 @@ import { splitFrontmatter } from "./frontmatter.js";
 import { protectDirectives, restoreDirectives } from "./directive-preserve.js";
 import { closesContainer, collectDiagnostics } from "./diagnostics.js";
 import { treeToDogsbayMd } from "./serialize.js";
+/** A 1-based line of the source as written, for a diagnostic's columns (split once, on first use). */
+function sourceLineOf(source) {
+    let lines;
+    return (line) => (lines ??= source.split(/\r\n|\n/))[line - 1];
+}
 /**
  * Parse Dogsbay Markdown into TreeNode[] plus extracted frontmatter.
  */
@@ -100,7 +105,7 @@ export function dogsbayMdToTree(source, options) {
     attachTableAttrsRow(tokens, content);
     // Before tokensToTree: it changes nothing these read, but read the parse as markdown-it left it
     // A lone-CR source never gets here with diagnostics (see the top), so `lineOf` is set
-    let diagnostics = options?.diagnostics ? collectDiagnostics(tokens, content.split(/\r\n|\n/), lineOf ?? (() => undefined)) : undefined;
+    let diagnostics = options?.diagnostics ? collectDiagnostics(tokens, content.split(/\r\n|\n/), lineOf ?? (() => undefined), sourceLineOf(source)) : undefined;
     if (diagnostics && lineOf && yamlLifted.badProps.length) {
         for (const bad of yamlLifted.badProps) {
             // The line YAML stops at, mapped itself: protected directives can add or stash lines in
@@ -112,7 +117,7 @@ export function dogsbayMdToTree(source, options) {
         }
         diagnostics = diagnostics.sort((a, b) => a.line - b.line);
     }
-    let tree = foldRelated(tokensToTree(tokens, options?.sourceLines ? lineOf : undefined));
+    let tree = foldRelated(tokensToTree(tokens, options?.sourceLines ? lineOf : undefined, content.split(/\r\n|\n/)));
     if (directiveTable) {
         // `preserve` restores every construct as a first-class node. `resolve-first`
         // restores INCLUDES as nodes too — they are transclusions of real content,
@@ -518,9 +523,9 @@ function markUnclosedGenericContainers(tokens, src) {
             tok.meta = { ...(tok.meta ?? {}), unclosed: true };
     }
 }
-function tokensToTree(tokens, lineOf) {
+function tokensToTree(tokens, lineOf, lines) {
     const nodes = [];
-    const ctx = { tokens, i: 0, ...(lineOf ? { lineOf } : {}) };
+    const ctx = { tokens, i: 0, ...(lineOf ? { lineOf } : {}), ...(lines ? { lines } : {}) };
     while (ctx.i < ctx.tokens.length) {
         const node = consumeBlock(ctx);
         if (node) {
@@ -1173,6 +1178,13 @@ function consumeContainer(ctx) {
             ctx.i++;
         }
     }
+    // A `:::math` body is LaTeX, not Markdown: read its lines as written (parsed, `\\` lost a
+    // backslash and `{aligned}` became attributes), and give it the shape `$$…$$` has, which every
+    // renderer draws. Its children were rendered by nothing: render-html drew an empty block.
+    if (name === "math" && registered !== GENERIC_CONTAINER) {
+        const latex = openTok.map && ctx.lines ? containerBody(ctx.lines, openTok.map) : children.map(nodeText).join("\n");
+        return { type: "math-block", props: { latex } };
+    }
     if (registered === GENERIC_CONTAINER) {
         // `:::name` with no closing `:::`: the line was prose (as before generic containers), not a block
         // that swallows the rest of the page.
@@ -1196,6 +1208,34 @@ function consumeContainer(ctx) {
     const node = mapContainerToTreeNode(name, attrs, children);
     return closer && !Array.isArray(node) ? { ...node, meta: { ...(node.meta ?? {}), closer } } : node;
 }
+/**
+ * A container's body lines as written: between its opener and its closer (`map[1]`, or the end
+ * when unclosed), less the opener's own indent and `>` markers, blank lines at either end dropped.
+ */
+function containerBody(lines, map) {
+    const prefix = /^[ \t>]*/.exec(lines[map[0]] ?? "")[0];
+    const body = lines.slice(map[0] + 1, Math.min(map[1], lines.length)).map((l) => {
+        if (l.startsWith(prefix))
+            return l.slice(prefix.length);
+        // A lazy or blank quote line: drop what of the prefix it has
+        let k = 0;
+        while (k < prefix.length && k < l.length && l[k] === prefix[k])
+            k++;
+        return l.slice(k);
+    });
+    while (body.length && body[0].trim() === "")
+        body.shift();
+    while (body.length && body[body.length - 1].trim() === "")
+        body.pop();
+    return body.join("\n");
+}
+/** A block's text, its paragraphs' inline text joined (the fallback with no source lines). */
+function nodeText(n) {
+    const inline = n.inline;
+    if (inline)
+        return inline.map((x) => x.text ?? x.latex ?? "").join("");
+    return (n.children ?? []).map(nodeText).join("\n");
+}
 /**
  * Convert a container + children into the appropriate TreeNode(s).
  * Handles callout type aliases, tabs definition-list recovery, cards list form, etc.
@@ -1251,6 +1291,11 @@ function mapContainerToTreeNode(name, attrs, children) {
         "quote",
         "callout",
     ]);
+    // `::math{latex="…"}` (the leaf in docs/dogsbay-md.md): the shape `$$…$$` has. As a `math`
+    // block it was written back as nothing and drawn empty.
+    if (name === "math" && typeof props.latex === "string" && children.length === 0) {
+        return { type: "math-block", props: { latex: props.latex } };
+    }
     if (CALLOUT_TYPES.has(name)) {
         const calloutProps = { ...props };
         if (name !== "callout")

package/package.json

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