@dogsbay/format-astro 0.2.0-beta.152 → 0.2.0-beta.154

package/dist/granularity.js

@@ -113,7 +113,7 @@ export function openAsPageNode(slug, hrefPrefix) {
     const route = hrefPrefix ? `${hrefPrefix}/${slug}` : `/${slug}`;
     return {
         type: "paragraph",
-        props: { class: "dsb-open-as-page" },
+        props: { class: "dsb-open-as-page not-prose" },
         children: [{ type: "prose", inline: [{ type: "link", href: route, children: [{ type: "text", text: "Open as page ↗" }] }] }],
     };
 }

package/dist/project.d.ts

@@ -102,6 +102,7 @@ export interface AstroProjectOptions {
         into?: string;
         mediaOnly?: boolean;
         root?: string;
+        skip?: string[];
     }[];
     /**
      * Per-source asset directories with the URL prefix their content refs
@@ -168,6 +169,12 @@ export interface AstroProjectOptions {
      * See plans/search-facets.md.
      */
     taxonomyDisplay?: import("@dogsbay/types").SiteConfig["taxonomyDisplay"];
+    /**
+     * Declared taxonomies with `hierarchical: true`: a page's nested value in one
+     * of them is a search facet at every level (`ai/llm` → `ai`, `ai/llm`), as
+     * `pageFacets` (@dogsbay/site-files) maps it for DocsLayout and dogsbay-ssg.
+     */
+    hierarchicalTaxonomies?: string[];
     /** Canonical site URL — required for sitemap.xml + canonical tags */
     siteUrl?: string;
     /** Site-wide description used as default <meta name="description"> */
@@ -685,7 +692,29 @@ export interface SwitcherMap {
         label: string;
         home: string;
     }>>;
+    /**
+     * The version banner each unit's pages carry, keyed by site-files `unitKeyString` (product,
+     * locale, version; just the version for site-wide versions): the version's own text, or a kind
+     * the layout words (older, no longer maintained, not released), and the default version it points
+     * to with its home URL (where the link goes when the page is not in that version). As dogsbay-ssg:
+     * with a `products:` block from site-files `unitOf`; site-wide, an older version only. Left out
+     * when no page has one.
+     */
+    banners?: Record<string, VersionBannerData>;
 }
