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

package/dist/browser.d.ts

@@ -11,8 +11,9 @@
  * (js-yaml only) rather than gray-matter, whose entry `require('fs')`s at
  * module load and would drag `node:fs` back into this graph.
  */
-export { dogsbayMdToTree, parseInline, type ParseResult, type ParseOptions } from "./parse.js";
+export { dogsbayMdToTree, parseInline, containerOpenBefore, type ParseResult, type ParseOptions } from "./parse.js";
 export { KNOWN_INLINE_DIRECTIVES, type ParseDiagnostic } from "./diagnostics.js";
+export { KNOWN_BLOCK_DIRECTIVES } from "./plugin-containers.js";
 export { treeToDogsbayMd, nodeToDogsbayMd } from "./serialize.js";
 export type { SerializeOptions } from "./types.js";
 export { inlineToDogsbayMd } from "./inline.js";

package/dist/browser.js

@@ -11,8 +11,10 @@
  * (js-yaml only) rather than gray-matter, whose entry `require('fs')`s at
  * module load and would drag `node:fs` back into this graph.
  */
-export { dogsbayMdToTree, parseInline } from "./parse.js";
+export { dogsbayMdToTree, parseInline, containerOpenBefore } from "./parse.js";
 export { KNOWN_INLINE_DIRECTIVES } from "./diagnostics.js";
+// The `:::name` blocks the parser knows (an editor completes names from it)
+export { KNOWN_BLOCK_DIRECTIVES } from "./plugin-containers.js";
 export { treeToDogsbayMd, nodeToDogsbayMd } from "./serialize.js";
 export { inlineToDogsbayMd } from "./inline.js";
 export { transformCodeRegions, transformProseLines, transformProseSegments, fenceOpenBefore, createFenceTracker, } from "./code-regions.js";

package/dist/container-rule.d.ts

@@ -0,0 +1,87 @@
+/**
+ * The `:::name` container block rule: markdown-it-container 4.0.0 (MIT,
+ * Vitaly Puzrin, Alex Kocharin), adapted. Three changes, all in how the
+ * closing line is found:
+ *
+ * 1. A closer may carry an HTML comment, `::: <!-- end note -->`, the way an
+ *    author labels an XML end tag. The comment changes nothing about which
+ *    container closes; it rides on the close token (`info`) so the parser can
+ *    keep it and diagnostics can check the name.
+ * 2. A `:::` line inside a code block does not close the container.
+ *    markdown-it-container scanned raw lines, so a code example showing a
+ *    directive closed the container around it and the rest of the page became
+ *    one code block, with no message. Which lines are code comes from one
+ *    block-level pass over the source with containers off (codeLines).
+ *
+ * 3. Blocks nest by a stack, not by colon count (NESTING below).
+ *
+ * Everything else (indentation, auto-close at the end of the parent) is
+ * markdown-it-container's.
+ *
+ * markdown-it-container's licence:
+ *
+ * Copyright (c) 2015 Vitaly Puzrin, Alex Kocharin.
+ *
+ * Permission is hereby granted, free of charge, to any person
+ * obtaining a copy of this software and associated documentation
+ * files (the "Software"), to deal in the Software without
+ * restriction, including without limitation the rights to use,
+ * copy, modify, merge, publish, distribute, sublicense, and/or sell
+ * copies of the Software, and to permit persons to whom the
+ * Software is furnished to do so, subject to the following
+ * conditions:
+ *
+ * The above copyright notice and this permission notice shall be
+ * included in all copies or substantial portions of the Software.
+ *
+ * THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND,
+ * EXPRESS OR IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES
+ * OF MERCHANTABILITY, FITNESS FOR A PARTICULAR PURPOSE AND
+ * NONINFRINGEMENT. IN NO EVENT SHALL THE AUTHORS OR COPYRIGHT
+ * HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER LIABILITY,
+ * WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING
+ * FROM, OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR
+ * OTHER DEALINGS IN THE SOFTWARE.
+ */
+import type MarkdownIt from "markdown-it";
+/**
+ * NESTING. A closer with N colons closes the innermost open block opened with exactly N colons,
+ * else the innermost opened with fewer, and any block still open inside it. So every block can close with plain `:::`
+ * (`:::steps` … `:::tabs` … `:::` … `:::`), and today's scaled nesting (`::::steps` … `:::tabs`
+ * … `:::` … `::::`) and the inverse (inner blocks with more colons) read the same. Pandoc's fenced
+ * divs nest the same way. Before the stack, a closer ended the OUTERMOST block it was long
+ * enough for, so a nested block needed more colons on the outer one, and one `:::` could close
+ * several blocks (that case now leaves the outer one open, and the diagnostic says why). "Exactly
+ * N first" keeps the old reading where the author scaled: `::::note` … `:::tip` … `::::` closes the
+ * note (and the tip with it) as before, rather than the tip.
+ *
+ * Only a known directive name opens a block in the scan. An unknown `:::word` is a block only if
+ * it has a closer of its own and is otherwise text (markUnclosedGenericContainers), and the scan
+ * cannot know which, so it does not push one: an unknown block nested at the same colon count
+ * as its parent still needs more colons on the parent. A body-less block (`:::youtube{#id}`) is
+ * pushed only when a closer that fits it follows, or it would take its parent's.
+ *
+ * VERIFY. The scan reads raw lines, and markdown-it may not read an opener there as one: in raw
+ * HTML, a `$$` math block, a fence that never closes. Where that is depends on where the blocks
+ * around it end, so no pass over the page can say in advance. So after the body is tokenized, every
+ * opener the scan pushed must have opened a block in it; any that did not are left out and the
+ * body is scanned and tokenized again. Counted wrongly, an opener leaves the outer block open to
+ * the end of the page (the rule before the stack lost one closer at most). What a block learns is
+ * kept for the parse, by its opening line: when an outer block retries, the blocks inside it are
+ * tokenized again and start from what they learned, rather than repeating their own retries (which
+ * doubled the work at every level). A learned line can be stale in the new context, so the check
+ * runs both ways: a skipped line that markdown-it did open as a block is pushed again. Retried
+ * lines come out of one budget per parse (a few times the page's lines); past it, the scan stands.
+ */
+export interface ContainerOptions {
+    validate: (params: string, markup: string) => boolean;
+    render?: (tokens: unknown[], idx: number) => string;
+}
+/**
+ * Make `name` an opener for the nesting scan (the known directives; not the generic container).
+ * A `leaf` is written with no body (`:::youtube{#id}`) and often with no closer.
+ */
+export declare function registerOpener(name: string, options?: {
+    leaf?: boolean;
+}): void;
+export declare function containerRule(md: MarkdownIt, name: string, options: ContainerOptions): void;

