@dogsbay/format-mdx 0.2.0-beta.1 → 0.2.0-beta.101

package/dist/adapter.d.ts

@@ -0,0 +1,159 @@
+/**
+ * MDX adapter — extension points for components and conventions a specific
+ * site or docs framework layers on top of *generic* MDX.
+ *
+ * Mirrors the proven Docusaurus adapter architecture
+ * (format-docusaurus/src/adapter.ts): the generic parser handles only the
+ * common Mintlify-style vocabulary (callouts, Tabs, Steps, Cards…); anything
+ * a framework or site invented is injected via an adapter and/or per-source
+ * declarative component config.
+ *
+ * Three layers (plans/format-fumadocs.md):
+ *   A. generic parser + open registry + never-drop `mdx-raw` + fidelity ledger
+ *   B. framework adapters (e.g. `fumadocs`)
+ *   C. per-docset declarative config (`as` / `props` / `children` / `handler`)
+ *
+ * Trust boundary: declarative config and built-in named handlers are safe
+ * everywhere (no subscriber-supplied code is ever executed). Arbitrary
+ * `handler:` JS modules are NOT supported here — a hosted updater must be
+ * able to run any docset config without executing its code.
+ */
+import type { TreeNode } from "@dogsbay/types";
+/** How a component's inner content is treated. */
+export type ChildrenPolicy = "blocks" | "code" | "raw" | "ignore";
+/** Context handed to function-form component handlers. */
+export interface ComponentHandlerContext {
+    /** Parse an MDX source fragment into TreeNode[] with the active registry. */
+    parseBlocks: (source: string) => TreeNode[];
+    /** Append a fidelity-ledger entry. */
+    ledger: (entry: Omit<MdxLedgerEntry, "file">) => void;
+    /**
+     * Same-file `export const` literals (name → raw source text). Lets
+     * handlers statically resolve `attr={identifier}` references — the
+     * common "data next to the component" MDX pattern. Never executed.
+     */
+    moduleData: Record<string, string>;
+}
+export interface ComponentMapping {
+    /** TreeNode type to produce (e.g. "callout", "tabs", "endpoint"). */
+    type: string;
+    /** Extract props from JSX attributes. Bare attributes arrive as "true". */
+    propsFromAttrs?: (attrs: Record<string, string>) => Record<string, unknown>;
+    /** Whether this component wraps children. */
+    container: boolean;
+    /** Strip this component entirely (recorded in the ledger). */
+    strip?: boolean;
+    /**
+     * How inner content is treated (default "blocks" for containers):
+     * - "blocks" — parsed as nested MDX blocks;
+     * - "code"   — kept as a single code node (a lone inner fence is
+     *              unwrapped and keeps its language);
+     * - "raw"    — kept verbatim as an `mdx-raw` child;
+     * - "ignore" — dropped (explicit, unlike the old silent swallow).
+     */
+    children?: ChildrenPolicy;
+    /**
+     * Function form — full control over the produced node(s). Return
+     * "preserve" to fall back to a byte-exact `mdx-raw` node (+ ledger entry);
+     * return null to drop the component (recorded as "stripped").
+     * Takes precedence over type/propsFromAttrs/children.
+     */
+    toNode?: (attrs: Record<string, string>, innerSource: string, ctx: ComponentHandlerContext) => TreeNode | TreeNode[] | "preserve" | null;
+}
+export interface MdxPreprocessContext {
+    /** Absolute path of the source file being parsed. */
+    filePath?: string;
+    /** Absolute path of the docs root directory. */
+    rootDir?: string;
+}
+export interface MdxAdapter {
+    /** Adapter name (e.g. "fumadocs"). */
+    name: string;
+    /** Raw-text rewrites applied BEFORE any parsing. */
+    preprocess?: (source: string, ctx: MdxPreprocessContext) => string;
+    /** Block-level component mappings, merged over the generic builtins. */
+    components?: Record<string, ComponentMapping>;
+    /** Tags treated as self-closing when the source omits the `/>`. */
+    selfClosingTags?: string[];
+    /**
+     * Inline component transformations applied to source text before parsing.
+     * Each entry: [regex, replacement string or function].
+     */
+    inlineTransforms?: [
+        RegExp,
+        string | ((substring: string, ...args: string[]) => string)
+    ][];
+}
+export interface MdxLedgerEntry {
+    /** Component tag name (e.g. "APIMethod"). */
+    component: string;
+    /**
+     * What happened:
+     * - "preserved" — kept byte-exact as `mdx-raw` (unknown or parse-failed);
+     * - "stripped"  — deliberately dropped by a mapping.
+     */
+    action: "preserved" | "stripped";
+    /** 1-based line in the (preamble-stripped) source. Best effort. */
+    line: number;
+    /** Source file, filled in by the importer. */
+    file?: string;
+}
+/**
+ * YAML-friendly component mapping — the per-source `mdx.components:` block.
+ * Purely declarative: safe to evaluate for untrusted docset configs.
+ */
+export interface MdxComponentConfig {
+    /** TreeNode type to produce (e.g. "table", "endpoint"). */
+    as?: string;
+    /**
+     * Prop mapping: node prop name → JSX attribute name.
+     * `{ title: label }` reads attribute `label` into prop `title`.
+     */
+    props?: Record<string, string>;
+    /** Children policy (see ComponentMapping.children). */
+    children?: ChildrenPolicy;
+    /**
+     * Built-in named handler (e.g. "api-method"). Resolved from the handler
+     * registry shipped with this package — never a user-supplied module.
+     */
+    handler?: string;
+    /**
+     * HTML template with `{attr}` placeholders (attribute values are
+     * HTML-escaped on interpolation). For simple presentational
+     * components: `'<p><a href="https://…/{url}">Open ↗</a></p>'`.
+     * Adds no capability MDX content doesn't already have (raw HTML).
+     */
+    html?: string;
+    /**
+     * Map a component whose data lives in a separate TS/TSX file
+     * (statically parsed, never executed). `file` resolves relative to
+     * the source directory. Requires the CLI import context (file I/O);
+     * plain compileComponentConfig callers must pass an extractResolver.
+     */
+    extract?: {
+        file: string;
+        export: string;
+        as: "cards" | "table";
+    };
+    /** Strip the component entirely. */
+    strip?: boolean;
+    /** Treat as self-closing. */
+    selfClosing?: boolean;
+}
+/**
+ * Compile declarative per-docset config into ComponentMapping entries.
+ *
+ * @param handlers registry of built-in named handlers (tag-independent);
+ *        unknown handler names throw — a config typo must not silently
+ *        degrade into the default mapping.
+ */
+export declare function compileComponentConfig(config: Record<string, MdxComponentConfig>, handlers?: Record<string, ComponentMapping>, 
+/**
+ * Resolver for `extract:` entries (needs file I/O — supplied by the
+ * CLI import layer). Without one, extract entries throw.
+ */
+extractResolver?: (spec: NonNullable<MdxComponentConfig["extract"]>, tag: string) => ComponentMapping): {
+    components: Record<string, ComponentMapping>;
+    selfClosingTags: string[];
+};
+//# sourceMappingURL=adapter.d.ts.map

