@dogsbay/format-astro 0.2.0-beta.114 → 0.2.0-beta.116

package/dist/serialize.js

@@ -1,34 +1,9 @@
-import { walkInline, applyTextFlags, renderLeaf, indent, } from "@dogsbay/serialize-core";
+import { walkInline, applyTextFlags, renderLeaf, indent, isSafeHref, } from "@dogsbay/serialize-core";
+import { parseInline } from "@dogsbay/format-dogsbay-md";
 import { decorateDiff, hasDiffMarks } from "./diff-decoration.js";
-/**
- * Tone palette for `:::grid-item{label="..." tone="..."}` cells.
- * Each tone is a `bg + text` Tailwind class pair. Used to make grid demos
- * declarative — authors specify a tone instead of writing the styling.
- *
- * Exported because the scaffolded site's `global.css` must safelist
- * these classes via `@source inline()` — they only appear in
- * markdown-generated `.astro` pages, which Tailwind's content
- * scanner doesn't always pick up reliably (and consumers who put
- * their content/ outside the scanned globs won't pick them up at
- * all). See generateGlobalCss in project.ts.
- */
-export const TONE_CLASSES = {
-    // Primary scale (intensity)
-    "primary": "bg-primary text-primary-foreground",
-    "primary-strong": "bg-primary/80 text-primary-foreground",
-    "primary-medium": "bg-primary/60 text-primary-foreground",
-    "primary-half": "bg-primary/50 text-primary-foreground",
-    "primary-light": "bg-primary/20 text-primary",
-    "primary-soft": "bg-primary/10 text-primary",
-    // Neutral
-    "muted": "bg-muted text-muted-foreground",
-    // Named colors (for layout demos with distinct cells)
-    "blue": "bg-blue-500/15 text-blue-700 dark:text-blue-300",
-    "amber": "bg-amber-500/15 text-amber-700 dark:text-amber-300",
-    "green": "bg-green-500/15 text-green-700 dark:text-green-300",
-    "purple": "bg-purple-500/15 text-purple-700 dark:text-purple-300",
-    "red": "bg-red-500/15 text-red-700 dark:text-red-300",
-};
+import { TONE_CLASSES } from "./tone-classes.js";
+import { apiBlockHtml, apiPropertiesHtml } from "./api-markdown.js";
+export { TONE_CLASSES };
 const COMPONENT_IMPORTS = {
     "markdown-example": [
         'import MarkdownExample from "@ui/markdown-example/MarkdownExample.astro";',
@@ -64,6 +39,9 @@ const COMPONENT_IMPORTS = {
     ],
     diagram: ['import Diagram from "@ui/diagram/Diagram.astro";'],
     youtube: ['import YouTube from "@ui/youtube/YouTube.astro";'],
+    badge: ['import Badge from "@ui/badge/Badge.astro";'],
+    kbd: ['import Kbd from "@ui/kbd/Kbd.astro";'],
+    files: ['import FileTree from "@ui/files/FileTree.astro";'],
     "math-block": ['import MathKatex from "@ui/math/MathKatex.astro";'],
     image: ['import BlockImage from "@ui/image/Image.astro";'],
     "api-class": ['import ApiSymbol from "@ui/api-symbol/ApiSymbol.astro";'],
@@ -121,7 +99,12 @@ export function escapeExpr(s) {
     // JSON.stringify handles all special characters (quotes, backslashes, newlines, etc.)
     // and produces a valid JS string literal. This avoids template literal edge cases
     // where backtick + brace combinations create false expression boundaries.
-    return JSON.stringify(s);
+    //
+    // `<` becomes \u003c: Astro parses the template as HTML before the expression is
+    // JavaScript, so a `<script>` inside a string (a code block showing one, say) would
+    // be taken for a real script tag and its text compiled as JavaScript. Vite's
+    // dependency scan then fails to parse it and a production build breaks.
+    return JSON.stringify(s).replace(/</g, "\\u003c");
 }
 /** Escape for use in an HTML attribute value (double-quoted). */
 export function escapeAttr(s) {
@@ -140,6 +123,15 @@ export function componentAttr(name, value) {
  * src, etc.). `id`, `class`, and `style` are first-class; any other
  * key passes through verbatim.
  */
+/** `{…}` attributes on a COMPONENT (Badge, Button): `componentAttr`, which Astro does not entity-decode. */
+function renderInlineComponentAttrs(attrs) {
+    if (!attrs)
+        return "";
+    return Object.entries(attrs)
+        .filter(([, value]) => value !== undefined)
+        .map(([key, value]) => componentAttr(key, String(value)))
+        .join("");
+}
 function renderInlineElementAttrs(attrs) {
     if (!attrs)
         return "";
@@ -185,6 +177,7 @@ export function treeToAstro(nodes, options) {
         mode: options?.mode ?? "template",
         imageOptimization: options?.imageOptimization ?? false,
         codeBlockTitle: options?.codeBlockTitle ?? true,
+        imageCaptions: options?.imageCaptions ?? false,
         combinedPrefix: options?.combinedPrefix ?? "",
         // Mixed prose+endpoint pages render endpoints as embedded blocks;
         // pages that are nothing but endpoints/headings keep the
@@ -199,9 +192,9 @@ export function treeToAstro(nodes, options) {
     // (card.props.icon) registers `icon` directly at the call
     // site; this pre-scan picks up the inline `:icon[name]`
     // directives the writer can drop into prose.
-    if (treeContainsInlineIcon(nodes)) {
-        ctx.imports.add("icon");
-    }
+    // Badges and inline buttons are components too, registered the same way.
+    for (const key of inlineComponentsIn(nodes))
+        ctx.imports.add(key);
     const body = nodes.map((n) => nodeToAstro(n, ctx)).filter(Boolean).join("\n");
     const imports = [];
     const seen = new Set();
@@ -246,6 +239,10 @@ function nodeToAstroBase(node, ctx) {
             return codeToAstro(node, ctx);
         case "callout":
             return calloutToAstro(node, ctx);
+        case "files":
+            return filesToAstro(node, ctx);
+        case "container":
+            return genericContainerToAstro(node, ctx);
         case "details":
             return detailsToAstro(node, ctx);
         case "tabs":
@@ -278,8 +275,10 @@ function nodeToAstroBase(node, ctx) {
             return `<hr${classAttr}${passthrough} />`;
         }
         case "html":
-            // Raw HTML always uses set:html — it may contain anything
-            return `<Fragment set:html={${escapeExpr(node.html ?? "")}} />`;
+            // Raw HTML always uses set:html — it may contain anything. Callouts inside it
+            // (dogsbay-md's HTML table fallback writes `<div role="note" data-callout>`)
+            // render as real callouts
+            return htmlToAstro(node.html ?? "", ctx);
         case "table":
             return tableToAstro(node, ctx);
         case "thead":
@@ -330,9 +329,20 @@ function nodeToAstroBase(node, ctx) {
             return exampleToAstro(node, ctx);
         case "figure": {
             const caption = node.props?.caption;
+            // A figure of one code block: the caption goes in the code block's header bar,
+            // which then is the figure's caption
+            const only = node.children?.length === 1 ? node.children[0] : undefined;
+            if (caption && only?.type === "code") {
+                return codeToAstro(only, ctx, {
+                    caption: captionToAstro(caption, ctx),
+                    // The figure's attributes, except those the code block has itself (an id twice is invalid)
+                    attrs: renderPassthroughAttrs(node.props, ["caption", "class", ...Object.keys(only.props ?? {})]),
+                    classes: ["my-4", node.props?.class].filter(Boolean).join(" "),
+                });
+            }
             const inner = childrenToAstro(node, ctx);
             const body = caption
-                ? `${inner}\n<figcaption class="text-center text-sm text-muted-foreground mt-2">${escapeTemplate(caption)}</figcaption>`
+                ? `${inner}\n<figcaption class="text-center text-sm text-muted-foreground mt-2">${captionToAstro(caption, ctx)}</figcaption>`
                 : inner;
             return wrapBlock("figure", "my-4", node, body, ["caption"]);
         }
@@ -468,15 +478,37 @@ function templateInlineEmitters() {
             strike: (s) => `<s>${s}</s>`,
         }),
         link: (node, ctx) => {
+            // A link node an importer built directly never passed markdown-it's
+            // scheme check: a `javascript:` href keeps its text and loses the link.
+            if (!isSafeHref(node.href)) {
+                ctx.report("link", `unsafe link target dropped (${node.href.slice(0, 40)})`);
+                return ctx.recurse(node.children);
+            }
             const titleAttr = node.title ? componentAttr("title", node.title) : "";
             const extraAttrs = renderInlineElementAttrs(node.attrs);
+            // An inline `:button`: the Button component, small, keeping its variant ("primary" is the filled default).
+            if (node.button) {
+                const variant = buttonVariant(node.button.variant);
+                return `<Button${componentAttr("href", node.href)}${componentAttr("variant", variant)} size="sm"${titleAttr}${renderInlineComponentAttrs(node.attrs)}>${ctx.recurse(node.children)}</Button>`;
+            }
             return `<a href="${escapeAttr(node.href)}"${titleAttr}${extraAttrs}>${ctx.recurse(node.children)}</a>`;
         },
-        image: (node) => {
+        badge: (node, ctx) => `<Badge${componentAttr("variant", node.variant ?? "default")}${renderInlineComponentAttrs(node.attrs)}>${ctx.escape(node.text)}</Badge>`,
+        image: (node, ctx) => {
+            if (!isSafeHref(node.src, "image")) {
+                ctx.report("image", `unsafe image source dropped (${node.src.slice(0, 40)})`);
+                return ctx.escape(node.alt ?? "");
+            }
             const extraAttrs = renderInlineElementAttrs(node.attrs);
             return `<img src="${escapeAttr(node.src)}" alt="${escapeAttr(node.alt ?? "")}" loading="lazy"${extraAttrs} />`;
         },
-        code: (node, ctx) => `<code>${ctx.escape(node.text)}</code>`,
+        // Code inherits the emphasis around it (`*using the \`dita\` command*`): the parser
+        // flags the code span, and dropping the flags split the italics around the code
+        code: (node, ctx) => applyTextFlags(`<code>${ctx.escape(node.text)}</code>`, node, {
+            bold: (s) => `<strong>${s}</strong>`,
+            italic: (s) => `<em>${s}</em>`,
+            strike: (s) => `<s>${s}</s>`,
+        }),
         // The arm that did not exist — `:highlight[…]` / `:mark[…]` rendered as
         // nothing at all. The class list mirrors the canonical rendering in
         // `packages/ui/src/content-renderer/InlineRenderer.astro`, so a highlight
@@ -486,7 +518,8 @@ function templateInlineEmitters() {
         // pages, where nothing declares `color-scheme`.
         highlight: (node, ctx) => `<mark class="${HIGHLIGHT_CLASS}">${ctx.recurse(node.children)}</mark>`,
         "footnote-ref": (node, ctx) => `<sup><a href="#fn-${escapeAttr(node.label)}" id="fnref-${escapeAttr(node.label)}" class="text-primary hover:underline">[${ctx.escape(node.label)}]</a></sup>`,
-        kbd: (node, ctx) => node.keys.map((k) => `<kbd>${ctx.escape(k)}</kbd>`).join("+"),
+        // The Kbd component (keys styled as keycaps); plain <kbd> had no style beyond a monospace font.
+        kbd: (node, ctx) => node.keys.map((k) => `<Kbd>${ctx.escape(k)}</Kbd>`).join("+"),
         math: (node, ctx) => `<code class="math-inline">${ctx.escape(node.latex)}</code>`,
         icon: (node) => {
             // Inline icon — emits the platform `<Icon>` component which
@@ -515,10 +548,18 @@ function htmlModeInlineEmitters() {
         // EXPRESSION, inside a string that becomes a `set:html` value. Astro never
         // parses it as markup, so the reader saw the braces and quotes.
         link: (node, ctx) => {
+            if (!isSafeHref(node.href)) {
+                ctx.report("link", `unsafe link target dropped (${node.href.slice(0, 40)})`);
+                return ctx.recurse(node.children);
+            }
             const titleAttr = node.title ? ` title="${escapeAttr(node.title)}"` : "";
             const extraAttrs = renderInlineElementAttrs(node.attrs);
-            return `<a href="${escapeAttr(node.href)}"${titleAttr}${extraAttrs}>${ctx.recurse(node.children)}</a>`;
+            // No components in HTML mode: a marked link (and a marked span for a badge below).
+            const button = node.button ? ` data-button data-variant="${escapeAttr(buttonVariant(node.button.variant))}"` : "";
+            return `<a href="${escapeAttr(node.href)}"${titleAttr}${button}${extraAttrs}>${ctx.recurse(node.children)}</a>`;
         },
+        kbd: (node, ctx) => node.keys.map((k) => `<kbd>${ctx.escape(k)}</kbd>`).join("+"),
+        badge: (node, ctx) => `<span data-badge data-variant="${escapeAttr(node.variant ?? "default")}"${renderInlineElementAttrs(node.attrs)}>${ctx.escape(node.text)}</span>`,
         text: (node, ctx) => applyTextFlags(ctx.escape(node.text), node, {
             bold: (s) => `<strong>${s}</strong>`,
             italic: (s) => `<em>${s}</em>`,
@@ -552,6 +593,8 @@ function renderInline(nodes, ctx) {
         const html = inlineToHtml(nodes);
         return `<Fragment set:html={${escapeExpr(html)}} />`;
     }
+    // Inline parsed from a prop (a caption) is not in the page-level pre-scan; its components are imported here.
+    inlineComponentsIn([{ type: "paragraph", inline: nodes }], ctx.imports);
     return inlineToTemplate(nodes);
 }
 /** Render an HTML string in the current mode. */
@@ -572,7 +615,7 @@ function headingToAstro(node, ctx) {
     // `id` takes precedence over `slug` (slug is auto-generated, id is explicit user override)
     const id = node.props?.id ?? node.props?.slug ?? "";
     const anchor = id
-        ? `<a href="#${escapeAttr(id)}" class="ml-2 text-muted-foreground opacity-0 group-hover:opacity-100 no-underline" aria-hidden="true" tabindex="-1">&para;</a>`
+        ? `<a href="#${escapeAttr(id)}" class="ml-2 text-muted-foreground opacity-0 group-hover:opacity-100 no-underline" aria-hidden="true" tabindex="-1" data-pagefind-ignore>&para;</a>`
         : "";
     const idAttr = id ? ` id="${escapeAttr(id)}"` : "";
     const consumed = ["level", "slug", "id", "class", "text"];
@@ -625,7 +668,9 @@ function paragraphToAstro(node, ctx) {
             // Author-supplied {.class #id ...} on the image itself
             // (Phase 1.5 of plans/inline-attrs.md).
             const imageAttrs = renderInlineElementAttrs(img.attrs);
-            return `<BlockImage${componentAttr("src", img.src)}${componentAttr("alt", img.alt ?? "")}${imageAttrs}${passthrough}${imgDataAttr} />`;
+            // `content.imageCaptions: title`: the figure form of BlockImage, captioned by the title (as dogsbay-ssg).
+            const figure = ctx.imageCaptions && img.title ? ` block${componentAttr("title", img.title)}` : "";
+            return `<BlockImage${componentAttr("src", img.src)}${componentAttr("alt", img.alt ?? "")}${figure}${imageAttrs}${passthrough}${imgDataAttr} />`;
         }
     }
     const classAttr = mergeClassAttr("", node.props?.class);
@@ -652,7 +697,7 @@ function paragraphToAstro(node, ctx) {
     }).join("");
     return `<p${classAttr}${passthrough} set:html={${escapeExpr(html)}} />`;
 }
-function codeToAstro(node, ctx) {
+function codeToAstro(node, ctx, figure) {
     // Code content may live on props.code (Starlight convention) or node.html
     // (dogsbay-md convention). Same for lang — Starlight uses props.lang,
     // dogsbay-md uses props.language.
@@ -663,13 +708,18 @@ function codeToAstro(node, ctx) {
         ?? node.html
         ?? "";
     const title = node.props?.title;
-    const highlights = node.props?.highlights;
+    // The fence's documented `mark`, `ins` and `del` are CodeRich's highlights, diffAdd and diffRemove.
+    const lineSpec = (...values) => values.filter((v) => typeof v === "string" || typeof v === "number").map(String).filter(Boolean).join(",") || undefined;
+    const highlights = lineSpec(node.props?.highlights, node.props?.mark);
     const lineNumbers = node.props?.lineNumbers;
     const copyText = node.props?.copyText;
-    const diffAdd = node.props?.diffAdd;
-    const diffRemove = node.props?.diffRemove;
+    const diffAdd = lineSpec(node.props?.diffAdd, node.props?.ins);
+    const diffRemove = lineSpec(node.props?.diffRemove, node.props?.del);
     const isRich = lineNumbers || highlights || code.includes("[!code") || Boolean(diffAdd || diffRemove);
-    const classAttr = mergeClassAttr("", node.props?.class);
+    const classAttr = mergeClassAttr(figure?.classes ?? "", node.props?.class);
+    const figureAttrs = figure?.attrs ?? "";
+    // The component with its caption slot filled, or self-closing
+    const close = (tag, open) => figure ? `${open}>\n<Fragment slot="caption">${figure.caption}</Fragment>\n</${tag}>` : `${open} />`;
     const consumed = [
         "lang", "language", "code", "title", "highlights", "lineNumbers",
         "class", "ins", "del", "mark", "collapse", "copyText", "diffAdd", "diffRemove",
@@ -690,7 +740,7 @@ function codeToAstro(node, ctx) {
             attrs.push(`diffAdd="${escapeAttr(diffAdd)}"`);
         if (diffRemove)
             attrs.push(`diffRemove="${escapeAttr(diffRemove)}"`);
-        return `<CodeRich ${attrs.join(" ")}${classAttr}${passthrough} />`;
+        return close("CodeRich", `<CodeRich ${attrs.join(" ")}${classAttr}${passthrough}${figureAttrs}`);
     }
     ctx.imports.add("code");
     const attrs = [`code={${escapeExpr(code)}}`, `lang="${escapeAttr(lang)}"`];
@@ -699,7 +749,7 @@ function codeToAstro(node, ctx) {
     if (ctx.codeBlockTitle !== true) {
         attrs.push(`showTitle="${ctx.codeBlockTitle}"`);
     }
-    return `<CodeBlock ${attrs.join(" ")}${classAttr}${passthrough} />`;
+    return close("CodeBlock", `<CodeBlock ${attrs.join(" ")}${classAttr}${passthrough}${figureAttrs}`);
 }
 // Map GitHub alert names (and other aliases) to Alert component variants.
 // The Alert variant palette follows MkDocs Material; not every GitHub name
@@ -711,17 +761,71 @@ const CALLOUT_VARIANT_MAP = {
     hint: "tip",
     attention: "warning",
 };
-// Default title shown when a callout has no explicit one (post-variant-map).
-// Keyed by the mapped variant. Falls back to a capitalised variant otherwise.
+// Default title shown when a callout has no explicit one, keyed by the type
+// the author wrote: aliases share a look but keep their own name (`:::info` is
+// "Info", not the "Important" of the variant it shares). The same labels as
+// dogsbay-ssg (src/render/icons.ts CALLOUTS). Anything else: the type, capitalised.
 const CALLOUT_LABELS = {
     note: "Note",
+    info: "Info",
     tip: "Tip",
-    info: "Important",
-    warning: "Warning",
-    danger: "Caution",
-    failure: "Error",
+    hint: "Hint",
     success: "Success",
+    important: "Important",
+    warning: "Warning",
+    attention: "Attention",
+    caution: "Caution",
+    danger: "Danger",
+    error: "Error",
+    failure: "Failure",
+    question: "Question",
+    bug: "Bug",
+    example: "Example",
+    abstract: "Abstract",
+    quote: "Quote",
 };
+const CALLOUT_OPEN = /<div role="note" data-callout="([^"]*)"(?: data-title="([^"]*)")?>/g;
+/**
+ * Raw HTML as set:html fragments, with each marked callout div rendered by
+ * calloutToAstro. The fragments around a callout may hold unbalanced tags
+ * (`<table><tr><td>` before, `</td></tr></table>` after); set:html writes
+ * them verbatim, so the page's HTML is whole again.
+ */
+function htmlToAstro(html, ctx) {
+    const raw = (s) => (s ? `<Fragment set:html={${escapeExpr(s)}} />` : "");
+    const out = [];
+    let rest = html;
+    for (;;) {
+        CALLOUT_OPEN.lastIndex = 0;
+        const open = CALLOUT_OPEN.exec(rest);
+        if (!open)
+            break;
+        // The callout ends at its matching </div>
+        const divs = /<div\b|<\/div>/g;
+        divs.lastIndex = open.index + open[0].length;
+        let depth = 1;
+        let end = -1;
+        for (let m = divs.exec(rest); m; m = divs.exec(rest)) {
+            depth += m[0] === "</div>" ? -1 : 1;
+            if (depth === 0) {
+                end = m.index;
+                break;
+            }
+        }
+        if (end < 0)
+            break;
+        const unescape = (s) => s.replace(/&quot;/g, '"').replace(/&lt;/g, "<").replace(/&gt;/g, ">").replace(/&amp;/g, "&");
+        out.push(raw(rest.slice(0, open.index)));
+        out.push(calloutToAstro({
+            type: "callout",
+            props: { type: unescape(open[1]), ...(open[2] !== undefined ? { title: unescape(open[2]) } : {}) },
+            children: [{ type: "html", html: rest.slice(open.index + open[0].length, end) }],
+        }, ctx));
+        rest = rest.slice(end + "</div>".length);
+    }
+    out.push(raw(rest));
+    return out.filter(Boolean).join("\n") || raw(html);
+}
 function calloutToAstro(node, ctx) {
     ctx.imports.add("callout");
     // Callout variant may live on props.variant (Starlight / MkDocs importers)
@@ -735,11 +839,13 @@ function calloutToAstro(node, ctx) {
     // admonitions and GitHub-style alerts both show the type next to the icon,
     // and an empty title leaves the icon standing alone. Issue #004.
     const explicitTitle = node.props?.title;
+    // The default title names the authored type, not the variant it maps to.
     const title = explicitTitle && explicitTitle.length > 0
         ? explicitTitle
-        : CALLOUT_LABELS[variant] ?? variant.charAt(0).toUpperCase() + variant.slice(1);
+        : CALLOUT_LABELS[rawVariant] ?? rawVariant.charAt(0).toUpperCase() + rawVariant.slice(1);
     const icon = node.props?.icon;
-    const iconAttr = icon ? ` icon="${escapeAttr(icon)}"` : "";
+    // The authored type (`hint`, `caution`) beside the variant it shares, as dogsbay-ssg writes it.
+    const iconAttr = (icon ? ` icon="${escapeAttr(icon)}"` : "") + (node.props?.["data-type"] === undefined ? ` data-type="${escapeAttr(rawVariant)}"` : "");
     // User classes and passthrough attributes (id, data-*, aria-*, style)
     const classAttr = mergeClassAttr("my-4", node.props?.class);
     const passthrough = renderPassthroughAttrs(node.props, [
@@ -853,9 +959,47 @@ function wrapBlock(tag, defaultClass, node, content, consumed = []) {
     return `<${tag}${classAttr}${passthrough}>${sep}${content}${sep}</${tag}>`;
     void needsNewline;
 }
+/**
+ * `:::files` around a nested bullet list: FileTree, whose markup (files/markup.ts) dogsbay-ssg
+ * shares. An entry is a folder when it has entries or its name ends in "/".
+ */
+function filesToAstro(node, ctx) {
+    ctx.imports.add("files");
+    const isList = (n) => n.type === "unordered-list" || n.type === "ordered-list";
+    const items = (list) => (list?.children ?? [])
+        .filter((li) => li.type === "list-item")
+        .map((li) => {
+        const inline = li.inline ?? (li.children ?? []).find((c) => c.type === "paragraph")?.inline ?? [];
+        const sub = (li.children ?? []).find(isList);
+        const text = inline.map((n) => ("text" in n && typeof n.text === "string" ? n.text : "")).join("");
+        return { label: inlineToHtml(inline), folder: !!sub || /\/\s*$/.test(text), children: items(sub) };
+    });
+    const classAttr = mergeClassAttr("", node.props?.class);
+    // Each list is a tree; anything else in the block (an intro, a note) renders as it is.
+    // `<` is escaped in the JSON: a label may hold inline HTML, and a literal `</script>` in an
+    // expression breaks Vite's dependency scan (see escapeExpr).
+    return (node.children ?? [])
+        .map((child) => isList(child)
+        ? `<FileTree items={${JSON.stringify(items(child)).replace(/</g, "\\u003c")}}${classAttr} />`
+        : nodeToAstro(child, ctx))
+        .filter(Boolean)
+        .join("\n");
+}
+/**
+ * A `:::name` block with a name no renderer knows (a generic container): its content in a
+ * marked <div>, the title (text after the name) first.
+ */
+function genericContainerToAstro(node, ctx) {
+    const name = typeof node.meta?.name === "string" ? node.meta.name : "container";
+    const title = typeof node.meta?.title === "string" ? `<p class="font-semibold">${escapeTemplate(node.meta.title)}</p>\n` : "";
+    const classAttr = mergeClassAttr("", node.props?.class);
+    const passthrough = renderPassthroughAttrs(node.props, ["class"]);
+    return `<div data-directive="${escapeAttr(name)}"${classAttr}${passthrough}>\n${title}${childrenToAstro(node, ctx)}\n</div>`;
+}
 function detailsToAstro(node, ctx) {
     ctx.imports.add("details");
-    const variant = node.props?.variant ?? "note";
+    // `variant` as documented; `type` as dogsbay-ssg (and callouts) read it.
+    const variant = node.props?.variant ?? node.props?.type ?? "note";
     const title = node.props?.title ?? "Details";
     const open = node.props?.open;
     const icon = node.props?.icon;
@@ -867,7 +1011,7 @@ function detailsToAstro(node, ctx) {
         attrs.push(`icon="${escapeAttr(icon)}"`);
     const classAttr = mergeClassAttr("my-4", node.props?.class);
     const passthrough = renderPassthroughAttrs(node.props, [
-        "variant", "title", "open", "icon", "class", "summary",
+        "variant", "type", "title", "open", "icon", "class", "summary",
     ]);
     return `<CollapsibleAlert ${attrs.join(" ")}${classAttr}${passthrough}>
 ${indentStr(inner, 2)}
@@ -939,21 +1083,44 @@ function tabsToAstro(node, ctx) {
         .join("\n");
     const classAttr = mergeClassAttr("my-4", node.props?.class);
     const passthrough = renderPassthroughAttrs(node.props, ["sync", "default", "class"]);
+    // Groups with the same key switch together (db-tabs). Written `syncKey`, `sync-key` or `group`, as dogsbay-ssg reads it.
+    const syncKey = [node.props?.syncKey, node.props?.["sync-key"], node.props?.group].find((v) => typeof v === "string" && v !== "");
+    const syncAttr = syncKey ? componentAttr("syncKey", syncKey) : "";
     // Same encoding as the trigger/content `value` it selects — see above.
-    return `<Tabs${componentAttr("defaultValue", defaultValue)}${classAttr}${passthrough}>
+    return `<Tabs${componentAttr("defaultValue", defaultValue)}${syncAttr}${classAttr}${passthrough}>
   <TabsList>
 ${triggers}
   </TabsList>
 ${contents}
 </Tabs>`;
 }
+/**
+ * A caption is inline Markdown. Plain text renders exactly as before;
+ * formatting (`Sample \`<plugin>\` file`) renders as inline markup.
+ */
+function captionInline(caption) {
+    return parseInline(caption);
+}
+const isPlainCaption = (nodes) => nodes.every((n) => n.type === "text" && !n.bold && !n.italic && !n.strikethrough);
+function captionToAstro(caption, ctx) {
+    const nodes = captionInline(caption);
+    return isPlainCaption(nodes)
+        ? escapeTemplate(nodes.map((n) => (n.type === "text" ? n.text : "")).join(""))
+        : renderInline(nodes, ctx);
+}
 function tableToAstro(node, ctx) {
     ctx.imports.add("table");
     const classAttr = mergeClassAttr("my-4", node.props?.class);
     const caption = node.props?.caption;
-    const captionAttr = caption ? ` caption={${escapeExpr(caption)}}` : "";
+    const nodes = caption ? captionInline(caption) : [];
+    const plain = isPlainCaption(nodes);
+    // A plain caption stays the `caption` prop; a formatted one fills the table's caption slot
+    const captionAttr = caption && plain
+        ? ` caption={${escapeExpr(nodes.map((n) => (n.type === "text" ? n.text : "")).join(""))}}`
+        : "";
+    const captionSlot = caption && !plain ? `<Fragment slot="caption">${renderInline(nodes, ctx)}</Fragment>\n` : "";
     const passthrough = renderPassthroughAttrs(node.props, ["class", "caption"]);
-    return `<Table${classAttr}${captionAttr}${passthrough}>\n${childrenToAstro(node, ctx)}\n</Table>`;
+    return `<Table${classAttr}${captionAttr}${passthrough}>\n${captionSlot}${childrenToAstro(node, ctx)}\n</Table>`;
 }
 function diagramToAstro(node, ctx) {
     ctx.imports.add("diagram");
@@ -1019,6 +1186,11 @@ function footnoteListToAstro(node, ctx) {
 function footnoteDefToAstro(node, ctx) {
     const id = node.props?.id ?? "";
     const backrefId = node.props?.backrefId ?? "";
+    // Block content (a list, code): the blocks, with the backref after them
+    if (node.children?.length) {
+        const backref = backrefId ? `\n<a href="#${escapeAttr(backrefId)}" class="text-primary hover:underline">↩</a>` : "";
+        return `<li id="${escapeAttr(id)}" class="text-sm text-muted-foreground">\n${childrenToAstro(node, ctx)}${backref}\n</li>`;
+    }
     if (ctx.mode === "template" && node.inline) {
         const content = inlineToTemplate(node.inline);
         const backref = backrefId ? ` <a href="#${escapeAttr(backrefId)}" class="text-primary hover:underline">↩</a>` : "";
@@ -1088,11 +1260,17 @@ function endpointToAstro(node, ctx) {
     const path = props.path ?? "";
     const baseUrl = props.baseUrl ?? "";
     const summary = props.summary;
-    const description = props.description;
+    // Descriptions are CommonMark, rendered with raw HTML off: the components
+    // put them in the page with set:html (api-markdown.ts).
+    // (Compared as text first: the card hides a description equal to the
+    // summary, and the rendered HTML never equals it.)
+    const description = typeof props.description === "string" && props.description !== props.summary
+        ? apiBlockHtml(props.description)
+        : undefined;
     const deprecated = props.deprecated === true;
-    const parameters = props.parameters ?? [];
-    const requestBody = props.requestBody ?? [];
-    const responses = props.responses ?? [];
+    const parameters = apiPropertiesHtml(props.parameters) ?? [];
+    const requestBody = apiPropertiesHtml(props.requestBody) ?? [];
+    const responses = (props.responses ?? []).map((r) => r && Array.isArray(r.schema) ? { ...r, schema: apiPropertiesHtml(r.schema) } : r);
     const codeSamples = props.codeSamples ?? [];
     const requestBodyExample = props.requestBodyExample;
     const cardAttrs = [
@@ -1180,13 +1358,16 @@ function cardsToAstro(node, ctx) {
     if (cardNodes.length > 0) {
         const cards = cardNodes.map((card) => {
             const title = card.props?.title ?? "";
-            const href = card.props?.href ?? "";
+            const href = safeHref(card.props?.href);
             const description = card.props?.description;
             const icon = card.props?.icon;
             // Description sources: inline content, children, or props.description.
-            const inner = childrenToAstro(card, ctx)
+            // Child blocks carry their own <p>, so they get a <div>: <p><p>…</p></p> is invalid HTML.
+            const blocks = childrenToAstro(card, ctx);
+            const inner = blocks
                 || (card.inline ? inlineToTemplate(card.inline) : "")
                 || (description ? escapeTemplate(description) : "");
+            const descTag = blocks ? "div" : "p";
             // Icon renders inline before the title — picks up Lucide
             // SVG via the `icon` import. Resolved at build time; nothing
             // emitted when the name doesn't resolve (silent fallback).
@@ -1197,9 +1378,13 @@ function cardsToAstro(node, ctx) {
                 iconHtml = cardIconHtml(icon, title, ctx);
             }
             const titleHtml = title ? `<h3 class="text-base font-semibold">${escapeTemplate(title)}</h3>` : "";
-            const desc = inner
-                ? `<p class="text-sm text-muted-foreground mt-1 [text-decoration:none]">${inner}</p>`
+            // A description and a body are both shown (the description used to be dropped when a body existed).
+            const lead = blocks && description
+                ? `<p class="text-sm text-muted-foreground mt-1 [text-decoration:none]">${escapeTemplate(description)}</p>`
                 : "";
+            const desc = lead + (inner
+                ? `<${descTag} class="text-sm text-muted-foreground mt-1 [text-decoration:none]">${inner}</${descTag}>`
+                : "");
             const cardDefaultClass = href
                 ? "p-4 hover:border-foreground/20 transition-colors"
                 : "p-4";
@@ -1237,12 +1422,15 @@ function cardsToAstro(node, ctx) {
 function standaloneCardToAstro(node, ctx) {
     ctx.imports.add("card");
     const title = node.props?.title ?? "";
-    const href = node.props?.href ?? "";
+    const href = safeHref(node.props?.href);
     const description = node.props?.description;
     const icon = node.props?.icon;
-    const inner = childrenToAstro(node, ctx)
+    // Child blocks carry their own <p>, so they get a <div>: <p><p>…</p></p> is invalid HTML.
+    const blocks = childrenToAstro(node, ctx);
+    const inner = blocks
         || (node.inline ? inlineToTemplate(node.inline) : "")
         || (description ? escapeTemplate(description) : "");
+    const descTag = blocks ? "div" : "p";
     // Icon renders inline before the title (same shape as the
     // cards-list path). Resolved at build time via @dogsbay/icons.
     let iconHtml = "";
@@ -1253,9 +1441,13 @@ function standaloneCardToAstro(node, ctx) {
     const titleHtml = title
         ? `<h3 class="text-base font-semibold">${escapeTemplate(title)}</h3>`
         : "";
-    const desc = inner
-        ? `<p class="text-sm text-muted-foreground mt-1 [text-decoration:none]">${inner}</p>`
+    // A description and a body are both shown (the description used to be dropped when a body existed).
+    const lead = blocks && description
+        ? `<p class="text-sm text-muted-foreground mt-1 [text-decoration:none]">${escapeTemplate(description)}</p>`
         : "";
+    const desc = lead + (inner
+        ? `<${descTag} class="text-sm text-muted-foreground mt-1 [text-decoration:none]">${inner}</${descTag}>`
+        : "");
     const cardDefaultClass = href
         ? "p-4 hover:border-foreground/20 transition-colors"
         : "p-4";
@@ -1298,10 +1490,19 @@ function cardIconHtml(icon, title, ctx) {
     ctx.imports.add("icon");
     return `<Icon name="${escapeAttr(icon)}" class="size-5 mb-2 text-muted-foreground" />`;
 }
+/**
+ * A button's variant as `Button.astro` names it. The spec's `primary` is its
+ * filled `default` style; `Button.astro` has no `primary`, so it rendered
+ * with no fill at all.
+ */
+function buttonVariant(variant) {
+    return !variant || variant === "primary" ? "default" : variant;
+}
 function linkButtonToAstro(node, ctx) {
     ctx.imports.add("link-button");
-    const href = node.props?.href ?? "";
-    const variant = node.props?.variant;
+    const href = safeHref(node.props?.href);
+    const written = node.props?.variant;
+    const variant = written === undefined ? undefined : buttonVariant(written);
     const classAttr = mergeClassAttr("", node.props?.class);
     const passthrough = renderPassthroughAttrs(node.props, ["href", "variant", "class"]);
     // A button's label is phrasing content, so a lone paragraph child is
@@ -1314,6 +1515,11 @@ function linkButtonToAstro(node, ctx) {
         : leafContent(node, ctx) || childrenToAstro(node, ctx);
     return `<Button${componentAttr("href", href)}${variant ? componentAttr("variant", variant) : ""}${classAttr}${passthrough}>${label}</Button>`;
 }
+/** A card or button `href` from an importer, or "" (no link) when its
+ *  scheme could run script: these never passed markdown-it's link check. */
+function safeHref(href) {
+    return typeof href === "string" && isSafeHref(href) ? href : "";
+}
 function linkCardToAstro(node, ctx) {
     const hasRichChildren = (node.children ?? []).length > 0;
     if (hasRichChildren) {
@@ -1322,15 +1528,17 @@ function linkCardToAstro(node, ctx) {
     ctx.imports.add("link-card");
     const title = node.props?.title ?? "";
     const description = node.props?.description;
-    const href = node.props?.href ?? "";
+    const href = safeHref(node.props?.href);
     const titleAttr = componentAttr("title", title);
     const hrefAttr = componentAttr("href", href);
     const descAttr = description ? componentAttr("description", description) : "";
+    const icon = node.props?.icon;
+    const iconAttr = icon ? componentAttr("icon", icon) : "";
     const classAttr = mergeClassAttr("", node.props?.class);
     const passthrough = renderPassthroughAttrs(node.props, [
         "title", "description", "href", "icon", "class",
     ]);
-    return `<LinkCard${titleAttr}${descAttr}${hrefAttr}${classAttr}${passthrough} />`;
+    return `<LinkCard${titleAttr}${descAttr}${hrefAttr}${iconAttr}${classAttr}${passthrough} />`;
 }
 /**
  * Render an `accordion` TreeNode and its `accordion-item` children.
@@ -1469,31 +1677,25 @@ function childrenToAstro(node, ctx) {
  * icon usage on cards registers `icon` at the renderer call site;
  * this is the inline-only path. Returns true on first hit.
  */
-function treeContainsInlineIcon(nodes) {
-    if (!nodes)
-        return false;
-    for (const node of nodes) {
-        if (node.inline) {
-            for (const inl of node.inline) {
-                if (inlineHasIcon(inl))
-                    return true;
-            }
-        }
-        if (treeContainsInlineIcon(node.children))
-            return true;
-    }
-    return false;
-}
-function inlineHasIcon(node) {
-    if (node.type === "icon")
-        return true;
-    if ("children" in node && Array.isArray(node.children)) {
-        for (const child of node.children) {
-            if (inlineHasIcon(child))
-                return true;
-        }
+/** The component imports inline nodes need: `icon`, `badge`, and `link-button` for an inline `:button`. */
+function inlineComponentsIn(nodes, out = new Set()) {
+    const visit = (node) => {
+        if (node.type === "icon")
+            out.add("icon");
+        else if (node.type === "badge")
+            out.add("badge");
+        else if (node.type === "kbd")
+            out.add("kbd");
+        else if (node.type === "link" && node.button)
+            out.add("link-button");
+        if ("children" in node && Array.isArray(node.children))
+            node.children.forEach(visit);
+    };
+    for (const node of nodes ?? []) {
+        node.inline?.forEach(visit);
+        inlineComponentsIn(node.children, out);
     }
-    return false;
+    return out;
 }
 /** Indent, via the core's shared implementation (was a fourth local copy). */
 const indentStr = indent;