package/dist/container-rule.js

@@ -0,0 +1,292 @@
+/**
+ * What may follow a closer's colons: nothing, or spaces and one HTML comment, then spaces. The
+ * comment is not optional inside the group: `[ \t]*(…)?[ \t]*` backtracks quadratically on a long
+ * run of spaces followed by anything else.
+ */
+const CLOSER_TAIL = /^(?:[ \t]*|[ \t]*(<!--(?:(?!-->)[\s\S])*-->)[ \t]*)$/;
+/** state.env keys: the pre-pass that finds the code, and its result. */
+const NO_CONTAINERS = "__dogsbayNoContainers";
+const CODE_LINES = "__dogsbayCodeLines";
+/** state.env keys for VERIFY: the parse's retry budget, and each block's learned openers to skip. */
+const RETRY_BUDGET = "__dogsbayContainerRetries";
+const LEARNED = "__dogsbayContainerNotOpeners";
+/**
+ * The source lines inside a fenced code block, from one block-level pass over the whole source
+ * with containers switched off, made the first time a container needs it and kept in the parse's
+ * env. A `:::` line cannot change where a fence starts or ends (a fence ends only at its own
+ * closing fence or the end of its list item or quote), so the pass agrees with the real parse,
+ * and markdown-it reads fences in quotes, list items and definitions as a line scan does not.
+ * One pass per parse, so the cost is linear however many containers there are or how deep.
+ *
+ * Only a fence that CLOSES counts. With no container to end it, an unclosed fence in the pass runs
+ * to the end of the page, and every closer after it would be code: a ````` ```` ````` fence closed
+ * with three backticks would take the rest of the page into its container. Left out, it ends at
+ * the container's closer, as with markdown-it-container. (Still misread, and no worse than
+ * markdown-it-container: a `:::name` straight after a list item, lazily continuing it in the pass,
+ * so a fence indented four in the container is read in the item.)
+ */
+function codeLines(state) {
+    const env = state.env;
+    const cached = env?.[CODE_LINES];
+    if (cached && cached.src === state.src && cached.md === state.md)
+        return cached.lines;
+    const tokens = [];
+    state.md.block.parse(state.src, state.md, { [NO_CONTAINERS]: true }, tokens);
+    const source = state.src.split(/\r\n|\r|\n/);
+    const lines = new Set();
+    for (const t of tokens) {
+        if (t.type !== "fence" || !t.map || !closesFence(source[t.map[1] - 1], t.markup, t.map[1] - 1 > t.map[0]))
+            continue;
+        // A fence's opening line is not inside it; the lines after it, to its closing fence, are
+        for (let l = t.map[0] + 1; l < t.map[1]; l++)
+            lines.add(l);
+    }
+    if (env)
+        env[CODE_LINES] = { src: state.src, md: state.md, lines };
+    return lines;
+}
+/** Whether `line` (as written, with any `>` and indentation) is the closing fence of a fence opened with `markup`. */
+function closesFence(line, markup, after) {
+    if (!after || line === undefined)
+        return false;
+    const m = /^[ \t>]*(`{3,}|~{3,})[ \t]*$/.exec(line);
+    return m !== null && m[1][0] === markup[0] && m[1].length >= markup.length;
+}
+/** The directive names the scan treats as openers (plugin-containers registers them), and whether each is body-less. */
+const KNOWN_OPENERS = new Map();
+/** The known directive the text after an opener's colons starts with. */
+function knownOpener(rest) {
+    const m = /^\s*([A-Za-z][\w-]*)(?=$|[\s{[])/.exec(rest);
+    return m === null ? undefined : KNOWN_OPENERS.get(m[1]);
+}
+/**
+ * Make `name` an opener for the nesting scan (the known directives; not the generic container).
+ * A `leaf` is written with no body (`:::youtube{#id}`) and often with no closer.
+ */
+export function registerOpener(name, options = {}) {
+    KNOWN_OPENERS.set(name, { leaf: options.leaf === true });
+}
+/** Whether the next non-blank line after `line`, before `endLine`, is a closer for a block opened with `colons`. */
+function closerFollows(state, line, endLine, colons) {
+    for (let l = line + 1; l < endLine; l++) {
+        const start = state.bMarks[l] + state.tShift[l];
+        const max = state.eMarks[l];
+        if (start >= max)
+            continue;
+        const m = /^(:{3,})(.*)$/.exec(state.src.slice(start, max));
+        return m !== null && m[1].length >= colons && CLOSER_TAIL.test(m[2]);
+    }
+    return false;
+}
+/** Tokens whose lines are not block openers: an opener the scan pushed inside one is wrong (VERIFY). */
+const READ_AS_OTHER = new Set(["paragraph_open", "heading_open", "html_block", "fence", "code_block", "math_block", "hr", "table_open"]);
+/** The openers each block (by opening line) learned to skip in this parse (VERIFY). */
+function learned(state) {
+    const env = state.env;
+    if (!env)
+        return new Map();
+    const kept = env[LEARNED];
+    if (kept && kept.src === state.src)
+        return kept.map;
+    const map = new Map();
+    env[LEARNED] = { src: state.src, map };
+    return map;
+}
+/** The lines left in this parse's retry budget (VERIFY), shared by every block in it. */
+function retryBudget(state) {
+    const env = state.env;
+    const fresh = { lines: 4 * state.bMarks.length + 1000 };
+    if (!env)
+        return fresh;
+    const kept = env[RETRY_BUDGET];
+    if (kept && kept.src === state.src)
+        return kept.budget;
+    env[RETRY_BUDGET] = { src: state.src, budget: fresh };
+    return fresh;
+}
+export function containerRule(md, name, options) {
+    const MARKER = ":".charCodeAt(0);
+    function container(state, startLine, endLine, silent) {
+        const start = state.bMarks[startLine] + state.tShift[startLine];
+        const max = state.eMarks[startLine];
+        if (state.src.charCodeAt(start) !== MARKER)
+            return false;
+        if (state.env?.[NO_CONTAINERS])
+            return false;
+        let pos = start + 1;
+        while (pos <= max && state.src.charCodeAt(pos) === MARKER)
+            pos++;
+        const markerCount = pos - start;
+        if (markerCount < 3)
+            return false;
+        const markup = state.src.slice(start, pos);
+        const params = state.src.slice(pos, max);
+        if (!options.validate(params, markup))
+            return false;
+        if (silent)
+            return true;
+        const oldParent = state.parentType;
+        const oldLineMax = state.lineMax;
+        state.parentType = "container";
+        const tokensBefore = state.tokens.length;
+        // Openers markdown-it did not open, found by an earlier try (VERIFY above)
+        const known = learned(state);
+        const notOpeners = new Set(known.get(startLine));
+        let scan;
+        for (;;) {
+            scan = scanBody(state, startLine, endLine, markerCount, notOpeners);
+            // lazy continuations never run past the closer
+            state.lineMax = scan.nextLine;
+            const open = state.push(`container_${name}_open`, "div", 1);
+            open.markup = markup;
+            open.block = true;
+            open.info = params;
+            open.map = [startLine, scan.nextLine];
+            if (!scan.autoClosed && (scan.skippedCloser !== undefined || scan.legacyCloser !== undefined)) {
+                open.meta = {
+                    ...(open.meta ?? {}),
+                    ...(scan.skippedCloser !== undefined ? { skippedCloser: scan.skippedCloser } : {}),
+                    ...(scan.legacyCloser !== undefined ? { legacyCloser: scan.legacyCloser } : {}),
+                };
+            }
+            state.md.block.tokenize(state, startLine + 1, scan.nextLine);
+            const close = state.push(`container_${name}_close`, "div", -1);
+            close.markup = scan.closeMarkup;
+            close.block = true;
+            close.info = scan.closeComment;
+            // Wrong: a pushed opener's line that markdown-it read as something else. A line it read as
+            // nothing (past markdown-it's nesting limit, where it drops the rest) is not evidence.
+            // Missed: a skipped line markdown-it did open as a block (a learned line, stale here).
+            const pushed = new Set(scan.pushed);
+            const wrong = [];
+            const missed = [];
+            if (pushed.size > 0 || notOpeners.size > 0) {
+                for (let i = tokensBefore + 1; i < state.tokens.length; i++) {
+                    const t = state.tokens[i];
+                    if (!t.map)
+                        continue;
+                    if (READ_AS_OTHER.has(t.type)) {
+                        for (let l = t.map[0]; l < t.map[1]; l++)
+                            if (pushed.delete(l))
+                                wrong.push(l);
+                    }
+                    else if (t.nesting === 1 && t.type.startsWith("container_") && notOpeners.has(t.map[0]))
+                        missed.push(t.map[0]);
+                }
+            }
+            if (wrong.length === 0 && missed.length === 0)
+                break;
+            const budget = retryBudget(state);
+            if (budget.lines < scan.nextLine - startLine)
+                break;
+            budget.lines -= scan.nextLine - startLine;
+            for (const l of wrong)
+                notOpeners.add(l);
+            for (const l of missed)
+                notOpeners.delete(l);
+            state.tokens.length = tokensBefore;
+        }
+        if (notOpeners.size > 0)
+            known.set(startLine, new Set(notOpeners));
+        else
+            known.delete(startLine);
+        state.parentType = oldParent;
+        state.lineMax = oldLineMax;
+        state.line = scan.nextLine + (scan.autoClosed ? 1 : 0);
+        return true;
+    }
+    /** Find where the block opened at `startLine` ends (NESTING above), skipping the `notOpeners` lines as openers. */
+    function scanBody(state, startLine, endLine, markerCount, notOpeners) {
+        let code;
+        let nextLine = startLine;
+        const scan = { nextLine, autoClosed: false, closeMarkup: "", closeComment: "", pushed: [] };
+        // Blocks opened inside this one and not yet closed, innermost last (see NESTING above)
+        // `least` is the fewest colons from the outermost to this one, and `openCount` counts the open
+        // blocks by colons, so a closer that fits none is turned away without walking the stack
+        const inner = [];
+        const openCount = new Map();
+        const truncate = (k) => {
+            for (let j = k; j < inner.length; j++)
+                openCount.set(inner[j].colons, openCount.get(inner[j].colons) - 1);
+            inner.length = k;
+        };
+        for (;;) {
+            nextLine++;
+            // unclosed: closed by the end of the document or of the parent block
+            if (nextLine >= endLine)
+                break;
+            const start = state.bMarks[nextLine] + state.tShift[nextLine];
+            const max = state.eMarks[nextLine];
+            if (start >= max)
+                continue;
+            // a non-empty line indented less than the block ends it (a list item's container)
+            if (state.sCount[nextLine] < state.blkIndent)
+                break;
+            // a block opened deeper (in a list item) ended at a line indented less than its opener
+            while (inner.length > 0 && state.sCount[nextLine] < inner[inner.length - 1].indent)
+                truncate(inner.length - 1);
+            if (state.src.charCodeAt(start) !== MARKER)
+                continue;
+            // openers and closers are indented less than 4 spaces past the block
+            if (state.sCount[nextLine] - state.blkIndent >= 4)
+                continue;
+            let pos = start + 1;
+            while (pos < max && state.src.charCodeAt(pos) === MARKER)
+                pos++;
+            const colons = pos - start;
+            if (colons < 3)
+                continue;
+            const rest = state.src.slice(pos, max);
+            const tail = CLOSER_TAIL.exec(rest);
+            const opener = tail ? undefined : knownOpener(rest);
+            if (!tail && !opener)
+                continue;
+            // a `:::` in a code example is code
+            if ((code ??= codeLines(state)).has(nextLine)) {
+                if (tail && colons >= markerCount)
+                    scan.skippedCloser ??= nextLine;
+                continue;
+            }
+            if (opener) {
+                if (notOpeners.has(nextLine) || (opener.leaf && !closerFollows(state, nextLine, endLine, colons)))
+                    continue;
+                const least = Math.min(colons, inner.length > 0 ? inner[inner.length - 1].least : colons);
+                inner.push({ colons, indent: state.sCount[nextLine], least });
+                openCount.set(colons, (openCount.get(colons) ?? 0) + 1);
+                scan.pushed.push(nextLine);
+                continue;
+            }
+            // Where the rule before the stack (the first closer with enough colons) would have ended this block
+            if (colons >= markerCount)
+                scan.legacyCloser ??= nextLine;
+            // The innermost open block opened with exactly this many colons, else the innermost opened
+            // with fewer; it closes, and any block still open inside it. Index -1 is this block.
+            const closes = (fits) => {
+                for (let k = inner.length - 1; k >= 0; k--)
+                    if (fits(inner[k].colons))
+                        return k;
+                return fits(markerCount) ? -1 : undefined;
+            };
+            const exact = (openCount.get(colons) ?? 0) > 0 || markerCount === colons;
+            const fewer = markerCount < colons || (inner.length > 0 && inner[inner.length - 1].least < colons);
+            const k = exact ? closes((n) => n === colons) : fewer ? closes((n) => n < colons) : undefined;
+            // shorter than every open block: it closes nothing here
+            if (k === undefined)
+                continue;
+            if (k >= 0) {
+                truncate(k);
+                continue;
+            }
+            scan.autoClosed = true;
+            scan.closeMarkup = state.src.slice(start, pos);
+            scan.closeComment = tail?.[1] ?? "";
+            break;
+        }
+        scan.nextLine = nextLine;
+        return scan;
+    }
+    md.block.ruler.before("fence", `container_${name}`, container, { alt: ["paragraph", "reference", "blockquote", "list"] });
+    const render = options.render ?? (() => "");
+    md.renderer.rules[`container_${name}_open`] = render;
+    md.renderer.rules[`container_${name}_close`] = render;
+}

package/dist/diagnostics.d.ts

@@ -2,19 +2,26 @@ 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" | "bad-attributes";
+    code: "unclosed-container" | "stray-closer" | "unknown-container" | "unknown-inline" | "block-directive-inline" | "bad-attributes" | "closer-mismatch" | "dropped-attributes" | "missing-label";
     message: string;
 }
 /**
  * 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
- * indentation come first.
+ * indentation come first. A closer may carry one HTML comment, an end-tag
+ * label: `::: <!-- end note -->` (container-rule.ts).
  */
 export declare const closesContainer: (line: string | undefined, colons: number) => boolean;
+/**
+ * The container a closer's comment names, when it names one: `<!-- end note -->`,
+ * `<!-- /note -->` or `<!-- note -->`. Any other comment is the author's own words.
+ */
+export declare function closerLabel(comment: string): string | undefined;
 /** The inline directives the parser turns into nodes (parse.ts inlineDirectiveToNode); any other name stays literal text. */
 export declare const KNOWN_INLINE_DIRECTIVES: ReadonlySet<string>;
 type Token = {
     type: string;
+    attrs?: Array<[string, string]> | null;
     tag: string;
     info: string;
     markup: string;
@@ -23,6 +30,8 @@ type Token = {
     children: Token[] | null;
     meta: {
         unclosed?: boolean;
+        skippedCloser?: number;
+        legacyCloser?: number;
     } | null;
 };
 /**

package/dist/diagnostics.js

@@ -8,15 +8,28 @@
  * here: the parser passes any leaf through as a node of that type, and only a
  * renderer knows whether it can draw it (render-html reports the ones it can't).
  */
-import { GENERIC_CONTAINER } from "./plugin-containers.js";
+import { GENERIC_CONTAINER, KNOWN_BLOCK_DIRECTIVES } from "./plugin-containers.js";
+import { PRECEDES_TEXT } from "./plugin-inline-directives.js";
 /**
  * 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
- * indentation come first.
+ * indentation come first. A closer may carry one HTML comment, an end-tag
+ * label: `::: <!-- end note -->` (container-rule.ts).
  */
-export const closesContainer = (line, colons) => line !== undefined && new RegExp(`^:{${colons},}\\s*$`).test(line.replace(/^[\s>]*/, ""));
+export const closesContainer = (line, colons) => line !== undefined && new RegExp(`^:{${colons},}[ \\t]*(?:<!--(?:(?!-->)[\\s\\S])*-->[ \\t]*)?$`).test(line.replace(/^[\s>]*/, ""));
+/**
+ * The container a closer's comment names, when it names one: `<!-- end note -->`,
+ * `<!-- /note -->` or `<!-- note -->`. Any other comment is the author's own words.
+ */
+export function closerLabel(comment) {
+    return /^<!--\s*(?:end\s+|\/)?:*([A-Za-z][\w-]*)\s*-->$/.exec(comment.trim())?.[1];
+}
 /** The inline directives the parser turns into nodes (parse.ts inlineDirectiveToNode); any other name stays literal text. */
 export const KNOWN_INLINE_DIRECTIVES = new Set(["kbd", "icon", "math", "mark", "highlight", "button", "badge"]);
+/** Directives that are blocks: `::name{…}` draws one only on a line of its own (parse.ts mapContainerToTreeNode). */
+const BLOCK_DIRECTIVES = new Set([...KNOWN_BLOCK_DIRECTIVES, "avatar", "child-links", "link-card", "openapi", "autodoc"]);
+/** Inline tokens markdown-it-attrs can give attributes to that the parser has no field for (links and images keep theirs). */
+const ATTRLESS_INLINE = { strong_open: "bold text", em_open: "italic text", s_open: "struck-through text", code_inline: "inline code" };
 /**
  * Why an attribute block `{…}` cannot be read, or undefined when it can.
  * parseAttrs never fails: it reads what it can and drops the rest, so a
@@ -59,7 +72,16 @@ export function collectDiagnostics(tokens, lines, lineOf) {
                 const name = generic ? (/^[A-Za-z][\w-]*/.exec(info)?.[0] ?? info) : open[1];
                 const colons = (tok.markup ?? ":::").length;
                 const closed = closesContainer(lines[tok.map[1]], colons);
-                if (!closed) {
+                const skipped = tok.meta?.skippedCloser;
+                const legacy = tok.meta?.legacyCloser;
+                if (!closed && legacy !== undefined && !generic) {
+                    // Before the nesting stack, the closer on that line ended this block and the ones inside it
+                    add(tok.map[0], "unclosed-container", `:::${name} is never closed — the ${lines[legacy]?.trim()} on line ${lineOf(legacy) ?? "?"} closes only the innermost open block; each block needs its own closer (one \`:::\` used to close several)`);
+                }
+                else if (!closed && skipped !== undefined) {
+                    add(tok.map[0], "unclosed-container", `:::${name} is never closed — the ${lines[skipped]?.trim()} on line ${lineOf(skipped) ?? "?"} is inside a code block, so it does not close it (add a closer after the code)`);
+                }
+                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)})`);
@@ -67,6 +89,14 @@ export function collectDiagnostics(tokens, lines, lineOf) {
                 else if (generic) {
                     add(tok.map[0], "unknown-container", `:::${name} is not a known directive — it is shown as a plain box`);
                 }
+                if (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`);
+                    }
+                }
                 const rest = info.slice(name.length).trim();
                 if (rest.startsWith("{")) {
                     const problem = attributeProblem(rest);
@@ -74,12 +104,11 @@ export function collectDiagnostics(tokens, lines, lineOf) {
                         add(tok.map[0], "bad-attributes", `the attributes of :::${name} ${problem} — they are ignored`);
                 }
             }