package/dist/adapter.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"adapter.d.ts","sourceRoot":"","sources":["../src/adapter.ts"],"names":[],"mappings":"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"}

package/dist/adapter.js

@@ -0,0 +1,95 @@
+/**
+ * MDX adapter — extension points for components and conventions a specific
+ * site or docs framework layers on top of *generic* MDX.
+ *
+ * Mirrors the proven Docusaurus adapter architecture
+ * (format-docusaurus/src/adapter.ts): the generic parser handles only the
+ * common Mintlify-style vocabulary (callouts, Tabs, Steps, Cards…); anything
+ * a framework or site invented is injected via an adapter and/or per-source
+ * declarative component config.
+ *
+ * Three layers (plans/format-fumadocs.md):
+ *   A. generic parser + open registry + never-drop `mdx-raw` + fidelity ledger
+ *   B. framework adapters (e.g. `fumadocs`)
+ *   C. per-docset declarative config (`as` / `props` / `children` / `handler`)
+ *
+ * Trust boundary: declarative config and built-in named handlers are safe
+ * everywhere (no subscriber-supplied code is ever executed). Arbitrary
+ * `handler:` JS modules are NOT supported here — a hosted updater must be
+ * able to run any docset config without executing its code.
+ */
+/**
+ * Compile declarative per-docset config into ComponentMapping entries.
+ *
+ * @param handlers registry of built-in named handlers (tag-independent);
+ *        unknown handler names throw — a config typo must not silently
+ *        degrade into the default mapping.
+ */
+export function compileComponentConfig(config, handlers = {}, 
+/**
+ * Resolver for `extract:` entries (needs file I/O — supplied by the
+ * CLI import layer). Without one, extract entries throw.
+ */
+extractResolver) {
+    const components = {};
+    const selfClosingTags = [];
+    for (const [tag, entry] of Object.entries(config)) {
+        if (entry.selfClosing)
+            selfClosingTags.push(tag);
+        if (entry.extract) {
+            if (!extractResolver) {
+                throw new Error(`mdx component <${tag}> uses extract:, which requires the CLI ` +
+                    `import context (file access)`);
+            }
+            components[tag] = extractResolver(entry.extract, tag);
+            continue;
+        }
+        if (entry.html) {
+            const template = entry.html;
+            components[tag] = {
+                type: "html",
+                container: true,
+                toNode: (attrs) => ({
+                    type: "html",
+                    html: template.replace(/\{(\w+)\}/g, (_, name) => String(attrs[name] ?? "")
+                        .replace(/&/g, "&amp;")
+                        .replace(/</g, "&lt;")
+                        .replace(/>/g, "&gt;")
+                        .replace(/"/g, "&quot;")),
+                }),
+            };
+            continue;
+        }
+        if (entry.handler) {
+            const handler = handlers[entry.handler];
+            if (!handler) {
+                throw new Error(`Unknown mdx component handler "${entry.handler}" for <${tag}>. ` +
+                    `Available: ${Object.keys(handlers).join(", ") || "(none)"}`);
+            }
+            components[tag] = handler;
+            continue;
+        }
+        if (entry.strip) {
+            components[tag] = { type: "", container: true, strip: true };
+            continue;
+        }
+        const propsMap = entry.props;
+        components[tag] = {
+            type: entry.as ?? "",
+            container: true,
+            children: entry.children,
+            propsFromAttrs: propsMap
+                ? (attrs) => {
+                    const props = {};
+                    for (const [propName, attrName] of Object.entries(propsMap)) {
+                        if (attrs[attrName] !== undefined)
+                            props[propName] = attrs[attrName];
+                    }
+                    return props;
+                }
+                : undefined,
+        };
+    }
+    return { components, selfClosingTags };
+}
+//# sourceMappingURL=adapter.js.map

package/dist/adapter.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"adapter.js","sourceRoot":"","sources":["../src/adapter.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;GAmBG;AAwIH;;;;;;GAMG;AACH,MAAM,UAAU,sBAAsB,CACpC,MAA0C,EAC1C,WAA6C,EAAE;AAC/C;;;GAGG;AACH,eAGqB;IAErB,MAAM,UAAU,GAAqC,EAAE,CAAC;IACxD,MAAM,eAAe,GAAa,EAAE,CAAC;IAErC,KAAK,MAAM,CAAC,GAAG,EAAE,KAAK,CAAC,IAAI,MAAM,CAAC,OAAO,CAAC,MAAM,CAAC,EAAE,CAAC;QAClD,IAAI,KAAK,CAAC,WAAW;YAAE,eAAe,CAAC,IAAI,CAAC,GAAG,CAAC,CAAC;QAEjD,IAAI,KAAK,CAAC,OAAO,EAAE,CAAC;YAClB,IAAI,CAAC,eAAe,EAAE,CAAC;gBACrB,MAAM,IAAI,KAAK,CACb,kBAAkB,GAAG,0CAA0C;oBAC7D,8BAA8B,CACjC,CAAC;YACJ,CAAC;YACD,UAAU,CAAC,GAAG,CAAC,GAAG,eAAe,CAAC,KAAK,CAAC,OAAO,EAAE,GAAG,CAAC,CAAC;YACtD,SAAS;QACX,CAAC;QAED,IAAI,KAAK,CAAC,IAAI,EAAE,CAAC;YACf,MAAM,QAAQ,GAAG,KAAK,CAAC,IAAI,CAAC;YAC5B,UAAU,CAAC,GAAG,CAAC,GAAG;gBAChB,IAAI,EAAE,MAAM;gBACZ,SAAS,EAAE,IAAI;gBACf,MAAM,EAAE,CAAC,KAAK,EAAE,EAAE,CAAC,CAAC;oBAClB,IAAI,EAAE,MAAM;oBACZ,IAAI,EAAE,QAAQ,CAAC,OAAO,CAAC,YAAY,EAAE,CAAC,CAAC,EAAE,IAAY,EAAE,EAAE,CACvD,MAAM,CAAC,KAAK,CAAC,IAAI,CAAC,IAAI,EAAE,CAAC;yBACtB,OAAO,CAAC,IAAI,EAAE,OAAO,CAAC;yBACtB,OAAO,CAAC,IAAI,EAAE,MAAM,CAAC;yBACrB,OAAO,CAAC,IAAI,EAAE,MAAM,CAAC;yBACrB,OAAO,CAAC,IAAI,EAAE,QAAQ,CAAC,CAC3B;iBACF,CAAC;aACH,CAAC;YACF,SAAS;QACX,CAAC;QAED,IAAI,KAAK,CAAC,OAAO,EAAE,CAAC;YAClB,MAAM,OAAO,GAAG,QAAQ,CAAC,KAAK,CAAC,OAAO,CAAC,CAAC;YACxC,IAAI,CAAC,OAAO,EAAE,CAAC;gBACb,MAAM,IAAI,KAAK,CACb,kCAAkC,KAAK,CAAC,OAAO,UAAU,GAAG,KAAK;oBAC/D,cAAc,MAAM,CAAC,IAAI,CAAC,QAAQ,CAAC,CAAC,IAAI,CAAC,IAAI,CAAC,IAAI,QAAQ,EAAE,CAC/D,CAAC;YACJ,CAAC;YACD,UAAU,CAAC,GAAG,CAAC,GAAG,OAAO,CAAC;YAC1B,SAAS;QACX,CAAC;QAED,IAAI,KAAK,CAAC,KAAK,EAAE,CAAC;YAChB,UAAU,CAAC,GAAG,CAAC,GAAG,EAAE,IAAI,EAAE,EAAE,EAAE,SAAS,EAAE,IAAI,EAAE,KAAK,EAAE,IAAI,EAAE,CAAC;YAC7D,SAAS;QACX,CAAC;QAED,MAAM,QAAQ,GAAG,KAAK,CAAC,KAAK,CAAC;QAC7B,UAAU,CAAC,GAAG,CAAC,GAAG;YAChB,IAAI,EAAE,KAAK,CAAC,EAAE,IAAI,EAAE;YACpB,SAAS,EAAE,IAAI;YACf,QAAQ,EAAE,KAAK,CAAC,QAAQ;YACxB,cAAc,EAAE,QAAQ;gBACtB,CAAC,CAAC,CAAC,KAAK,EAAE,EAAE;oBACR,MAAM,KAAK,GAA4B,EAAE,CAAC;oBAC1C,KAAK,MAAM,CAAC,QAAQ,EAAE,QAAQ,CAAC,IAAI,MAAM,CAAC,OAAO,CAAC,QAAQ,CAAC,EAAE,CAAC;wBAC5D,IAAI,KAAK,CAAC,QAAQ,CAAC,KAAK,SAAS;4BAAE,KAAK,CAAC,QAAQ,CAAC,GAAG,KAAK,CAAC,QAAQ,CAAC,CAAC;oBACvE,CAAC;oBACD,OAAO,KAAK,CAAC;gBACf,CAAC;gBACH,CAAC,CAAC,SAAS;SACd,CAAC;IACJ,CAAC;IAED,OAAO,EAAE,UAAU,EAAE,eAAe,EAAE,CAAC;AACzC,CAAC"}

package/dist/cli.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"cli.d.ts","sourceRoot":"","sources":["../src/cli.ts"],"names":[],"mappings":"AAGA,OAAO,KAAK,EAAE,YAAY,EAAuB,MAAM,gBAAgB,CAAC;AAmIxE,eAAO,MAAM,MAAM,EAAE,YAQpB,CAAC"}
+{"version":3,"file":"cli.d.ts","sourceRoot":"","sources":["../src/cli.ts"],"names":[],"mappings":"AAGA,OAAO,KAAK,EAAE,YAAY,EAAiC,MAAM,gBAAgB,CAAC;AAialF,eAAO,MAAM,MAAM,EAAE,YAapB,CAAC"}

package/dist/cli.js

@@ -1,37 +1,181 @@
 import { existsSync, readFileSync, readdirSync, statSync } from "node:fs";
-import { join, relative } from "node:path";
+import { isAbsolute, join, relative } from "node:path";
 import YAML from "yaml";
 import { parseMeta } from "@dogsbay/types";
-import { mdxToTree, extractHeadings } from "./parse.js";
+import { parseMdx, extractHeadings } from "./parse.js";
+import { compileComponentConfig, } from "./adapter.js";
+import { MDX_BUILTIN_HANDLERS } from "./fumadocs.js";
+import { buildFumadocsNav, detectFumadocsDir } from "./meta-nav.js";
+import { buildMintlifyNav, detectMintlifyDir } from "./mintlify-nav.js";
+import { mintlifyOpenApiSpecRef, buildMintlifyEndpointMap, readOpenApiSpecSource, collectMintlifyOpenApiSpecRefs, collectMintlifyOpenApiNavPages, openApiPageKey, openApiPageSpecRef, } from "./mintlify-openapi.js";
+import { mintlifyAdapter } from "./mintlify.js";
+import { mintlifyRedirects } from "./mintlify-nav.js";
+import { extractNavFromTsxFile } from "./nav-extract.js";
+import { makeExtractMapping } from "./extract.js";
 /**
- * Detect a pulled MDX docs directory.
- *
- * Looks for nav.json (written by `dogsbay pull`) + at least one .md file.
+ * Detect an MDX docs directory. Two shapes:
+ * - a pulled site: nav.json (written by `dogsbay pull`) + .md files;
+ * - a Fumadocs content directory: meta.json + .mdx/.md pages.
  */
 function detectMdxDir(path) {
-    return (existsSync(join(path, "nav.json")) &&
-        existsSync(path) &&
-        hasMdFiles(path));
+    if (existsSync(join(path, "nav.json")) && hasMdFiles(path))
+        return true;
+    if (detectMintlifyDir(path))
+        return true;
+    return detectFumadocsDir(path);
 }
 function hasMdFiles(dir) {
     try {
         const entries = readdirSync(dir);
-        return entries.some((e) => e.endsWith(".md") && e !== "llms.txt");
+        return entries.some((e) => (e.endsWith(".md") || e.endsWith(".mdx")) && e !== "llms.txt");
     }
     catch {
         return false;
     }
 }
 /**
- * Import a directory of pulled MDX files into ExportPage[] + NavItem[].
+ * Import a directory of MDX files into ExportPage[] + NavItem[].
  */
 async function importMdxDir(source, opts) {
-    // Read nav.json
+    // Parse options: adapter instance + declarative per-source components.
+    const parseOpts = {};
+    if (opts.adapterInstance) {
+        parseOpts.adapter = opts.adapterInstance;
+    }
+    else if (detectMintlifyDir(source)) {
+        // A Mintlify CONFIG — not merely a file called `docs.json`, which TypeDoc
+        // also emits. `detectMintlifyDir` exists precisely to make that
+        // distinction (it requires `navigation`, `anchors`, or a mintlify
+        // `$schema`), and keying off bare file existence bypassed it: a Fumadocs
+        // corpus that happened to ship TypeDoc output got Mintlify's component map
+        // applied silently.
+        //
+        // Default the adapter instead of making the user pass `--adapter mintlify`
+        // to get their own components mapped.
+        //
+        // Without this, importing Mintlify's own docs left every <HeroCard>,
+        // <Update>, <ParamField> and <Expandable> unmapped: preserved as mdx-raw
+        // and rendered as CODE BLOCKS of their own JSX on the built site. The
+        // never-drop policy meant nothing was lost, but the page looked broken.
+        // An explicit `--adapter` still wins.
+        parseOpts.adapter = mintlifyAdapter;
+    }
+    // Redirects the source itself declares. A docs site links to its own old
+    // paths and relies on the live redirect; after import nothing serves it, so
+    // the link 404s unless it is rewritten here.
+    const linkRedirects = mintlifyRedirects(source);
+    if (Object.keys(linkRedirects).length > 0)
+        parseOpts.linkRedirects = linkRedirects;
+    if (opts.componentsConfig) {
+        const compiled = compileComponentConfig(opts.componentsConfig, MDX_BUILTIN_HANDLERS, 
+        // extract: data files resolve like sidebar files — absolute paths
+        // arrive pre-rebased (site build stages the source), relative ones
+        // resolve against the source dir (the convert path).
+        (spec) => makeExtractMapping(spec, (file) => isAbsolute(file) ? file : join(source, file)));
+        parseOpts.components = compiled.components;
+        parseOpts.selfClosingTags = compiled.selfClosingTags;
+    }
+    // Nav: hardcoded-page-tree extract > nav.json (pulled sites) >
+    // Fumadocs meta.json walk.
+    const hrefPrefix = typeof opts.hrefPrefix === "string" ? opts.hrefPrefix : "";
     const navPath = join(source, "nav.json");
-    const nav = JSON.parse(readFileSync(navPath, "utf-8"));
-    // Walk all .md files
+    let nav = null;
+    const sidebarExtract = opts.sidebarExtract;
+    if (sidebarExtract) {
+        // Absolute file paths arrive pre-resolved (the site-build path
+        // rebases them onto the ORIGINAL source dir — the staged copy the
+        // plugin sees can't reach ../ siblings); relative ones resolve
+        // against the source dir (the convert path).
+        const sidebarFile = isAbsolute(sidebarExtract.file)
+            ? sidebarExtract.file
+            : join(source, sidebarExtract.file);
+        nav = extractNavFromTsxFile(sidebarFile, {
+            exportName: sidebarExtract.export,
+            stripPrefix: sidebarExtract.stripPrefix,
+            hrefPrefix,
+        });
+        if (!nav) {
+            console.warn(`mdx: sidebar extraction from ${sidebarExtract.file} failed — ` +
+                `falling back to meta.json nav`);
+        }
+    }
+    if (!nav && existsSync(navPath)) {
+        nav = JSON.parse(readFileSync(navPath, "utf-8"));
+    }
+    // Mintlify source-pull: nav is the authoritative `docs.json` / `mint.json`.
+    if (!nav) {
+        nav = buildMintlifyNav(source, { hrefPrefix });
+    }
+    if (!nav) {
+        nav = buildFumadocsNav(source, { hrefPrefix });
+    }
+    // Mintlify OpenAPI pages: an `openapi: <method> <path>` frontmatter page has
+    // no body — its content is generated from the spec in docs.json (api.openapi).
+    // Resolve the spec once into a (method+path → endpoint node) map so those
+    // pages import as real endpoint pages instead of blank.
+    const specRef = mintlifyOpenApiSpecRef(source);
+    // Specs named by INDIVIDUAL PAGES (`openapi: "/openapi.json GET /x"`). A site
+    // whose docs.json declares no `api.openapi` still tells us, page by page,
+    // exactly which spec to read — Mintlify's own docs do precisely this, and
+    // ignoring it cost 100 pages their endpoint content (20 of them entirely
+    // blank) with the spec sitting in the repo root. Scanned up front so each
+    // distinct spec is parsed once, not per page.
+    const pageSpecRefs = new Set();
+    const preScan = walkMdFiles(source, source);
+    for (const { filePath } of preScan) {
+        const fm = extractFrontmatter(readFileSync(filePath, "utf-8"));
+        const ref = openApiPageSpecRef(source, fm?.openapi);
+        if (ref && ref !== specRef)
+            pageSpecRefs.add(ref);
+    }
+    // Preserve the ORIGINAL spec for exporters that consume one directly. The
+    // spec is a canonical source artifact; rebuilding it from endpoint TreeNodes
+    // is lossy, so pass the real thing through when we have it.
+    const allSpecRefs = collectMintlifyOpenApiSpecRefs(source, [...pageSpecRefs]);
+    if (allSpecRefs.length > 0) {
+        const preserved = [];
+        for (const ref of allSpecRefs) {
+            const spec = await readOpenApiSpecSource(ref);
+            if (spec) {
+                preserved.push({ ...spec, ref });
+            }
+            else {
+                // A failed fetch must NOT look like "this source had no spec" — that
+                // silently downgrades the export to lossy reconstruction and the
+                // ledger then reports the wrong reason.
+                console.warn(`  warning: could not read the OpenAPI spec at ${ref} — export will ` +
+                    `reconstruct it from endpoint nodes instead (lossy: $ref components, ` +
+                    `security schemes and callbacks are lost).`);
+            }
+        }
+        if (preserved.length > 0)
+            opts.sourceOpenApiSpecs = preserved;
+    }
+    const endpointResult = specRef
+        ? await buildMintlifyEndpointMap(specRef)
+        : { map: new Map(), loadError: null };
+    const endpointMap = endpointResult.map;
+    // One endpoint map per page-declared spec, keyed by resolved spec path.
+    const pageSpecMaps = new Map();
+    for (const ref of pageSpecRefs) {
+        const result = await buildMintlifyEndpointMap(ref);
+        if (result.loadError) {
+            console.warn(`  warning: failed to load OpenAPI spec at ${ref} (named by page ` +
+                `frontmatter): ${result.loadError} — those pages import without ` +
+                `endpoint content.`);
+        }
+        pageSpecMaps.set(ref, result.map);
+    }
+    if (endpointResult.loadError) {
+        console.warn(`  warning: failed to load OpenAPI spec from ${specRef}: ` +
+            `${endpointResult.loadError} — API pages import without endpoint content.`);
+    }
+    // Walk all .md/.mdx files
     const mdFiles = walkMdFiles(source, source);
     const pages = [];
+    const ledger = [];
+    let openApiResolved = 0;
+    let openApiMissed = 0;
     // Custom taxonomy names from dogsbay.config.yml's `taxonomies:` block.
     const taxonomyNames = Array.isArray(opts.taxonomyNames)
         ? opts.taxonomyNames
@@ -39,7 +183,34 @@ async function importMdxDir(source, opts) {
     for (const { filePath, slug } of mdFiles) {
         const content = readFileSync(filePath, "utf-8");
         const frontmatter = extractFrontmatter(content);
-        const tree = mdxToTree(content);
+        const result = parseMdx(content, {
+            ...parseOpts,
+            file: relative(source, filePath),
+            // Needed to resolve `import X from "/snippets/foo.mdx"` — Mintlify
+            // resolves a leading `/` against the DOCS ROOT, not the filesystem root.
+            rootDir: source,
+        });
+        let tree = result.tree;
+        ledger.push(...result.ledger);
+        // Mintlify OpenAPI page: append the spec-generated endpoint node. The MDX
+        // body (usually empty, sometimes an intro paragraph) renders before it.
+        const oaKey = openApiPageKey(frontmatter?.openapi);
+        if (oaKey) {
+            // The page's OWN spec wins when it names one — a site can reference
+            // several specs (mintlify-docs ships openapi.json, admin-openapi.json,
+            // analytics.openapi.json and discovery-openapi.json), so the config-level
+            // map is the fallback, not the authority.
+            const ownRef = openApiPageSpecRef(source, frontmatter?.openapi);
+            const endpoint = (ownRef ? pageSpecMaps.get(ownRef)?.get(oaKey) : undefined) ??
+                endpointMap.get(oaKey);
+            if (endpoint) {
+                tree = [...tree, ...endpoint];
+                openApiResolved++;
+            }
+            else {
+                openApiMissed++;
+            }
+        }
         const headings = extractHeadings(tree);
         // Extract title: prefer frontmatter, fall back to first h1
         const titleNode = tree.find((n) => n.type === "heading" && n.props?.level === 1);
@@ -49,6 +220,44 @@ async function importMdxDir(source, opts) {
         const meta = parseMeta(frontmatter, { slug, taxonomyNames });
         pages.push({ slug, title, tree, headings, frontmatter, meta });
     }
+    // Nav-referenced OpenAPI pages: `METHOD /path` nav strings under a container
+    // with an `openapi` spec exist in no .mdx file — generate them so the nav
+    // links resolve (ollama's "Endpoints" group). Their slugs match the nav hrefs
+    // (both via openApiRefSlug); skip any that collide with a real .mdx page.
+    const existingSlugs = new Set(pages.map((p) => p.slug));
+    const navOa = await collectMintlifyOpenApiNavPages(source);
+    let navOaAdded = 0;
+    for (const page of navOa.pages) {
+        if (existingSlugs.has(page.slug))
+            continue;
+        existingSlugs.add(page.slug);
+        pages.push(page);
+        navOaAdded++;
+    }
+    if (navOa.loadError && navOaAdded === 0) {
+        console.warn(`  warning: failed to load nav-referenced OpenAPI spec: ${navOa.loadError}`);
+    }
+    // Report OpenAPI page resolution — never silently leave API pages blank.
+    const totalOa = openApiResolved + navOaAdded;
+    if (totalOa > 0 || openApiMissed > 0) {
+        console.log(`  Mintlify OpenAPI: resolved ${totalOa} endpoint page(s)` +
+            (specRef ? ` from ${specRef}` : ""));
+    }
+    if (openApiMissed > 0) {
+        const cause = !specRef && pageSpecRefs.size === 0
+            ? " (no api.openapi spec found in docs.json/mint.json, and no page named its own spec)"
+            : endpointResult.loadError
+                ? " (the spec failed to load — see the warning above)"
+                : "";
+        console.warn(`  warning: ${openApiMissed} page(s) with \`openapi:\` frontmatter had no ` +
+            `matching operation in the spec${cause}` +
+            " — those pages import without endpoint content.");
+    }
+    // Fidelity ledger: expose programmatically; print with --report.
+    opts.importLedger = ledger;
+    if (opts.report && ledger.length > 0) {
+        printLedgerReport(ledger);
+    }
     // Attach metadata for exporters to consume
     const llmsTxtPath = join(source, "llms.txt");
     if (existsSync(llmsTxtPath)) {
@@ -60,6 +269,34 @@ async function importMdxDir(source, opts) {
     }
     return { pages, nav };
 }
+/**
+ * Print the fidelity ledger grouped by component: what was preserved
+ * as raw MDX (candidates for a component mapping) and what a mapping
+ * deliberately stripped. Mirrors the import-ditamap --report pattern.
+ */
+function printLedgerReport(ledger) {
+    const byComponent = new Map();
+    for (const entry of ledger) {
+        const key = `${entry.component}	${entry.action}`;
+        const agg = byComponent.get(key) ?? {
+            action: entry.action,
+            count: 0,
+            files: new Set(),
+        };
+        agg.count++;
+        if (entry.file)
+            agg.files.add(entry.file);
+        byComponent.set(key, agg);
+    }
+    console.log("\nMDX fidelity ledger:");
+    const sorted = [...byComponent.entries()].sort((a, b) => b[1].count - a[1].count);
+    for (const [key, agg] of sorted) {
+        const component = key.split("	")[0];
+        console.log(`  <${component}> ${agg.action} ×${agg.count} (${agg.files.size} file${agg.files.size === 1 ? "" : "s"})`);
+    }
+    console.log("  Preserved components survive byte-exact as raw MDX. Map them via an\n" +
+        "  adapter or the per-source mdx.components config to convert them.");
+}
 const FRONTMATTER_RE = /^---\n([\s\S]*?)\n---\n?/;
 /**
  * Lift YAML frontmatter from the raw markdown source. Returns
@@ -85,8 +322,8 @@ function extractFrontmatter(source) {
     }
 }
 /**
- * Recursively find all .md files in a directory.
- * Returns slug (relative path without .md) and absolute file path.
+ * Recursively find all .md/.mdx files in a directory.
+ * Returns slug (relative path without extension) and absolute file path.
  */
 function walkMdFiles(dir, root) {
     const results = [];
@@ -95,11 +332,19 @@ function walkMdFiles(dir, root) {
         const fullPath = join(dir, entry);
         const stat = statSync(fullPath);
         if (stat.isDirectory()) {
+            // Dot-directories are TOOLING, not documentation. Mintlify's own docs
+            // carry `.claude/skills/**/SKILL.md`, `.mintlify/AGENTS.md` and
+            // `.github/pull_request_template.md`; all 20 were imported as pages and
+            // landed in the exported vault as `CLAUDE.md`, `AGENTS.md` and
+            // `SKILL.md` beside the real docs. `node_modules` likewise.
+            if (entry.startsWith(".") || entry === "node_modules")
+                continue;
             results.push(...walkMdFiles(fullPath, root));
         }
-        else if (entry.endsWith(".md") && entry !== "llms.txt") {
+        else if ((entry.endsWith(".md") || entry.endsWith(".mdx")) &&
+            entry !== "llms.txt") {
             const rel = relative(root, fullPath);
-            const slug = rel.replace(/\.md$/, "").replace(/\\/g, "/");
+            const slug = rel.replace(/\.(md|mdx)$/, "").replace(/\\/g, "/");
             results.push({ filePath: fullPath, slug });
         }
     }
@@ -110,7 +355,12 @@ export const plugin = {
     canImport: true,
     canExport: false,
     detectSource: detectMdxDir,
-    importOptions: [],
+    importOptions: [
+        { flags: "--adapter <name>", description: "MDX framework adapter (e.g. fumadocs)" },
+        { flags: "--components <path>", description: "YAML/JSON file with declarative component mappings" },
+        { flags: "--sidebar <path[#export]>", description: "Statically extract a hand-written page tree" },
+        { flags: "--report", description: "Print the fidelity ledger (preserved/stripped components)" },
+    ],
     exportOptions: [],
     import: importMdxDir,
 };