@dogsbay/format-starlight 0.2.0-beta.11 → 0.2.0-beta.110

package/dist/adapters/cloudflare.js

@@ -143,18 +143,27 @@ function resolveWranglerConfig(source) {
                 toml = toml.replace(/^(\s*)(.*compatibility_date.*)/m, "$1# Set this to today's date\n$1$2");
                 jsonc = jsonc.replace(/^(\s*)(.*compatibility_date.*)/m, "$1// Set this to today's date\n$1$2");
             }
+            // A closing fence MUST be on its own line. It wasn't for the TOML
+            // half — `TOML.stringify` returns no trailing newline, so the fence
+            // was glued to the last config line (`remote = true```). The block
+            // then never closed and SWALLOWED THE REST OF THE PAGE: on
+            // ai-search/get-started/workers, everything after the binding config
+            // — prose, headings and three more components — became one giant code
+            // block. Normalising both halves means neither depends on what its
+            // serializer happens to append.
             const result = `<Tabs>
 <TabItem label="wrangler.jsonc">
 
 \`\`\`jsonc
-${jsonc}
+${jsonc.replace(/\s*$/, "")}
 \`\`\`
 
 </TabItem>
 <TabItem label="wrangler.toml">
 
 \`\`\`toml
-${toml}\`\`\`
+${toml.replace(/\s*$/, "")}
+\`\`\`
 
 </TabItem>
 </Tabs>`;
@@ -323,13 +332,34 @@ export const cloudflareAdapter = {
                 href: attrs.href,
             }),
         },
+        // Cloudflare's own alias: `export { default as LinkTitleCard } from
+        // "./components/cf/LinkCard.astro"` — the SAME component under a second
+        // name, used when the card wraps its description as children rather than
+        // passing it as an attribute. Unmapped, it leaked its opening tag onto the
+        // page as visible text (`<LinkTitleCard title="Get started" href=…`) and
+        // its body rendered as a code block. 300 uses across the corpus.
+        LinkTitleCard: {
+            type: "card",
+            container: true,
+            propsFromAttrs: (attrs) => ({
+                title: attrs.title || "",
+                href: attrs.href,
+                icon: attrs.icon,
+            }),
+        },
         RelatedProduct: {
             type: "card",
             container: true,
             propsFromAttrs: (attrs) => ({
                 title: attrs.header || "",
                 href: attrs.href,
-                icon: attrs.product ? `icons/${attrs.product}.svg` : undefined,
+                // `/_assets/icons/…` — the mount convention, so the file the importer
+                // copies is the file this reference names. It used to be a bare
+                // `icons/x.svg`, which existed in neither output: Astro's <Icon> takes
+                // a registry NAME and silently rendered nothing, and Obsidian built an
+                // <img> against a vault path with no file behind it, so every related
+                // product showed a broken image with its title stretched down the page.
+                icon: attrs.product ? `/_assets/icons/${attrs.product}.svg` : undefined,
             }),
         },
         Description: {
@@ -414,6 +444,20 @@ export const cloudflareAdapter = {
         // <Plan type="all" /> → **Available on all plans**
         [/<Plan\s+type="all"\s*\/?>/g, "**Available on all plans**"],
         [/<Plan\s+type="([^"]*)"\s*\/?>/g, "**$1 plan**"],
+        // <Type text="string" /> → `string`
+        //
+        // An inline type-annotation badge next to a parameter or method — the
+        // component renders it as a styled <code>, so inline code is the faithful
+        // mapping, not an approximation. 249 uses in the AI Search partials alone
+        // (`string` ×93, `boolean` ×38, `object` ×28), all inside API reference
+        // parameter lists where the type IS the content.
+        [/<Type\s+text="([^"]*)"\s*\/>/g, "`$1`"],
+        // <MetaInfo text="optional" /> → optional
+        //
+        // The companion annotation: "optional", "default: 10", a units hint. It
+        // was being DELETED, which reads as though every parameter is required.
+        // The component is a muted inline span, so plain text is the mapping.
+        [/<MetaInfo\s+text="([^"]*)"\s*\/>/g, "$1"],
         // <InlineBadge ... /> → strip
         [/<InlineBadge\s[^>]*\/>/g, ""],
         // Fallback strip for self-closing components that may appear deeply indented