-            // A `:::` line markdown-it-container did not take as a closer: the container it was
-            // meant to close ended earlier (an inner block of the same fence closed it), or there is none
+            // A `:::` line no open block took: every block it could close is already closed
             if (tok.type === "inline" && tok.map) {
                 (tok.content ?? "").split("\n").forEach((l, k) => {
-                    if (/^\s*:{3,}\s*$/.test(l)) {
-                        add(tok.map[0] + k, "stray-closer", `stray \`${l.trim()}\` — it closes nothing and is shown as text; to nest a directive, give the outer one more colons (::::steps around :::tabs)`);
+                    if (/^\s*:{3,}[ \t]*(?:<!--(?:(?!-->)[\s\S])*-->[ \t]*)?$/.test(l)) {
+                        add(tok.map[0] + k, "stray-closer", `stray \`${l.trim()}\` — it closes nothing and is shown as text: every block before it is already closed (each block takes one closer)`);
                     }
                 });
             }
@@ -96,7 +125,75 @@ export function collectDiagnostics(tokens, lines, lineOf) {
                     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}[…]`;
-                    add(tok.map[0] + offset, "unknown-inline", `${shown} is not a known inline directive — it is shown as text`);
+                    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`);
+                    }
+                    else {
+                        add(tok.map[0] + offset, "unknown-inline", `${shown} is not a known inline directive — it is shown as text`);
+                    }
+                }
+            }
+            // Attribute blocks markdown-it-attrs read and the tree has nowhere to keep
+            if (tok.type === "list_item_open" && tok.map && tok.attrs?.length) {
+                // parse.ts keepListItemBraces puts trailing braces back as text, or on a heading; what is left had nowhere to go
+                add(tok.map[0], "dropped-attributes", `the attribute block on this list item is dropped — list items take no attributes`);
+            }
+            // A table row that is only an attribute block, where the parser could not move it onto the
+            // table (not the last row, or text follows the table with no blank line): an empty row
+            if (tok.type === "tr_open" && tok.map) {
+                const cells = [];
+                for (let k = list.indexOf(tok) + 1; k < list.length && list[k].type !== "tr_close"; k++)
+                    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`);
+                }
+            }
+            // 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(tok.map[0], "dropped-attributes", `the attribute block on this list is dropped — lists take no attributes`);
+            }
+            // An attribute block alone on its line after a blank line: an empty paragraph that carries it
+            if (tok.type === "paragraph_open" && tok.map && tok.attrs?.length) {
+                const inline = list[list.indexOf(tok) + 1];
+                // Only what an author writes as attributes: `{#id}`, `{.class}`, `{key=…}`. markdown-it-attrs also eats a
+                // leftover MDX expression (`{/* prettier-ignore */}`), which is an importer's problem, not the author's
+                const looksLikeAttrs = /^\{\s*(?:[#.][^\s{}]|[\w-]+\s*=)/.test(inline?.content.trim() ?? "");
+                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`);
+                }
+            }
+            if (tok.type === "inline" && tok.map && tok.children) {
+                for (const child of tok.children) {
+                    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`);
+                }
+                // Inline directives that keep no attributes (only badge and button do)
+                for (const child of tok.children) {
+                    if (child.type !== "dogsbay_inline_directive_open" || child.tag === "badge" || child.tag === "button" || !KNOWN_INLINE_DIRECTIVES.has(child.tag))
+                        continue;
+                    let parsed = {};
+                    try {
+                        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
+                for (const child of tok.children) {
+                    if (child.type !== "text")
+                        continue;
+                    for (const m of child.content.matchAll(/:([a-z]+)\{/g)) {
+                        if (m.index > 0 && PRECEDES_TEXT.test(child.content[m.index - 1]))
+                            continue;
+                        if (KNOWN_INLINE_DIRECTIVES.has(m[1]))
+                            add(tok.map[0], "missing-label", `:${m[1]}{…} has no [label] — it is shown as text; write :${m[1]}[…]{…}`);
+                    }
                 }
             }
             // A heading's attribute block that markdown-it-attrs could not read stays in its text

package/dist/index.d.ts

@@ -2,12 +2,13 @@ export { treeToDogsbayMd, nodeToDogsbayMd } from "./serialize.js";
 export type { SerializeOptions } from "./types.js";
 export { DOGSBAY_MD_CAPABILITIES } from "./capabilities.js";
 export { inlineToDogsbayMd } from "./inline.js";
-export { dogsbayMdToTree, parseInline } from "./parse.js";
+export { dogsbayMdToTree, parseInline, containerOpenBefore } from "./parse.js";
 export { extractHeadings, slugifyHeadingText, type HeadingInfo } from "./headings.js";
 export { transformCodeRegions, transformProseLines, transformProseSegments, fenceOpenBefore, createFenceTracker } from "./code-regions.js";
 export { maskMinjaInCode, unmaskMinjaInCode, maskAllMinjaOpeners, isMinjaProcessedFence, stripInlineMinjaMarkers, stripFenceMinjaMarkers } from "./minja-mask.js";
 export type { ParseResult, ParseOptions } from "./parse.js";
 export { KNOWN_INLINE_DIRECTIVES, type ParseDiagnostic } from "./diagnostics.js";
+export { KNOWN_BLOCK_DIRECTIVES } from "./plugin-containers.js";
 export { buildNavFromDirectory } from "./nav.js";
 export type { BuildNavOptions } from "./nav.js";
 export { loadNavFile } from "./nav-file.js";

package/dist/index.js

@@ -5,11 +5,13 @@
 export { treeToDogsbayMd, nodeToDogsbayMd } from "./serialize.js";
 export { DOGSBAY_MD_CAPABILITIES } from "./capabilities.js";
 export { inlineToDogsbayMd } from "./inline.js";
-export { dogsbayMdToTree, parseInline } from "./parse.js";
+export { dogsbayMdToTree, parseInline, containerOpenBefore } from "./parse.js";
 export { extractHeadings, slugifyHeadingText } from "./headings.js";
 export { transformCodeRegions, transformProseLines, transformProseSegments, fenceOpenBefore, createFenceTracker } from "./code-regions.js";
 export { maskMinjaInCode, unmaskMinjaInCode, maskAllMinjaOpeners, isMinjaProcessedFence, stripInlineMinjaMarkers, stripFenceMinjaMarkers } from "./minja-mask.js";
 export { KNOWN_INLINE_DIRECTIVES } from "./diagnostics.js";
+// The `:::name` blocks the parser knows (an editor completes names from it)
+export { KNOWN_BLOCK_DIRECTIVES } from "./plugin-containers.js";
 export { buildNavFromDirectory } from "./nav.js";
 export { loadNavFile } from "./nav-file.js";
 export { renderDiagrams } from "./renderers/diagrams.js";

package/dist/parse.d.ts

@@ -42,3 +42,12 @@ export declare function dogsbayMdToTree(source: string, options?: ParseOptions):
  * Parse a single inline string to InlineNode[] (useful for testing).
  */
 export declare function parseInline(source: string): InlineNode[];
+/**
+ * Per line of `source` (the body, no front matter, split at `\n` as the commands engine splits
+ * it): whether the line is inside a `:::` block as the parser nests them. The opener's line is
+ * not, nor the closer's; the body between is. Read from the
+ * parse rather than re-derived, so the commands engine's outline (a heading in a block is never
+ * structure) cannot drift from the parser: a line scan cannot see where a list item ends a block,
+ * which names are blocks, or raw HTML. An unknown name never closed is text, so not a block.
+ */
+export declare function containerOpenBefore(source: string): boolean[];

package/dist/parse.js

@@ -87,6 +87,8 @@ export function dogsbayMdToTree(source, options) {
     const md = sharedParser();
     const tokens = md.parse(content, {});
     markUnclosedGenericContainers(tokens, content);
+    keepListItemBraces(tokens, content);
+    attachTableAttrsRow(tokens, content);
     // Before tokensToTree: it changes nothing these read, but read the parse as markdown-it left it
     const diagnostics = options?.diagnostics
         ? collectDiagnostics(tokens, 
@@ -304,6 +306,115 @@ function createParser() {
     });
     return md;
 }
+/**
+ * `{.compact-table}` on the line straight under a table, with no blank line, is the table's
+ * attribute block, as Pandoc and kramdown write it. markdown-it reads the line as one more row, and
+ * markdown-it-attrs gives the attributes to that row's first cell, so the table got an empty last
+ * row and no class. Such a row is moved onto the table: the last row, written without a `|`
+ * (a row the author wrote as `| {x} |` is a row), its first cell only an attribute block. Once
+ * per table. After a blank line the block already reached the table.
+ */
+function attachTableAttrsRow(tokens, src) {
+    const lines = src.split(/\r\n|\r|\n/);
+    for (let i = 0; i < tokens.length; i++) {
+        if (tokens[i].type !== "table_close")
+            continue;
+        let open = i - 1;
+        while (open >= 0 && tokens[open].type !== "table_open")
+            open--;
+        // the last row: tr_close just before tbody_close
+        if (tokens[i - 1]?.type !== "tbody_close" || tokens[i - 2]?.type !== "tr_close")
+            continue;
+        let tr = i - 2;
+        while (tr > open && tokens[tr].type !== "tr_open")
+            tr--;
+        const map = tokens[tr].map;
+        if (!map || /^[\s>]*\|/.test(lines[map[0]] ?? ""))
+            continue;
+        const cells = tokens.slice(tr + 1, i - 2);
+        const inlines = cells.filter((t) => t.type === "inline");
+        const first = cells[0];
+        if (!first?.attrs?.length || !/^\{[^{}]*\}$/.test((inlines[0]?.content ?? "").trim()))
+            continue;
+        if (inlines.slice(1).some((t) => t.content.trim() !== ""))
+            continue;
+        // Classes join; any other key from the row wins, as the later block does in markdown-it-attrs
+        const attrs = new Map((tokens[open].attrs ?? []).map(([k, v]) => [k, v]));
+        for (const [k, v] of first.attrs)
+            attrs.set(k, k === "class" && attrs.has("class") ? `${attrs.get("class")} ${v}` : v);
+        tokens[open].attrs = [...attrs];
+        // The row, and its tbody when it was the only row (the serializer writes no empty tbody)
+        const onlyRow = tokens[tr - 1]?.type === "tbody_open";
+        const from = onlyRow ? tr - 1 : tr;
+        tokens.splice(from, (onlyRow ? i : i - 1) - from);
+        i = from;
+    }
+}
+/**
+ * markdown-it-attrs reads a trailing `{…}` on a list item's text as the item's attributes, and the
+ * tree has nowhere to keep them, so the braces were lost: `- e.g. { minutes: 3 }` and
+ * `- mcp__{server}__{tool}` lost their ends (both in real docs). Trailing braces on a list item are
+ * literal text, as the spec says: they are put back from the source line. An item that starts
+ * with a heading gives them to the heading.
+ */
+function keepListItemBraces(tokens, src) {
+    const lines = src.split(/\r\n|\r|\n/);
+    tokens.forEach((tok, i) => {
+        if (tok.type !== "list_item_open" || !tok.attrs?.length)
+            return;
+        // An item that starts with a heading: `1. ### Title {#id}` is the heading's id, and a step
+        // heading's anchor was lost with it
+        if (tokens[i + 1]?.type === "heading_open") {
+            const heading = tokens[i + 1];
+            heading.attrs = [...(heading.attrs ?? []), ...tok.attrs];
+            tok.attrs = null;
+            return;
+        }
+        // Otherwise only an item that starts with text (diagnostics report any other)
+        if (tokens[i + 1]?.type !== "paragraph_open")
+            return;
+        const inline = tokens.slice(i + 1).find((t) => t.type === "inline" || t.type === "list_item_open" || t.type === "list_item_close");
+        const map = inline?.map;
+        if (inline?.type !== "inline" || !map)
+            return;
+        const tail = /\s*\{[^{}]*\}[ \t]*$/.exec(lines[map[1] - 1] ?? "");
+        const last = [...(inline.children ?? [])].reverse().find((c) => c.type === "text");
+        if (!tail || !last)
+            return;
+        // The source's own spacing: markdown-it-attrs may or may not have trimmed the text before it
+        const braces = tail[0].trimEnd();
+        last.content = last.content.trimEnd() + braces;
+        inline.content = inline.content.trimEnd() + braces;
+        tok.attrs = null;
+    });
+}
+/**
+ * Per line of `source` (the body, no front matter, split at `\n` as the commands engine splits
+ * it): whether the line is inside a `:::` block as the parser nests them. The opener's line is
+ * not, nor the closer's; the body between is. Read from the
+ * parse rather than re-derived, so the commands engine's outline (a heading in a block is never
+ * structure) cannot drift from the parser: a line scan cannot see where a list item ends a block,
+ * which names are blocks, or raw HTML. An unknown name never closed is text, so not a block.
+ */
+export function containerOpenBefore(source) {
+    // As markdown-it's normalize step (which block.parse skips): \r\n is a line break. A lone \r is
+    // one to markdown-it but not to the engine's split at \n, so it becomes a space
+    const src = source.replace(/\r\n/g, "\n").replace(/\r/g, " ");
+    const inside = new Array(src.split("\n").length).fill(false);
+    // block rules only: the inline pass changes no line a block spans
+    const md = sharedParser();
+    const tokens = [];
+    md.block.parse(src, md, {}, tokens);
+    markUnclosedGenericContainers(tokens, src);
+    for (const tok of tokens) {
+        const map = tok.map;
+        if (tok.nesting !== 1 || !tok.type.startsWith("container_") || !map || tok.meta?.unclosed)
+            continue;
+        for (let l = map[0] + 1; l < map[1] && l < inside.length; l++)
+            inside[l] = true;
+    }
+    return inside;
+}
 /**
  * markdown-it-container runs a block with no closing marker to the end of the document. For a
  * generic (unknown-name) container that would turn any prose line starting `:::word` into a block
@@ -956,9 +1067,12 @@ function consumeContainer(ctx) {
     ctx.i++;
     const children = [];
     const closeType = `container_${registered}_close`;
+    // The closer's end-tag label, `::: <!-- end note -->` (container-rule.ts): kept so it is written back
+    let closer = "";
     while (ctx.i < ctx.tokens.length) {
         const tok = ctx.tokens[ctx.i];
         if (tok.type === closeType) {
+            closer = tok.info ?? "";
             ctx.i++;
             break;
         }
@@ -988,10 +1102,11 @@ function consumeContainer(ctx) {
             type: "container",
             props: attrs ? attrsToProps(attrs) : {},
             children,
-            meta: { container: true, name, ...(title ? { title } : {}) },
+            meta: { container: true, name, ...(title ? { title } : {}), ...(closer ? { closer } : {}) },
         };
     }
-    return mapContainerToTreeNode(name, attrs, children);
+    const node = mapContainerToTreeNode(name, attrs, children);
+    return closer && !Array.isArray(node) ? { ...node, meta: { ...(node.meta ?? {}), closer } } : node;
 }
 /**
  * Convert a container + children into the appropriate TreeNode(s).
@@ -1629,6 +1744,9 @@ function tokensToInline(tokens, inheritedFmt = []) {
                 const name = tok.tag;
                 const attrs = tok.info ? JSON.parse(tok.info) : null;
                 const node = inlineDirectiveToNode(name, "", [], attrs);
+                // An unknown leaf stays as written (`::name{…}`), not in the text form `:name[]{…}`, which reads back as something else
+                if (node?.type === "html-inline" && node.html.startsWith(`:${name}[]`))
+                    node.html = `::${name}${node.html.slice(name.length + 3)}`;
                 if (node)
                     result.push(node);
                 break;

package/dist/plugin-containers.d.ts

@@ -1,9 +1,9 @@
 /**
- * Register markdown-it-container plugin for each known Dogsbay block directive.
+ * Register the container rule (container-rule.ts, adapted from markdown-it-container) for each
+ * known Dogsbay block directive.
  *
- * Uses the existing @markdown-it/container library. Each directive name is
- * registered separately; within same colon count, different-name directives can
- * nest. Same-name nesting requires more colons (::::).
+ * Each directive name is registered separately. Blocks nest at any colon count, the same name
+ * too: the rule keeps a stack of the blocks open inside it (NESTING in container-rule.ts).
  */
 import type MarkdownIt from "markdown-it";
 export declare const KNOWN_BLOCK_DIRECTIVES: readonly ["tabs", "tab", "steps", "step", "cards", "card", "grid", "grid-item", "details", "callout", "note", "tip", "info", "important", "warning", "caution", "danger", "success", "hint", "attention", "error", "failure", "bug", "question", "abstract", "quote", "button", "figure", "math", "api-endpoint", "api-params", "api-response", "config", "files", "example", "accordion", "accordion-item", "link-card", "autodoc", "api-class", "api-member", "api-doc", "api-source", "youtube", "openapi", "theme"];

package/dist/plugin-containers.js

@@ -1,4 +1,4 @@
-import container from "markdown-it-container";
+import { containerRule, registerOpener } from "./container-rule.js";
 import { parseAttrs } from "./parse-attrs.js";
 export const KNOWN_BLOCK_DIRECTIVES = [
     "tabs",
@@ -72,7 +72,9 @@ export const KNOWN_BLOCK_DIRECTIVES = [
 export const GENERIC_CONTAINER = "dogsbay_generic";
 export function containersPlugin(md) {
     for (const name of KNOWN_BLOCK_DIRECTIVES) {
-        md.use(container, name, {
+        // `:::youtube{#id}` has no body, and is often written with no closer
+        registerOpener(name, { leaf: name === "youtube" });
+        containerRule(md, name, {
             validate: (params) => {
                 const trimmed = params.trim();
                 if (!trimmed.startsWith(name))
@@ -103,7 +105,7 @@ export function containersPlugin(md) {
         });
     }
     const known = new Set(KNOWN_BLOCK_DIRECTIVES);
-    md.use(container, GENERIC_CONTAINER, {
+    containerRule(md, GENERIC_CONTAINER, {
         validate: (params) => {
             const m = /^([A-Za-z][\w-]*)(?=$|[\s{[])/.exec(params.trim());
             return m !== null && !known.has(m[1]);

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

@@ -14,4 +14,6 @@
  * The inline directive body contains nested inline tokens parsed recursively.
  */
 import type MarkdownIt from "markdown-it";
+/** A character a directive cannot follow directly (see inlineDirectiveRule). */
+export declare const PRECEDES_TEXT: RegExp;
 export declare function inlineDirectivesPlugin(md: MarkdownIt): void;

package/dist/plugin-inline-directives.js

@@ -1,4 +1,6 @@
 import { parseAttrs } from "./parse-attrs.js";
+/** A character a directive cannot follow directly (see inlineDirectiveRule). */
+export const PRECEDES_TEXT = /[\p{Script=Latin}\p{Script=Greek}\p{Script=Cyrillic}0-9:]/u;
 export function inlineDirectivesPlugin(md) {
     md.inline.ruler.before("emphasis", "dogsbay_inline_directive", inlineDirectiveRule);
 }
@@ -7,6 +9,11 @@ function inlineDirectiveRule(state, silent) {
     const src = state.src;
     if (src.charCodeAt(start) !== 0x3a /* : */)
         return false;
+    // Not straight after a word in a spaced script, a digit or a colon: `std::vector`, `x:Type[]`
+    // and a Tailwind `md:grid-cols-[…]` in an attribute block are text, not directives. CJK text
+    // has no spaces, so a directive may follow it directly (`按:kbd[Ctrl]键`)
+    if (start > 0 && PRECEDES_TEXT.test(src[start - 1]))
+        return false;
     // Determine leaf (::) vs text (:) directive
     const isLeaf = src.charCodeAt(start + 1) === 0x3a;
     const nameStart = isLeaf ? start + 2 : start + 1;

package/dist/serialize.js

@@ -29,6 +29,12 @@ export function nodeToDogsbayMd(node, options) {
     return renderNode(node, resolveOptions(options));
 }
 function renderNode(node, ctx) {
+    const out = renderNodeBody(node, ctx);
+    // A closer's end-tag label (`::: <!-- end note -->`), as the author wrote it
+    const closer = node.meta?.closer;
+    return typeof closer === "string" && /^<!--(?:(?!-->)[\s\S])*-->$/.test(closer) && /\n:{3,}$/.test(out) ? `${out} ${closer}` : out;
+}
+function renderNodeBody(node, ctx) {
     switch (node.type) {
         case "heading":
             return renderHeading(node);
@@ -423,7 +429,9 @@ function renderCallout(node, ctx) {
     // panel.
     const props = node.props ?? {};
     const hasOnlyTypeProp = Object.keys(props).every((k) => k === "type");
-    if (ctx.githubCallouts && hasOnlyTypeProp && GITHUB_CALLOUT_TYPES.has(type)) {
+    // Nor a closer's end-tag label: a `:::note` the author labelled stays a directive
+    const labelled = typeof node.meta?.closer === "string";
+    if (ctx.githubCallouts && hasOnlyTypeProp && !labelled && GITHUB_CALLOUT_TYPES.has(type)) {
         const tag = `[!${type.toUpperCase()}]`;
         return [tag, body]
             .join("\n")

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@dogsbay/format-dogsbay-md",
-  "version": "0.2.0-beta.125",
+  "version": "0.2.0-beta.127",
   "description": "Dogsbay Markdown dialect — canonical format for TreeNode[] with directives, YAML bodies, and intelligent fallbacks",
   "type": "module",
   "main": "dist/index.js",
@@ -36,13 +36,12 @@
     "js-yaml": "^5.2.1",
     "markdown-it": "^14.3.0",
     "markdown-it-attrs": "^5.0.0",
-    "markdown-it-container": "^4.0.0",
     "markdown-it-deflist": "^3.0.1",
     "markdown-it-footnote": "^4.0.0",
     "markdown-it-front-matter": "^0.2.4",
-    "@dogsbay/minja": "0.2.0-beta.125",
-    "@dogsbay/serialize-core": "0.2.0-beta.125",
-    "@dogsbay/types": "0.2.0-beta.125"
+    "@dogsbay/minja": "0.2.0-beta.127",
+    "@dogsbay/serialize-core": "0.2.0-beta.127",
+    "@dogsbay/types": "0.2.0-beta.127"
   },
   "license": "MIT",
   "repository": {