+/** A unit's version banner in switcherMap.json (site-files `UnitBanner`, `latest.home` as served). */
+export type VersionBannerData = ({
+    kind: "custom";
+    text: string;
+} | {
+    kind: "eol" | "prerelease" | "old";
+}) & {
+    latest?: {
+        id: string;
+        label: string;
+        home: string;
+    };
+};
 export interface SwitcherVariant {
     /** Present when the locale axis is active for this site. */
     locale?: string;

package/dist/project.js

@@ -26,10 +26,10 @@ function pageLiteral(value, indent) {
 }
 import { emitPluginRuntime } from "./plugins.js";
 import { buildLlmsTxt, buildSectionLlmsTxt, buildLlmsFullTxt } from "./llms-txt.js";
-import { buildSitemapFiles, buildSitemapIndex } from "./sitemap.js";
+import { buildSitemapFiles, buildSitemapIndex, pageHref } from "./sitemap.js";
 import { canonicalPlan } from "./canonical.js";
 import { headMetadata } from "./head-metadata.js";
-import { buildHeadersFile, buildRobotsTxt as buildRobotsTxtFile } from "@dogsbay/site-files";
+import { buildHeadersFile, buildRobotsTxt as buildRobotsTxtFile, pageFacets } from "@dogsbay/site-files";
 import { mergeHeaders, mergeRedirects, productRootRedirects, siteFiles, siteRootTarget, switcher as productSwitcherRows, productSwitcher, isVersionMenuHref, versionMenuHref, toPagesScript, toScript, unitKeyString, unitManifest, unitOf, } from "@dogsbay/site-files";
 import { assembleBook, estimateTreeBytes } from "./granularity.js";
 /**
@@ -41,7 +41,7 @@ function singlePageLinkLines(href, indent) {
     if (!href)
         return [];
     const pad = " ".repeat(indent);
-    return [`${pad}<a class="dsb-read-single-page" href="${href}">Read as single page →</a>`];
+    return [`${pad}<a class="dsb-read-single-page not-prose" href="${href}">Read as single page →</a>`];
 }
 import { normalizeBasePath, basePathSegments, buildCurrentPath, withBasePath, parseSiteUrl, combinePrefix, } from "./base-path.js";
 import { buildBlogData, blogAdjacency } from "./blog.js";
@@ -1658,10 +1658,11 @@ export async function emitAstroPages(pages, nav, outputDir, options) {
             const dest = mount.into
                 ? join(outputDir, "public", mount.root ?? "_assets", mount.into)
                 : join(outputDir, "public", mount.root ?? "_assets");
+            const skipped = new Set((mount.skip ?? []).map((f) => join(mount.dir, f)));
             if (mount.mediaOnly)
-                copyMediaTree(mount.dir, dest);
+                copyMediaTree(mount.dir, dest, skipped);
             else
-                cpSync(mount.dir, dest, { recursive: true });
+                cpSync(mount.dir, dest, { recursive: true, filter: (src) => !skipped.has(src) });
         }
     }
     let generated = 0;
@@ -1933,6 +1934,14 @@ export async function emitAstroPages(pages, nav, outputDir, options) {
             const pageTaxonomies = pageMeta?.taxonomies && Object.keys(pageMeta.taxonomies).length > 0
                 ? pageMeta.taxonomies
                 : undefined;
+            // The page's search facets, by the mapping dogsbay-ssg's index uses
+            // too; DocsLayout writes them as Pagefind filters. Computed here
+            // because only the build knows which taxonomies are hierarchical.
+            const pageFacetValues = pageFacets(pageMeta, {
+                tagPrefixes: options.tagPrefixes,
+                hierarchical: options.hierarchicalTaxonomies,
+                unit: { product: page.multiSource?.namespace, version: page.multiSource?.version },
+            });
             // `tagsIndexPath` flows to `<TagList>` for chip hrefs
             // (`${indexPath}/${tag}/`). Caller passes the raw config value
             // (e.g. `/tags`); we bake the COMBINED prefix (urlBase from
@@ -2095,6 +2104,7 @@ export async function emitAstroPages(pages, nav, outputDir, options) {
                 `const pageAudience = ${pageLiteral(pageAudience ?? null)};`,
                 `const pageCategory = ${pageLiteral(pageCategory ?? null)};`,
                 `const pageTaxonomies = ${pageLiteral(pageTaxonomies ?? null)};`,
+                `const pageFacets = ${pageLiteral(pageFacetValues)};`,
                 `const tagsIndexPath = ${pageLiteral(tagsIndexPath)};`,
                 `const lastUpdated = ${pageLiteral(pageLastUpdated)} || undefined;`,
                 `const llmActionsProps = ${pageLiteral(llmActionsEnabled
@@ -2150,6 +2160,7 @@ export async function emitAstroPages(pages, nav, outputDir, options) {
                 `  category={pageCategory ?? undefined}`,
                 `  lastUpdated={lastUpdated}`,
                 `  taxonomies={pageTaxonomies ?? undefined}`,
+                `  facets={pageFacets}`,
                 `  autoH1={${autoH1}}`,
                 `  autoLede={${autoLede}}`,
                 `  llmActions={llmActionsProps}`,
@@ -2636,13 +2647,17 @@ export function emitSwitcherMap(pages, outputDir, options) {
         const variant = {
             ...(ms.locale !== undefined ? { locale: ms.locale } : {}),
             ...(ms.version !== undefined ? { version: ms.version } : {}),
-            url: `${combined}/${page.slug}`,
+            // As the site serves the page (a folder, with the slash): a raw slug cost each menu link a redirect
+            url: pageHref(page.slug, combined),
         };
         if (!byLogicalKey[key])
             byLogicalKey[key] = [];
         byLogicalKey[key].push(variant);
     }
     const data = { versions, locales, byLogicalKey };
+    const banners = versionBanners(options, combined, pages);
+    if (banners)
+        data.banners = banners;
     const menus = versionMenus(options, combined);
     if (menus)
         data.versionMenu = menus;
@@ -2656,6 +2671,61 @@ export function emitSwitcherMap(pages, outputDir, options) {
     mkdirSync(dataDir, { recursive: true });
     writeFileSync(outPath, JSON.stringify(data, null, 2));
 }
+/**
+ * Each unit's version banner, as dogsbay-ssg shows it: with a `products:` block the shared model's
+ * (site-files `unitOf`), none on a hidden version (the number a `latest` alias serves); site-wide,
+ * an older version's, pointing at the default version's unit with the same source and language
+ * (its home read from that unit's pages), and none when the default version has no such unit.
+ */
+function versionBanners(options, combined, pages) {
+    const out = {};
+    if (options.products) {
+        const model = options.products;
+        for (const u of model.units) {
+            if (u.version === undefined)
+                continue;
+            const product = model.products.find((p) => p.name === u.product);
+            if (product?.versions.find((v) => v.id === u.version)?.hidden)
+                continue;
+            const b = unitOf(model, u).banner;
+            if (b)
+                out[unitKeyString(u)] = b.latest ? { ...b, latest: { ...b.latest, home: `${combined}${b.latest.home}` } } : b;
+        }
+    }
+    else if (options.defaultVersion) {
+        const def = options.versions?.find((v) => v.id === options.defaultVersion);
+        if (!def)
+            return undefined;
+        const hidden = new Set((options.versions ?? []).filter((v) => v.hidden).map((v) => v.id));
+        // Each unit (source, language, version) and the URL prefix its pages are served under
+        const home = new Map();
+        const units = new Map();
+        const bare = (x) => x.replace(/^\/+|\/+$/g, "").replace(/(^|\/)index$/, "");
+        for (const page of pages) {
+            const ms = page.multiSource;
+            if (!ms?.version || page.redirect)
+                continue;
+            const u = { ...(ms.namespace ? { product: ms.namespace } : {}), ...(ms.locale ? { locale: ms.locale } : {}), version: ms.version };
+            const key = unitKeyString(u);
+            units.set(key, u);
+            if (home.has(key))
+                continue;
+            const slug = bare(page.slug);
+            const own = bare(ms.originalSlug);
+            const prefix = own === "" ? slug : slug.endsWith(`/${own}`) ? slug.slice(0, -own.length - 1) : slug === own ? "" : undefined;
+            if (prefix !== undefined)
+                home.set(key, `${combined}/${prefix ? `${prefix}/` : ""}`);
+        }
+        for (const [key, u] of units) {
+            if (u.version === def.id || hidden.has(u.version))
+                continue;
+            const target = home.get(unitKeyString({ ...u, version: def.id }));
+            if (target)
+                out[key] = { kind: "old", latest: { id: def.id, label: def.label ?? def.id, home: target } };
+        }
+    }
+    return Object.keys(out).length ? out : undefined;
+}
 /** The product menu per locale (`<locale|_>`), or nothing with fewer than two products. */
 function productMenuRows(model, combined) {
     const locales = model.localeAxis ? [...new Set(model.units.map((u) => u.locale))] : [undefined];
@@ -3523,11 +3593,13 @@ const MOUNT_MEDIA_EXTS = new Set([
     ".svg", ".ico", ".pdf", ".mp4", ".webm",
 ]);
 /** Recursively copy only media files, preserving relative structure. */
-function copyMediaTree(srcDir, destDir) {
+function copyMediaTree(srcDir, destDir, skip) {
     for (const entry of readdirSync(srcDir)) {
         const full = join(srcDir, entry);
+        if (skip?.has(full))
+            continue;
         if (statSync(full).isDirectory()) {
-            copyMediaTree(full, join(destDir, entry));
+            copyMediaTree(full, join(destDir, entry), skip);
             continue;
         }
         const dot = entry.lastIndexOf(".");

package/dist/serialize.js

@@ -308,9 +308,13 @@ function nodeToAstroBase(node, ctx) {
         case "tr":
             ctx.imports.add("table");
             return `<TableRow>\n${childrenToAstro(node, ctx)}\n</TableRow>`;
-        case "th":
+        case "th": {
             ctx.imports.add("table");
-            return `<TableHead>${leafContent(node, ctx)}</TableHead>`;
+            // An empty header cell is no header (axe `empty-table-header`): a plain cell in the header row
+            const content = leafContent(node, ctx);
+            // Written here, not through TableHead: a site keeps the component it was scaffolded with
+            return content.trim() ? `<TableHead>${content}</TableHead>` : `<td class="${EMPTY_HEADER_CELL_CLASS}"></td>`;
+        }
         case "td":
             ctx.imports.add("table");
             return `<TableCell>${leafContent(node, ctx)}</TableCell>`;
@@ -640,8 +644,15 @@ function proseToAstro(node, ctx) {
         return renderHtml(node.html, ctx);
     return "";
 }
+/** TableHead's classes, for a header row's empty cell written as a plain `td`. */
+const EMPTY_HEADER_CELL_CLASS = "px-2 py-2 text-left align-bottom font-semibold text-muted-foreground";
+/** A card title's heading: one level below the last heading on the page, h6 at most. */
+function cardTitleTag(ctx) {
+    return `h${Math.min((ctx.lastHeading ?? 1) + 1, 6)}`;
+}
 function headingToAstro(node, ctx) {
     const level = node.props?.level ?? 1;
+    ctx.lastHeading = level;
     // `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
@@ -1347,6 +1358,7 @@ function apiSymbolToAstro(node, ctx) {
     // By position, not by type (apiSymbolLevels): a module-level function was
     // an h3 straight under the page's h1, and a class inside a class an h2.
     const level = ctx.apiSymbolLevels.get(node) ?? (node.type === "api-class" ? 2 : 3);
+    ctx.lastHeading = level;
     const attrs = [
         componentAttr("name", name).trimStart(),
         componentAttr("kind", kind).trimStart(),
@@ -1534,9 +1546,14 @@ function cardsToAstro(node, ctx) {
             const href = safeHref(card.props?.href);
             const description = card.props?.description;
             const icon = card.props?.icon;
+            // The title's level before the body is written: a heading inside it must not move this
+            // card's title, nor the next card's (each starts from the level before the group)
+            const tag = cardTitleTag(ctx);
+            const before = ctx.lastHeading;
             // Description sources: inline content, children, or props.description.
             // Child blocks carry their own <p>, so they get a <div>: <p><p>…</p></p> is invalid HTML.
             const blocks = wholeCardLink(!!href, () => childrenToAstro(card, ctx));
+            ctx.lastHeading = before;
             const inner = blocks
                 || (card.inline ? wholeCardLink(!!href, () => inlineToTemplate(card.inline)) : "")
                 || (description ? escapeTemplate(description) : "");
@@ -1550,7 +1567,7 @@ function cardsToAstro(node, ctx) {
             if (icon) {
                 iconHtml = cardIconHtml(icon, title, ctx);
             }
-            const titleHtml = title ? `<h3 class="${CARD_TITLE_CLASS}">${escapeTemplate(title)}</h3>` : "";
+            const titleHtml = title ? `<${tag} class="${CARD_TITLE_CLASS}">${escapeTemplate(title)}</${tag}>` : "";
             // 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>`
@@ -1569,7 +1586,7 @@ function cardsToAstro(node, ctx) {
                 "title", "href", "description", "icon", "variant", "class", "tone",
             ]);
             if (href) {
-                return `<Card${cardClassAttr}${cardPass}>\n<CardContent class="p-0">\n<a href="${escapeAttr(href)}" class="not-prose [text-decoration:none] text-foreground">\n${iconHtml}\n${titleHtml}\n${desc}\n</a>\n</CardContent>\n</Card>`;
+                return `<Card${cardClassAttr}${cardPass}>\n<CardContent class="p-0">\n<a href="${escapeAttr(href)}" data-variant="card" class="[text-decoration:none] text-foreground">\n${iconHtml}\n${titleHtml}\n${desc}\n</a>\n</CardContent>\n</Card>`;
             }
             return `<Card${cardClassAttr}${cardPass}>\n<CardContent class="p-0">\n${iconHtml}\n${titleHtml}\n${desc}\n</CardContent>\n</Card>`;
         }).join("\n");
@@ -1601,8 +1618,12 @@ function standaloneCardToAstro(node, ctx) {
     const href = safeHref(node.props?.href);
     const description = node.props?.description;
     const icon = node.props?.icon;
+    // The title's level before the body is written (a heading inside it must not move it)
+    const tag = cardTitleTag(ctx);
+    const before = ctx.lastHeading;
     // Child blocks carry their own <p>, so they get a <div>: <p><p>…</p></p> is invalid HTML.
     const blocks = wholeCardLink(!!href, () => childrenToAstro(node, ctx));
+    ctx.lastHeading = before;
     const inner = blocks
         || (node.inline ? wholeCardLink(!!href, () => inlineToTemplate(node.inline)) : "")
         || (description ? escapeTemplate(description) : "");
@@ -1610,7 +1631,7 @@ function standaloneCardToAstro(node, ctx) {
     // Icon renders inline before the title, a name or an image path, as in a card group
     const iconHtml = icon ? cardIconHtml(icon, title, ctx) : "";
     const titleHtml = title
-        ? `<h3 class="${CARD_TITLE_CLASS}">${escapeTemplate(title)}</h3>`
+        ? `<${tag} class="${CARD_TITLE_CLASS}">${escapeTemplate(title)}</${tag}>`
         : "";
     // A description and a body are both shown (the description used to be dropped when a body existed).
     const lead = blocks && description
@@ -1629,7 +1650,7 @@ function standaloneCardToAstro(node, ctx) {
         "title", "href", "description", "icon", "variant", "class", "tone",
     ]);
     if (href) {
-        return `<Card${classAttr}${passthrough}>\n<CardContent class="p-0">\n<a href="${escapeAttr(href)}" class="not-prose [text-decoration:none] text-foreground">\n${iconHtml}\n${titleHtml}\n${desc}\n</a>\n</CardContent>\n</Card>`;
+        return `<Card${classAttr}${passthrough}>\n<CardContent class="p-0">\n<a href="${escapeAttr(href)}" data-variant="card" class="[text-decoration:none] text-foreground">\n${iconHtml}\n${titleHtml}\n${desc}\n</a>\n</CardContent>\n</Card>`;
     }
     return `<Card${classAttr}${passthrough}>\n<CardContent class="p-0">\n${iconHtml}\n${titleHtml}\n${desc}\n</CardContent>\n</Card>`;
 }

package/dist/theme-css.js

@@ -90,21 +90,27 @@ export function generateGlobalCss() {
 @source inline("${buildVariantSafelist()}"); /* ASTRO-ONLY: variants, tones, theme scopes */
 
 /* Prose typography for rendered content.
-   Every element rule is guarded with :not(.dba-api *): API-reference
-   regions (ApiLayout root carries the dba-api marker) compose their own
-   typography from utility classes, and unguarded .docs-prose rules would
-   out-specify them. The guard lets mixed prose+endpoint pages (MDX
-   imports) keep full typography outside the cards. */
+   Every element rule is guarded with :not(.dba-api *, .not-prose, .not-prose *).
+   API-reference regions (ApiLayout root carries the dba-api marker) compose
+   their own typography from utility classes, and unguarded .docs-prose rules
+   would out-specify them (these rules are unlayered, so they beat every
+   utility). The guard lets mixed prose+endpoint pages (MDX imports) keep full
+   typography outside the cards. .not-prose means what it means in Tailwind
+   Typography: that element and everything inside it is UI, not prose. Only
+   the heading and link rules skipped it, and only the element itself, so a
+   search page's facet list and result list inside an article got bullets,
+   indents and underlines. A wrapper around AUTHORED content (a card group, an
+   API symbol) must therefore not carry it. */
 .docs-prose {
   line-height: 1.7;
 
   /* A heading that is part of a component (a card title: h3.not-prose) keeps the component look */
-  & h1:not(.dba-api *):not(.not-prose) { font-family: var(--font-heading); font-size: 2rem; font-weight: 700; margin-top: 0; margin-bottom: 1rem; line-height: 1.2; letter-spacing: -0.025em; }
-  & h2:not(.dba-api *):not(.not-prose) { font-family: var(--font-heading); font-size: 1.5rem; font-weight: 600; margin-top: 2.5rem; margin-bottom: 0.75rem; line-height: 1.3; border-bottom: 1px solid var(--border); padding-bottom: 0.5rem; letter-spacing: -0.015em; }
-  & h3:not(.dba-api *):not(.not-prose) { font-family: var(--font-heading); font-size: 1.25rem; font-weight: 600; margin-top: 2rem; margin-bottom: 0.5rem; line-height: 1.4; }
-  & h4:not(.dba-api *):not(.not-prose) { font-family: var(--font-heading); font-size: 1.1rem; font-weight: 600; margin-top: 1.5rem; margin-bottom: 0.5rem; }
+  & h1:not(.dba-api *, .not-prose, .not-prose *) { font-family: var(--font-heading); font-size: 2rem; font-weight: 700; margin-top: 0; margin-bottom: 1rem; line-height: 1.2; letter-spacing: -0.025em; }
+  & h2:not(.dba-api *, .not-prose, .not-prose *) { font-family: var(--font-heading); font-size: 1.5rem; font-weight: 600; margin-top: 2.5rem; margin-bottom: 0.75rem; line-height: 1.3; border-bottom: 1px solid var(--border); padding-bottom: 0.5rem; letter-spacing: -0.015em; }
+  & h3:not(.dba-api *, .not-prose, .not-prose *) { font-family: var(--font-heading); font-size: 1.25rem; font-weight: 600; margin-top: 2rem; margin-bottom: 0.5rem; line-height: 1.4; }
+  & h4:not(.dba-api *, .not-prose, .not-prose *) { font-family: var(--font-heading); font-size: 1.1rem; font-weight: 600; margin-top: 1.5rem; margin-bottom: 0.5rem; }
 
-  & p:not(.dba-api *) { margin-top: 0.75rem; margin-bottom: 0.75rem; }
+  & p:not(.dba-api *, .not-prose, .not-prose *) { margin-top: 0.75rem; margin-bottom: 0.75rem; }
 
   /* The :not([data-variant]) guard exempts anchors that ARE components. A
      link-button renders as an <a> carrying bg-primary + text-primary-foreground
@@ -116,48 +122,45 @@ export function generateGlobalCss() {
      (No backticks in this comment: the whole stylesheet is a template
      literal.) */
   /* Not a whole-card link (LinkCard, the video card: \`a.not-prose\`): its underline ran under every line of the card */
-  & a:not(.dba-api *):not([data-variant]):not(.not-prose) { color: var(--primary); text-decoration: underline; text-underline-offset: 2px; }
-  & a:hover:not(.dba-api *):not([data-variant]):not(.not-prose) { opacity: 0.8; }
+  & a:not(.dba-api *, .not-prose, .not-prose *):not([data-variant]) { color: var(--primary); text-decoration: underline; text-underline-offset: 2px; }
+  & a:hover:not(.dba-api *, .not-prose, .not-prose *):not([data-variant]) { opacity: 0.8; }
 
-  & strong:not(.dba-api *) { font-weight: 600; }
-  & code:not(.dba-api *) { font-size: 0.875em; padding: 0.15em 0.35em; border-radius: 0.25rem; background: var(--muted); font-family: var(--font-code, ui-monospace, monospace); }
-  & pre code:not(.dba-api *) { padding: 0; background: none; font-size: 1em; }
+  & strong:not(.dba-api *, .not-prose, .not-prose *) { font-weight: 600; }
+  & code:not(.dba-api *, .not-prose, .not-prose *) { font-size: 0.875em; padding: 0.15em 0.35em; border-radius: 0.25rem; background: var(--muted); font-family: var(--font-code, ui-monospace, monospace); }
+  & pre code:not(.dba-api *, .not-prose, .not-prose *) { padding: 0; background: none; font-size: 1em; }
 
   /* Spacing between consecutive block elements (code blocks, alerts, etc.) */
   & > * + * { margin-top: 0.75rem; }
-  & li > * + *:not(.dba-api *) { margin-top: 0.75rem; }
+  & li > * + *:not(.dba-api *, .not-prose *) { margin-top: 0.75rem; }
 
-  & ul:not(.dba-api *) { list-style: disc; padding-left: 1.5rem; margin: 0.75rem 0; }
+  & ul:not(.dba-api *, .not-prose, .not-prose *) { list-style: disc; padding-left: 1.5rem; margin: 0.75rem 0; }
   /* Not a step list, nor a list inside one: Steps.astro draws their numbers as circles, and this
      rule (one class and an element) outranked its .steps-list { list-style: none }, so each step
      showed its "2." beside its circle */
-  & ol:not(.dba-api *):not(.steps-list, .sub-steps-list, .steps-list ol) { list-style: decimal; padding-left: 1.5rem; margin: 0.75rem 0; }
-  & li:not(.dba-api *) { margin: 0.25rem 0; }
-  & li > ul:not(.dba-api *), & li > ol:not(.dba-api *) { margin: 0.25rem 0; }
-  /* A file tree draws its own folder and file icons (files/markup.ts): the list rules above gave it bullets too */
-  & [data-component="files"] ul:not(.dba-api *) { list-style: none; padding-left: 0; }
-  & [data-component="files"] li > ul:not(.dba-api *) { padding-left: 1rem; }
+  & ol:not(.dba-api *, .not-prose, .not-prose *):not(.steps-list, .sub-steps-list, .steps-list ol) { list-style: decimal; padding-left: 1.5rem; margin: 0.75rem 0; }
+  & li:not(.dba-api *, .not-prose, .not-prose *) { margin: 0.25rem 0; }
+  & li > ul:not(.dba-api *, .not-prose, .not-prose *), & li > ol:not(.dba-api *, .not-prose, .not-prose *) { margin: 0.25rem 0; }
 
-  & blockquote:not(.dba-api *) { border-left: 4px solid var(--border); padding-left: 1rem; color: var(--muted-foreground); font-style: italic; margin: 1rem 0; }
+  & blockquote:not(.dba-api *, .not-prose, .not-prose *) { border-left: 4px solid var(--border); padding-left: 1rem; color: var(--muted-foreground); font-style: italic; margin: 1rem 0; }
 
-  & hr:not(.dba-api *) { border: none; border-top: 1px solid var(--border); margin: 2rem 0; }
+  & hr:not(.dba-api *, .not-prose, .not-prose *) { border: none; border-top: 1px solid var(--border); margin: 2rem 0; }
 
-  & table:not(.dba-api *) { width: 100%; border-collapse: collapse; margin: 1rem 0; font-size: 0.875rem; }
-  & th:not(.dba-api *) { text-align: left; vertical-align: bottom; font-weight: 600; padding: 0.5rem; border-bottom: 2px solid var(--border); }
-  & td:not(.dba-api *) { padding: 0.5rem; vertical-align: top; border-bottom: 1px solid var(--border); }
+  & table:not(.dba-api *, .not-prose, .not-prose *) { width: 100%; border-collapse: collapse; margin: 1rem 0; font-size: 0.875rem; }
+  & th:not(.dba-api *, .not-prose, .not-prose *) { text-align: left; vertical-align: bottom; font-weight: 600; padding: 0.5rem; border-bottom: 2px solid var(--border); }
+  & td:not(.dba-api *, .not-prose, .not-prose *) { padding: 0.5rem; vertical-align: top; border-bottom: 1px solid var(--border); }
   /* A table's caption is its title, above it; the same for Table components and raw HTML tables */
-  & caption:not(.dba-api *) { caption-side: top; text-align: left; font-weight: 500; color: var(--foreground); padding-bottom: 0.5rem; }
+  & caption:not(.dba-api *, .not-prose, .not-prose *) { caption-side: top; text-align: left; font-weight: 500; color: var(--foreground); padding-bottom: 0.5rem; }
 
     /* Tailwind Preflight sets display: block on every img, which turns an
        INLINE icon into its own line and splits the sentence around it —
        AsciiDoc UI macros render mid-step and were breaking every procedure
        that used one. inline-block restores the flow and leaves a standalone
        image (the only child of its paragraph) looking exactly as before. */
-    & img:not(.dba-api *) { display: inline-block; max-width: 100%; border-radius: 0.5rem; }
+    & img:not(.dba-api *, .not-prose, .not-prose *) { display: inline-block; max-width: 100%; border-radius: 0.5rem; }
     /* A standalone image — the only child of its paragraph — keeps block
        layout, so the vertical rhythm and the absence of baseline descender
        space are exactly what they were before inline icons were fixed. */
-    & p > img:only-child:not(.dba-api *) { display: block; }
+    & p > img:only-child:not(.dba-api *, .not-prose, .not-prose *) { display: block; }
 
   & .heading-anchor { text-decoration: none; opacity: 0; margin-right: 0.25rem; transition: opacity 0.2s; }
   & h1:hover .heading-anchor, & h2:hover .heading-anchor, & h3:hover .heading-anchor, & h4:hover .heading-anchor { opacity: 0.4; }
@@ -166,19 +169,19 @@ export function generateGlobalCss() {
      callouts) is a <details> too, with its own border and spacing; it
      carries data-variant, and without the exclusion it got a second border
      and 1rem of padding around its title bar. */
-  & details:not(.dba-api *):not([data-variant]) { border: 1px solid var(--border); border-radius: 0.5rem; padding: 1rem; margin: 1rem 0; }
-  & summary:not(.dba-api *) { cursor: pointer; font-weight: 600; }
+  & details:not(.dba-api *, .not-prose, .not-prose *):not([data-variant]) { border: 1px solid var(--border); border-radius: 0.5rem; padding: 1rem; margin: 1rem 0; }
+  & summary:not(.dba-api *, .not-prose, .not-prose *) { cursor: pointer; font-weight: 600; }
 
   /* mark is emitted by the highlight directive AND can arrive as raw HTML
      from an importer. Without a rule here it renders as the browser default
      yellow, which clashes in light mode and is unreadable on a dark page
      (nothing declares color-scheme). Token-based so it follows the theme. */
-  & mark:not(.dba-api *) { background: var(--dsb-mark-bg, rgb(254 240 138 / 0.6)); color: inherit; border-radius: 0.125rem; padding: 0 0.125rem; }
-  &:where(.dark *) mark:not(.dba-api *), .dark & mark:not(.dba-api *) { background: var(--dsb-mark-bg-dark, rgb(234 179 8 / 0.3)); }
+  & mark:not(.dba-api *, .not-prose, .not-prose *) { background: var(--dsb-mark-bg, rgb(254 240 138 / 0.6)); color: inherit; border-radius: 0.125rem; padding: 0 0.125rem; }
+  &:where(.dark *) mark:not(.dba-api *, .not-prose, .not-prose *), .dark & mark:not(.dba-api *, .not-prose, .not-prose *) { background: var(--dsb-mark-bg-dark, rgb(234 179 8 / 0.3)); }
 
-  & dl:not(.dba-api *) { margin: 1rem 0; }
-  & dt:not(.dba-api *) { font-weight: 600; margin-top: 0.75rem; }
-  & dd:not(.dba-api *) { margin-left: 1.5rem; color: var(--muted-foreground); }
+  & dl:not(.dba-api *, .not-prose, .not-prose *) { margin: 1rem 0; }
+  & dt:not(.dba-api *, .not-prose, .not-prose *) { font-weight: 600; margin-top: 0.75rem; }
+  & dd:not(.dba-api *, .not-prose, .not-prose *) { margin-left: 1.5rem; color: var(--muted-foreground); }
 
   /* In-cell admonitions. Inside a raw HTML table cell nothing
      markdown-native works, so the AsciiDoc engine emits a neutral

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@dogsbay/format-astro",
-  "version": "0.2.0-beta.152",
+  "version": "0.2.0-beta.154",
   "description": "Astro format plugin for Dogsbay — export TreeNode[] to Astro component markup",
   "type": "module",
   "main": "dist/index.js",
@@ -32,13 +32,13 @@
   "license": "MIT",
   "dependencies": {
     "markdown-it": "^14.3.0",
-    "@dogsbay/format-dogsbay-md": "0.2.0-beta.152",
-    "@dogsbay/icons": "0.2.0-beta.152",
-    "@dogsbay/render-html": "0.2.0-beta.152",
-    "@dogsbay/serialize-core": "0.2.0-beta.152",
-    "@dogsbay/types": "0.2.0-beta.152",
-    "@dogsbay/site-files": "0.2.0-beta.152",
-    "@dogsbay/ui": "0.2.0-beta.152"
+    "@dogsbay/format-dogsbay-md": "0.2.0-beta.154",
+    "@dogsbay/icons": "0.2.0-beta.154",
+    "@dogsbay/serialize-core": "0.2.0-beta.154",
+    "@dogsbay/render-html": "0.2.0-beta.154",
+    "@dogsbay/site-files": "0.2.0-beta.154",
+    "@dogsbay/types": "0.2.0-beta.154",
+    "@dogsbay/ui": "0.2.0-beta.154"
   },
   "repository": {
     "type": "git",