@@ -422,7 +466,7 @@ export const cloudflareAdapter = {
         [/<AutoconfigDiagram[\s\S]*?\/>/g, ""],
         [/<GitHubCode\s[^>]*\/>/g, ""],
         [/<ResourcesBySelector[\s\S]*?\/>/g, ""],
-        [/<MetaInfo\s[^>]*\/>/g, ""],
+        [/<MetaInfo\s[^>]*\/>/g, ""], // fallback: forms with no `text` attribute
         [/<DirectoryListing[\s\S]*?\/>/g, ""],
         [/<ExternalResources\s[^>]*\/>/g, ""],
         [/<YouTubeVideos\s[^>]*\/>/g, ""],

package/dist/cli.d.ts

@@ -1,2 +1,4 @@
 import type { FormatPlugin } from "@dogsbay/types";
+import type { SiteAdapter } from "./adapter.js";
+export declare const STARLIGHT_ADAPTERS: Record<string, SiteAdapter>;
 export declare const plugin: FormatPlugin;

package/dist/cli.js

@@ -5,9 +5,10 @@ import { starlightToTree as starlightToTreeLegacy, extractFrontmatter } from "./
 import { starlightToTree as starlightToTreeMdx } from "./parse-mdx.js";
 import { cloudflareAdapter } from "./adapters/cloudflare.js";
 import { buildNavFromDirectory, buildNavFromConfig } from "./nav.js";
-const ADAPTERS = {
+export const STARLIGHT_ADAPTERS = {
     cloudflare: cloudflareAdapter,
 };
+const ADAPTERS = STARLIGHT_ADAPTERS;
 /**
  * Detect if a directory contains a Starlight docs source.
  *
@@ -136,9 +137,96 @@ async function importStarlight(source, opts) {
     if (opts.partialsDir) {
         partialsDir = opts.partialsDir;
     }
+    // Where the images live. Found the same way as partialsDir, because it is
+    // the same Astro layout: `src/content/docs` and `src/assets` are siblings
+    // under `src/`.
+    //
+    // Without this the conversion emitted `/_assets/images/x.png` refs and
+    // nothing ever copied a file there — every local image on a converted site
+    // was a 404. The reference survived and the file did not, which is why a
+    // page count, a retention score and a clean exit all looked fine.
+    let assetsDir;
+    searchDir = docsDir;
+    for (let depth = 0; depth < 10; depth++) {
+        const candidate = join(searchDir, "src", "assets");
+        if (existsSync(candidate)) {
+            assetsDir = candidate;
+            break;
+        }
+        const sibling = join(dirname(searchDir), "assets");
+        if (existsSync(sibling)) {
+            assetsDir = sibling;
+            break;
+        }
+        const parent = dirname(searchDir);
+        if (parent === searchDir)
+            break;
+        searchDir = parent;
+    }
+    // Product/brand icons, mounted under `_assets/icons` to match the refs the
+    // adapters emit for them.
+    let iconsDir;
+    searchDir = docsDir;
+    for (let depth = 0; depth < 10; depth++) {
+        const candidate = join(searchDir, "src", "icons");
+        if (existsSync(candidate)) {
+            iconsDir = candidate;
+            break;
+        }
+        const parent = dirname(searchDir);
+        if (parent === searchDir)
+            break;
+        searchDir = parent;
+    }
+    // Component sources, for recovering an accessible description from a
+    // component we cannot render. Same sibling layout as assets and partials.
+    let componentsDir;
+    searchDir = docsDir;
+    for (let depth = 0; depth < 10; depth++) {
+        const candidate = join(searchDir, "src", "components");
+        if (existsSync(candidate)) {
+            componentsDir = candidate;
+            break;
+        }
+        const parent = dirname(searchDir);
+        if (parent === searchDir)
+            break;
+        searchDir = parent;
+    }
+    /**
+     * The `aria-label` (or `<figcaption>`) a component declares about itself.
+     *
+     * Cloudflare's diagrams are Astro components — inline SVG, a web component,
+     * CSS animation — with no image file to carry across. But their `aria-label`
+     * is a full description written by their docs team, and it is the
+     * information the diagram exists to convey. Recovering it turns a silent
+     * hole into a described placeholder; nothing else about the component can
+     * survive a conversion to markdown.
+     */
+    const describeComponent = (tag) => {
+        if (!componentsDir)
+            return undefined;
+        const file = join(componentsDir, `${tag}.astro`);
+        if (!existsSync(file))
+            return undefined;
+        const source = readFileSync(file, "utf-8");
+        const aria = source.match(/aria-label="([^"]{20,})"/);
+        if (aria)
+            return aria[1].replace(/\s+/g, " ").trim();
+        const caption = source.match(/<figcaption[^>]*>([^<]{20,})<\/figcaption>/);
+        return caption ? caption[1].replace(/\s+/g, " ").trim() : undefined;
+    };
     // Parse all pages
     const mdxFiles = walkMdxFiles(docsDir, docsDir);
     const pages = [];
+    /** Components no builtin or adapter mapping claimed. */
+    const dropped = new Map();
+    const record = (tag, slug) => {
+        const entry = dropped.get(tag) ?? { count: 0, pages: new Set() };
+        entry.count++;
+        entry.pages.add(slug);
+        dropped.set(tag, entry);
+    };
     // Custom taxonomy names from dogsbay.config.yml's `taxonomies:` block
     // (threaded through cli's import-content.ts).
     const taxonomyNames = Array.isArray(opts.taxonomyNames)
@@ -151,7 +239,24 @@ async function importStarlight(source, opts) {
         // Fall back to legacy regex parser with --legacy-parser flag
         const useLegacy = opts.legacyParser === true;
         const starlightToTree = useLegacy ? starlightToTreeLegacy : starlightToTreeMdx;
-        const tree = starlightToTree(body, { adapter, partialsDir });
+        const tree = starlightToTree(body, {
+            adapter,
+            partialsDir,
+            onDrop: (tag) => record(tag, slug),
+            describeComponent,
+        });
+        // Catch what the callback cannot: a component nested inside a MAPPED
+        // container is not dropped, it LEAKS — its opening tag lands in the page
+        // as visible text and its body often becomes a code block, because nothing
+        // claimed the block. `<LinkTitleCard>` inside `<CardGrid>` did exactly
+        // that on Cloudflare's AI Search overview while the drop warning stayed
+        // silent.
+        //
+        // Scanning the finished tree catches every route into the output, present
+        // and future, in one place. `code` nodes are skipped: a code sample
+        // containing `<Response>` is content, not a leak.
+        for (const tag of leakedComponentTags(tree))
+            record(tag, slug);
         // Extract headings from tree
         const headings = tree
             .filter((n) => n.type === "heading")
@@ -215,16 +320,85 @@ async function importStarlight(source, opts) {
             opts.siteName = indexPage.title;
         }
     }
-    return { pages, nav };
+    // Say what was dropped, loudly and countably.
+    //
+    // A component nothing claimed is CONTENT THAT IS NOT ON THE PAGE — the
+    // Cloudflare AI Search overview lost its architecture diagram this way, and
+    // the only way anyone found out was comparing the converted page with the
+    // live one by eye. There is no ledger on this path, so the warning IS the
+    // report: it names each tag, how many times it appeared and how many pages
+    // it touched, so `convert … 2>&1 | grep "dropped"` answers "how much of this
+    // corpus does this affect" without reading any output files.
+    if (dropped.size > 0) {
+        const rows = [...dropped.entries()]
+            .sort((a, b) => b[1].count - a[1].count)
+            .map(([tag, d]) => `    <${tag}> ×${d.count} on ${d.pages.size} page(s): ${[...d.pages].slice(0, 3).join(", ")}${d.pages.size > 3 ? ", …" : ""}`);
+        const total = [...dropped.values()].reduce((n, d) => n + d.count, 0);
+        console.warn(`warning: ${total} unmapped component(s) — dropped, or leaked into the ` +
+            `page as literal text:\n${rows.join("\n")}\n` +
+            `  Map them with an adapter, or accept the loss knowingly.`);
+    }
+    return {
+        pages,
+        nav,
+        // Contents land in `public/_assets/`, matching the `/_assets/…` refs the
+        // parser now emits for the `~/assets/` alias.
+        ...(assetsDir || iconsDir
+            ? {
+                assetMounts: [
+                    ...(assetsDir ? [{ dir: assetsDir }] : []),
+                    ...(iconsDir ? [{ dir: iconsDir, into: "icons" }] : []),
+                ],
+            }
+            : {}),
+    };
+}
+/**
+ * Component tags left as literal text/HTML in a finished tree.
+ *
+ * A CamelCase tag only — `<ACCOUNT_ID>` and `<API_TOKEN>` are placeholders the
+ * docs write on purpose, and flagging those would bury the real signal.
+ */
+function leakedComponentTags(nodes) {
+    const found = [];
+    const scan = (list) => {
+        for (const node of list) {
+            if (node.type === "code" || node.type === "diagram")
+                continue;
+            for (const text of [node.html, ...(node.inline ?? []).map((i) => i.text)]) {
+                if (typeof text !== "string")
+                    continue;
+                // `</?` — a leak is often only the CLOSING tag, when the opener was
+                // consumed by the container above it but the closer had nothing to
+                // pair with. Matching openers alone missed exactly that case.
+                for (const m of text.matchAll(/<\/?([A-Z][a-z0-9]+[A-Za-z0-9]*)[\s/>]/g))
+                    found.push(m[1]);
+            }
+            if (node.children)
+                scan(node.children);
+        }
+    };
+    scan(nodes);
+    return found;
 }
 export const plugin = {
     name: "starlight",
     canImport: true,
     canExport: false,
     detectSource: detectStarlightSource,
-    exportOptions: [
-        { flags: "--adapter <name>", description: "Site adapter for custom components (e.g. cloudflare)" },
+    // importOptions, not exportOptions: this plugin declares `canExport: false`,
+    // so an export-side declaration described a flag on a command that does not
+    // exist — and `convert`'s "unusable flag" warning reads the IMPORT list, so
+    // `--adapter cloudflare` was reported as ignored while being consumed. That
+    // warning is load-bearing on this corpus: the adapter is the difference
+    // between every `<Render>` partial resolving and none of them.
+    importOptions: [
+        {
+            flags: "--adapter <name>",
+            description: `Site adapter for custom components (${Object.keys(STARLIGHT_ADAPTERS).join(", ")})`,
+        },
     ],
+    exportOptions: [],
     async import(source, opts) {
         return importStarlight(source, opts);
     },

package/dist/parse-mdx.d.ts

@@ -18,5 +18,28 @@ export interface ParseOptions {
     adapter?: SiteAdapter;
     /** Directory containing partial MDX files for <Render> resolution */
     partialsDir?: string;
+    /**
+     * Called with the tag name of every component DROPPED from the output —
+     * one that no builtin and no adapter mapping claimed.
+     *
+     * A dropped component is content that is not on the page. Cloudflare's
+     * `<AiSearchOverviewDiagram />` is the architecture diagram at the top of
+     * the AI Search overview; it vanished with no trace, and the only way to
+     * find out was to compare the converted page against the live one by eye.
+     * The importer knows at the moment it happens — this is how it says so.
+     */
+    onDrop?: (tag: string) => void;
+    /**
+     * Accessible description for a component we cannot render, if one can be
+     * found — used to leave a described placeholder instead of a hole.
+     *
+     * Cloudflare's diagrams are 478-line Astro components: inline SVG, a web
+     * component and CSS animation, with no image file anywhere. Nothing can
+     * convert that. But each carries an `aria-label` written by their docs team
+     * ("AI Search is a managed search primitive: you upload or connect your
+     * content…"), which IS the information the diagram conveys — and it was
+     * being thrown away with the markup.
+     */
+    describeComponent?: (tag: string) => string | undefined;
 }
 export declare function starlightToTree(source: string, options?: ParseOptions): TreeNode[];

package/dist/parse-mdx.js

@@ -105,10 +105,21 @@ function applyInlineTransforms(source, adapter) {
     return result;
 }
 /**
- * Rewrite ~/assets/ Vite alias to relative path.
+ * Rewrite the `~/assets/` Vite alias to the `/_assets/` mount convention.
+ *
+ * It used to produce a bare relative `assets/…`, which resolves to nothing:
+ * the page lives at `/ai-search/get-started/workers`, so a relative
+ * `assets/images/x.png` is looked for under that directory, and no exporter
+ * ever put a file there. Every local image on a converted Starlight site was a
+ * 404 — the reference survived the conversion and the file did not.
+ *
+ * `/_assets/…` is the repo-wide convention (see `assetMounts` in
+ * format-astro's project emitter): a mounted directory's CONTENTS land in
+ * `public/_assets/`, and importers rewrite refs to match — the same thing the
+ * Docusaurus importer does with a `static/` dir.
  */
 function rewriteAssetPaths(source) {
-    return source.replace(/~\/assets\//g, "assets/");
+    return source.replace(/~\/assets\//g, "/_assets/");
 }
 /**
  * Convert Starlight :::note / :::caution / :::tip / :::danger directives
@@ -149,7 +160,7 @@ function convertDirectives(source) {
  * Convert markdown-it tokens (including jsx_* tokens) to TreeNode[].
  * This replaces both segmentsToTree and tokensToTree from the old parser.
  */
-function tokensToTree(tokens, componentMap) {
+function tokensToTree(tokens, componentMap, onDrop, describeComponent) {
     const tree = [];
     let i = 0;
     while (i < tokens.length) {
@@ -327,7 +338,7 @@ function tokensToTree(tokens, componentMap) {
             const children = [];
             i++;
             while (i < tokens.length && tokens[i].type !== "blockquote_close") {
-                const nested = tokensToTree(tokens.slice(i, i + 1), componentMap);
+                const nested = tokensToTree(tokens.slice(i, i + 1), componentMap, onDrop, describeComponent);
                 children.push(...nested);
                 i++;
             }
@@ -339,7 +350,22 @@ function tokensToTree(tokens, componentMap) {
             // Check if this is a leftover JSX component that wasn't caught
             const trimmed = token.content.trim();
             if (trimmed.match(/^<[A-Z]/)) {
-                // Likely a JSX component — skip it (already handled or unrecognized)
+                // A JSX component nothing claimed. Dropping it is the existing
+                // behaviour; reporting it is new — silence here is what let five
+                // diagrams disappear from a converted section unnoticed.
+                const tag = trimmed.match(/^<([A-Za-z0-9]+)/)?.[1] ?? "unknown";
+                const description = describeComponent?.(tag);
+                if (description) {
+                    // Keep the MEANING even though the markup cannot travel.
+                    tree.push({
+                        type: "callout",
+                        props: { variant: "note", title: "Diagram" },
+                        children: [{ type: "paragraph", inline: [{ type: "text", text: description }] }],
+                    });
+                }
+                else {
+                    onDrop?.(tag);
+                }
                 i++;
                 continue;
             }
@@ -518,6 +544,8 @@ function groupConsecutiveCards(tree) {
 }
 export function starlightToTree(source, options) {
     const adapter = options?.adapter;
+    const onDrop = options?.onDrop;
+    const describeComponent = options?.describeComponent;
     const { components, selfClosing, map: componentMap } = buildComponentMap(adapter);
     // Strip frontmatter block before parsing. Without this, markdown-it sees
     // `---...---` as thematic-break + paragraph + thematic-break, which leaks the
@@ -548,7 +576,7 @@ export function starlightToTree(source, options) {
     // Parse into tokens (including jsx_* tokens)
     const tokens = md.parse(cleaned, {});
     // Convert tokens to tree
-    const tree = tokensToTree(tokens, componentMap);
+    const tree = tokensToTree(tokens, componentMap, onDrop, describeComponent);
     const unwrapped = unwrapStepsOrderedList(tree);
     return groupConsecutiveCards(unwrapped);
 }

package/dist/parse.js

@@ -140,11 +140,13 @@ function buildComponentMap(adapter) {
 function stripImports(source) {
     // Strip single-line imports: import { X } from "y";
     // Strip multi-line imports: import {\n  X,\n  Y,\n} from "y";
-    // Rewrite ~/assets/ Vite alias to relative assets/ path
+    // Rewrite the ~/assets/ Vite alias to the `/_assets/` mount convention —
+    // see the note on rewriteAssetPaths in parse-mdx.ts. A bare relative
+    // `assets/…` resolved against the page's own directory and 404'd.
     return source
         .replace(/^import\s+\{[^}]*\}\s+from\s+["'][^"']*["']\s*;?\s*$/gm, "")
         .replace(/^import\s+\{[\s\S]*?\}\s+from\s+["'][^"']*["']\s*;?\s*$/gm, "")
-        .replace(/~\/assets\//g, "assets/")
+        .replace(/~\/assets\//g, "/_assets/")
         .replace(/\{\/\*[\s\S]*?\*\/\}/g, "")
         .replace(/\n{3,}/g, "\n\n");
 }

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@dogsbay/format-starlight",
-  "version": "0.2.0-beta.11",
+  "version": "0.2.0-beta.110",
   "description": "Starlight MDX importer for Dogsbay — converts Starlight sources (with JSX components, Render partials, and adapter-specific extensions) into TreeNode[]",
   "type": "module",
   "exports": {
@@ -15,16 +15,16 @@
     "@iarna/toml": "^2.2.5",
     "gray-matter": "^4.0.3",
     "jsonc-parser": "^3.3.1",
-    "markdown-it": "^14.1.0",
-    "@dogsbay/markdown-it-mdx-jsx": "0.2.0-beta.11",
-    "@dogsbay/types": "0.2.0-beta.11"
+    "markdown-it": "^14.3.0",
+    "@dogsbay/markdown-it-mdx-jsx": "0.2.0-beta.110",
+    "@dogsbay/types": "0.2.0-beta.110"
   },
   "devDependencies": {
     "@types/iarna__toml": "^2.0.5",
     "@types/markdown-it": "^14.1.2",
-    "@types/node": "^22.0.0",
-    "typescript": "^5.8.0",
-    "vitest": "^3.2.0"
+    "@types/node": "^22.20.1",
+    "typescript": "^5.9.3",
+    "vitest": "^4.1.10"
   },
   "license": "MIT",
   "repository": {