@dogsbay/format-mdx 0.2.0-beta.15 → 0.2.0-beta.150

package/dist/mintlify-openapi.js

@@ -0,0 +1,362 @@
+/**
+ * Mintlify OpenAPI page generation.
+ *
+ * A Mintlify API-reference page is often just frontmatter — no body:
+ *
+ *   ---
+ *   openapi: post /partners/ban
+ *   sidebarTitle: Ban partner
+ *   ---
+ *
+ * The page content (endpoint card, params, request/response) is generated by
+ * Mintlify from the OpenAPI spec declared in `docs.json` (`api.openapi`, a URL
+ * or a local file). Without resolving that directive, every such page imports
+ * blank. This module reads the spec once and hands back the `endpoint` TreeNode
+ * for a given `METHOD path`, reusing `@dogsbay/format-openapi` (which already
+ * maps operations to endpoint nodes the Astro serializer renders as full API
+ * pages).
+ */
+import { existsSync, readFileSync, realpathSync } from "node:fs";
+import { join, resolve as resolvePath, dirname, basename, sep } from "node:path";
+import { parseOpenApiSpec } from "@dogsbay/format-openapi";
+const HTTP_METHODS = new Set([
+    "get",
+    "post",
+    "put",
+    "patch",
+    "delete",
+    "head",
+    "options",
+    "trace",
+]);
+/**
+ * The OpenAPI spec reference declared in a Mintlify config, or null. Reads
+ * `docs.json` / `mint.json` `api.openapi` (string, or first of an array) and the
+ * legacy top-level `openapi`. Only an `http(s)://` value is a URL; everything
+ * else — including a ROOT-relative path like `/api-reference/openapi.json`,
+ * which Mintlify resolves against the docs root, not the filesystem root — is
+ * resolved against `source`.
+ */
+export function mintlifyOpenApiSpecRef(source) {
+    const config = readConfig(source);
+    if (!config)
+        return null;
+    const ref = firstString(config.api?.openapi) ?? firstString(config.openapi) ?? null;
+    return ref ? resolveSpecRef(source, ref) : null;
+}
+/** Is `abs` inside `root` once symlinks are resolved? Separator-aware. */
+function withinRoot(abs, root) {
+    const real = (p) => {
+        try {
+            return realpathSync(p);
+        }
+        catch {
+            const parent = dirname(p);
+            return parent === p ? p : join(real(parent), basename(p));
+        }
+    };
+    const realRoot = real(resolvePath(root));
+    const realAbs = real(resolvePath(abs));
+    return realAbs === realRoot || realAbs.startsWith(realRoot + sep);
+}
+/**
+ * A spec ref → a URL, a source-relative filesystem path, or null when it is
+ * not allowed.
+ *
+ * Two refusals, both silent-by-default before:
+ *
+ *  - **Escaping the corpus.** `join(source, ref.replace(/^\//, ""))` strips a
+ *    leading slash but leaves `../` intact, so `openapi: "/../../secrets.json
+ *    GET /x"` read a file outside the docs root and put its contents into the
+ *    imported page. The check now compares realpaths and requires a separator,
+ *    matching the include resolver in `cli/src/commands/convert.ts`.
+ *  - **A page naming a URL.** Only a config-declared spec may be fetched. A
+ *    page-declared `https://…` made the converter issue a request from
+ *    wherever it runs — a CI runner or a hosted service sits inside a network
+ *    the repo's author cannot otherwise reach.
+ */
+function resolveSpecRef(source, ref, origin = "config") {
+    if (/^https?:\/\//.test(ref)) {
+        if (origin === "page") {
+            console.warn(`  warning: ignoring OpenAPI spec URL declared in page frontmatter ` +
+                `(${ref}) — only docs.json/mint.json may name a remote spec.`);
+            return null;
+        }
+        return ref;
+    }
+    const abs = join(source, ref.replace(/^\//, ""));
+    if (!withinRoot(abs, source)) {
+        console.warn(`  warning: ignoring OpenAPI spec path that escapes the docs root (${ref}).`);
+        return null;
+    }
+    return abs;
+}
+/**
+ * Fetch the raw spec document, unparsed.
+ *
+ * An OpenAPI spec is a CANONICAL SOURCE ARTIFACT, not prose: round-tripping it
+ * through the TreeNode IR is lossy by construction ($ref/component schemas
+ * inline, security schemes and callbacks vanish). Exporters that can consume a
+ * spec directly should pass THIS through rather than rebuild it from endpoint
+ * nodes. Returns null when the spec cannot be read.
+ */
+export async function readOpenApiSpecSource(specRef) {
+    try {
+        let text;
+        if (/^https?:\/\//.test(specRef)) {
+            const res = await fetch(specRef, { signal: AbortSignal.timeout(30_000) });
+            if (!res.ok)
+                return null;
+            text = await res.text();
+        }
+        else {
+            text = readFileSync(specRef, "utf-8");
+        }
+        const base = specRef.split(/[?#]/)[0].split("/").pop() || "openapi";
+        const filename = /\.(json|ya?ml)$/i.test(base)
+            ? base
+            : `${base}.${text.trimStart().startsWith("{") ? "json" : "yaml"}`;
+        return { text, filename };
+    }
+    catch {
+        return null;
+    }
+}
+/**
+ * Parse a spec into an endpoint map. A fetch/parse error must degrade to blank
+ * pages (never crash the import), but is reported via `loadError` rather than
+ * silently swallowed.
+ */
+export async function buildMintlifyEndpointMap(specRef) {
+    const map = new Map();
+    const titles = new Map();
+    try {
+        const { pages } = await parseOpenApiSpec(specRef);
+        for (const page of pages) {
+            const ep = page.tree.find((n) => n.type === "endpoint");
+            if (!ep)
+                continue;
+            const method = String(ep.props?.method ?? "").toLowerCase();
+            const path = String(ep.props?.path ?? "");
+            if (method && path) {
+                map.set(`${method} ${path}`, [ep]);
+                titles.set(`${method} ${path}`, page.title);
+            }
+        }
+        return { map, titles, loadError: null };
+    }
+    catch (err) {
+        return { map, titles, loadError: err instanceof Error ? err.message : String(err) };
+    }
+}
+/**
+ * Normalise a page's `openapi` frontmatter value to a map key, or null when the
+ * page is not an OpenAPI page. Accepts `"post /partners/ban"` (method + path);
+ * a leading named-spec token (`"api POST /x"`) is tolerated by taking the last
+ * two whitespace-separated tokens.
+ */
+export function openApiPageKey(value) {
+    if (typeof value !== "string")
+        return null;
+    const parts = value.trim().split(/\s+/);
+    if (parts.length < 2)
+        return null;
+    const path = parts[parts.length - 1];
+    const method = parts[parts.length - 2].toLowerCase();
+    if (!HTTP_METHODS.has(method))
+        return null;
+    if (!path.startsWith("/"))
+        return null;
+    return `${method} ${path}`;
+}
+/**
+ * The spec a PAGE names in its own `openapi:` frontmatter, or null.
+ *
+ * Mintlify lets a page point at a specific spec inline:
+ *
+ *     openapi: "/openapi.json GET /project/update-status/{statusId}"
+ *
+ * `openApiPageKey` already tolerates that leading token (it takes the last two
+ * tokens); this reads the token itself, which nothing did. A site whose
+ * `docs.json` has no `api.openapi` key therefore resolved NO endpoints even
+ * though every page stated exactly which spec to use — measured on Mintlify's
+ * own documentation: 100 pages imported without their endpoint content and 20
+ * of them came out completely blank, next to an `openapi.json` sitting in the
+ * repo root.
+ *
+ * Resolved the same way as a config-declared ref: a leading `/` is the DOCS
+ * root, not the filesystem root.
+ */
+export function openApiPageSpecRef(source, value) {
+    if (typeof value !== "string")
+        return null;
+    const parts = value.trim().split(/\s+/);
+    // Three tokens minimum: <spec> <METHOD> <path>. Two is method+path with no
+    // spec, which is the config-declared case.
+    if (parts.length < 3)
+        return null;
+    const ref = parts[0];
+    // Only treat it as a spec when it looks like one — a URL, a path, or a
+    // json/yaml filename. Anything else is a NAMED spec (Mintlify also allows
+    // `openapi: "api POST /x"` referring to a named entry), which this does not
+    // resolve and which the existing key parser already tolerates.
+    const looksLikeSpec = /^https?:\/\//.test(ref) || ref.startsWith("/") || /\.(json|ya?ml)$/i.test(ref);
+    return looksLikeSpec ? resolveSpecRef(source, ref, "page") : null;
+}
+/**
+ * The vault/site slug for a nav-referenced OpenAPI operation (a `pages` string
+ * of the form `"POST /api/generate"` under a tab/group that declares an
+ * `openapi` spec). The NAV and the GENERATED PAGE both call this, so their
+ * href and slug always agree. Path-based (`/api/generate` → `api/generate`) for
+ * clean URLs; same-path-different-method operations would collide — rare, and
+ * documented (ollama and typical REST doc sets use unique paths per page).
+ */
+export function openApiRefSlug(path) {
+    return path.replace(/^\//, "").replace(/\/$/, "");
+}
+/**
+ * Every distinct OpenAPI spec a Mintlify config references — the top-level
+ * `api.openapi` AND any `openapi` declared on a nav container (tab/group).
+ *
+ * Both are real source artifacts. Capturing only the top-level one meant a site
+ * like ollama (whose spec is declared on an "API Reference" tab) fell back to
+ * lossy reconstruction despite having a perfectly good spec on disk.
+ */
+export function collectMintlifyOpenApiSpecRefs(source, 
+/** Spec refs named by individual pages' `openapi:` frontmatter. */
+pageSpecRefs = []) {
+    const config = readConfig(source);
+    const refs = new Set(pageSpecRefs);
+    if (!config)
+        return [...refs];
+    const top = firstString(config.api?.openapi) ?? firstString(config.openapi);
+    const topResolved = top ? resolveSpecRef(source, top) : null;
+    if (topResolved)
+        refs.add(topResolved);
+    if (config.navigation) {
+        const found = new Map();
+        walkForOpenApiRefs(config.navigation, undefined, source, found);
+        for (const ref of found.keys())
+            refs.add(ref);
+    }
+    return [...refs];
+}
+/**
+ * Generate an ExportPage for every OpenAPI operation referenced ONLY by the nav
+ * (a `METHOD /path` `pages` string under a container that declares `openapi`) —
+ * these pages exist in no `.mdx` file (unlike the frontmatter case), so without
+ * this the nav links are dead and the API section is empty. ollama's docs.json
+ * is exactly this shape (an "Endpoints" group of 12 such strings under a tab
+ * with `openapi: /openapi.yaml`).
+ */
+export async function collectMintlifyOpenApiNavPages(source) {
+    const config = readConfig(source);
+    if (!config?.navigation)
+        return { pages: [], loadError: null };
+    const globalSpec = firstString(config.api?.openapi) ?? firstString(config.openapi);
+    // refs: specRef → set of "method path" keys referenced under it.
+    const refs = new Map();
+    walkForOpenApiRefs(config.navigation, globalSpec, source, refs);
+    if (refs.size === 0)
+        return { pages: [], loadError: null };
+    const pages = [];
+    const seen = new Set();
+    let loadError = null;
+    for (const [specRef, keys] of refs) {
+        const { map, titles, loadError: err } = await buildMintlifyEndpointMap(specRef);
+        if (err)
+            loadError = err;
+        for (const key of keys) {
+            const endpoint = map.get(key);
+            if (!endpoint)
+                continue;
+            const path = key.slice(key.indexOf(" ") + 1);
+            const slug = openApiRefSlug(path);
+            if (seen.has(slug))
+                continue;
+            seen.add(slug);
+            const ep = endpoint[0];
+            // format-openapi's title: the summary, unless it is shared or was a
+            // sentence fragment joined to its description (props.summary then holds
+            // the whole sentence).
+            const title = titles?.get(key) ||
+                `${String(ep.props?.method ?? "").toUpperCase()} ${path}`;
+            pages.push({ slug, title, tree: endpoint, headings: [] });
+        }
+    }
+    return { pages, loadError };
+}
+/** Walk a navigation node, tracking the inherited `openapi` spec, collecting
+ *  `METHOD /path` page strings keyed by their governing (resolved) spec ref. */
+function walkForOpenApiRefs(node, inheritedSpec, source, out, inPages = false) {
+    if (Array.isArray(node)) {
+        for (const e of node)
+            walkForOpenApiRefs(e, inheritedSpec, source, out, inPages);
+        return;
+    }
+    if (!node || typeof node !== "object") {
+        // A bare `METHOD /path` string — ONLY meaningful inside a `pages` array.
+        // Scanning every string made prose like `"See POST /users"` in a tab
+        // description generate a phantom API page.
+        if (!inPages)
+            return;
+        const key = typeof node === "string" ? openApiPageKey(node) : null;
+        if (key && inheritedSpec) {
+            const resolved = resolveSpecRef(source, inheritedSpec);
+            if (resolved) {
+                if (!out.has(resolved))
+                    out.set(resolved, new Set());
+                out.get(resolved).add(key);
+            }
+        }
+        return;
+    }
+    const declared = firstString(node.openapi);
+    const spec = declared ?? inheritedSpec;
+    // A container that DECLARES a spec registers it even when its children are
+    // ordinary .mdx pages — otherwise a nav-declared spec was only captured when
+    // a `METHOD /path` string happened to sit under it.
+    if (declared) {
+        const resolved = resolveSpecRef(source, declared);
+        if (resolved && !out.has(resolved))
+            out.set(resolved, new Set());
+    }
+    for (const [key, v] of Object.entries(node)) {
+        if (v && typeof v === "object") {
+            walkForOpenApiRefs(v, spec, source, out, key === "pages" || inPages);
+        }
+        else if (typeof v === "string" && key === "pages") {
+            walkForOpenApiRefs(v, spec, source, out, true);
+        }
+    }
+}
+function readConfig(source) {
+    for (const name of ["docs.json", "mint.json"]) {
+        const p = join(source, name);
+        if (existsSync(p)) {
+            try {
+                return JSON.parse(readFileSync(p, "utf-8"));
+            }
+            catch {
+                return null;
+            }
+        }
+    }
+    return null;
+}
+function firstString(v) {
+    if (typeof v === "string" && v.length > 0)
+        return v;
+    if (Array.isArray(v)) {
+        for (const e of v) {
+            const s = firstString(typeof e === "object" && e ? e.openapi ?? e.source : e);
+            if (s)
+                return s;
+        }
+    }
+    if (v && typeof v === "object") {
+        // `api.openapi` may be `{ source: "..." }` in some configs.
+        return firstString(v.source ?? v.openapi);
+    }
+    return undefined;
+}

package/dist/mintlify.d.ts

@@ -0,0 +1,2 @@
+import type { MdxAdapter } from "./adapter.js";
+export declare const mintlifyAdapter: MdxAdapter;

package/dist/mintlify.js

@@ -0,0 +1,195 @@
+/**
+ * `<Update label="2.1.218" description="July 22, 2026">` wraps every release
+ * in a Mintlify changelog, with the entries as ordinary markdown bullets
+ * inside.
+ *
+ * Unmapped it is PRESERVED as raw MDX, which means its inner markdown is
+ * never parsed — a 5,000-line changelog renders as one run-on paragraph of
+ * literal `*` characters (observed: 4,000+ bullets, zero list items). Mapping
+ * it with `children: "blocks"` is what makes the bullets parse.
+ *
+ * `details` rather than a callout: a changelog is hundreds of releases, and
+ * collapsing each one is the difference between a usable page and a wall.
+ * Both attributes ride into the title, because a version without its date
+ * loses the thing a reader scans for.
+ */
+const update = {
+    type: "details",
+    container: true,
+    children: "blocks",
+    propsFromAttrs: (attrs) => {
+        const label = attrs.label?.trim();
+        const description = attrs.description?.trim();
+        const title = [label, description].filter(Boolean).join(" — ");
+        // `<Update>` also carries `tags={[…]}` and `rss={{ title, description }}`.
+        // Reading only label/description dropped them with no ledger entry, and on
+        // the raw path they had survived byte-exact — 71 tags on one changelog page
+        // alone. Carried through as props so the information is not lost; an
+        // exporter that has nowhere to put them declares that in its capabilities.
+        const extra = {};
+        for (const key of ["tags", "rss"]) {
+            const value = attrs[key]?.trim();
+            if (value)
+                extra[key] = value;
+        }
+        return { variant: "note", ...(title ? { title } : {}), ...extra };
+    },
+};
+/**
+ * Self-closing marketing/experiment wrappers. Both carry NO documentation
+ * content — `<ContactSalesCard surface="bedrock" />` is a CTA, and
+ * `<Experiment flag="…" treatment={<ContactSalesCard …/>} />` is an A/B
+ * wrapper whose treatment is that same CTA.
+ *
+ * They were already being dropped by the built-in strip list; declaring them
+ * here makes the drop an ADAPTER DECISION recorded in the ledger, rather than
+ * a side effect of a component nobody had considered.
+ */
+/**
+ * `container: true` matches the BUILTIN strip entries for the same tags
+ * (`parse.ts` AgentInstructions/Experiment/ContactSalesCard). With
+ * `container: false` a paired `<Experiment>…</Experiment>` had its body kept
+ * and a stray `</Experiment>` html node leaked into the tree — invisible while
+ * the adapter was opt-in, and the default for every Mintlify site once adapter
+ * auto-selection landed.
+ */
+const stripped = { type: "", container: true, strip: true };
+/**
+ * `<ParamField body="url" type="string" required>` / `<ResponseField …>` — the
+ * parameter vocabulary of every hand-written Mintlify API page.
+ *
+ * Unmapped these were PRESERVED as `mdx-raw`, which is honest but not useful:
+ * an exporter that cannot render `<ParamField>` strips the tag and keeps only
+ * the description, so the reader is left with a page of unattributed sentences
+ * — the parameter NAME, TYPE, REQUIRED flag and DEFAULT all vanish. On the dub
+ * corpus that is 331 fields across the API reference.
+ *
+ * The mapping is evidence-backed, not guessed: the attribute set is fixed and
+ * documented, and the name arrives in whichever of `body`/`query`/`path`/
+ * `header` names the location — so the location is real information too, and
+ * rides into the term rather than being discarded.
+ *
+ * `deflist` because that IS the shape: a term (the parameter) and its
+ * definition (the prose). Every exporter already handles it, and the ones that
+ * lack a definition-list syntax degrade it visibly (bold term + indented body)
+ * rather than dropping it.
+ */
+const PARAM_LOCATIONS = ["body", "query", "path", "header"];
+/**
+ * `<Expandable title="properties">` wraps the NESTED fields of an object
+ * parameter. Unmapped it was preserved as raw MDX, so every exporter that
+ * cannot render it stripped the tag and orphaned the children — on dub that is
+ * 198 of 458 fields (43%), and 568 of 1753 (32%) on mintlify-docs, each losing
+ * its name and type exactly like the top-level fields did before ParamField
+ * was mapped.
+ *
+ * It has no content of its own beyond the title, so it UNWRAPS: its children
+ * are already `deflist`s and belong in the flow. The nesting is conveyed by the
+ * dotted field names Mintlify authors use (`user.name`), so flattening reads
+ * correctly rather than losing a distinction.
+ */
+const expandable = {
+    type: "",
+    container: true,
+    toNode: (_attrs, innerSource, ctx) => ctx.parseBlocks(innerSource),
+};
+const paramField = {
+    type: "deflist",
+    container: true,
+    toNode: (attrs, innerSource, ctx) => {
+        const location = PARAM_LOCATIONS.find((k) => attrs[k] !== undefined);
+        const name = (location ? attrs[location] : attrs.name) ?? "";
+        if (!name)
+            return "preserve";
+        const bits = [];
+        if (attrs.type)
+            bits.push(attrs.type);
+        if (location)
+            bits.push(location);
+        // A bare attribute arrives as the string "true".
+        if (attrs.required === "true" || attrs.required === "")
+            bits.push("required");
+        if (attrs.deprecated === "true" || attrs.deprecated === "")
+            bits.push("deprecated");
+        if (attrs.default)
+            bits.push(`default: ${attrs.default}`);
+        const body = ctx.parseBlocks(innerSource);
+        const dt = {
+            type: "dt",
+            inline: [
+                { type: "code", text: name },
+                ...(bits.length > 0 ? [{ type: "text", text: ` — ${bits.join(", ")}` }] : []),
+            ],
+        };
+        return {
+            type: "deflist",
+            children: [dt, ...(body.length > 0 ? [{ type: "dd", children: body }] : [])],
+        };
+    },
+};
+/**
+ * `<HeroCard filename title description href />` — a linked image card that
+ * Mintlify's own docs define IN THE PAGE:
+ *
+ *     export const HeroCard = ({ filename, title, description, href }) => {
+ *       return (<a href={href}><img src={…}/>…</a>)
+ *     }
+ *
+ * The definition is a multi-statement arrow, so the snippet substitution that
+ * handles `props => (<JSX/>)` cannot expand it, and every USAGE fell through to
+ * `mdx-raw` — 32 of them across the corpus, each rendering as a code block of
+ * its own JSX on the site's front page.
+ *
+ * Mapped rather than expanded: a Dogsbay `card` carries the title, description
+ * and href faithfully. What is lost is the hero IMAGE, whose src is built by
+ * template-interpolating `filename` into a GitHub raw URL — that is JavaScript,
+ * and reconstructing it would hard-code one site's asset convention into a
+ * general adapter. The card is the content; the image was decoration.
+ */
+/**
+ * IT DECLINES ANYTHING THAT IS NOT THAT SHAPE. `HeroCard` is not part of
+ * Mintlify's documented vocabulary the way `Update`/`ParamField`/`Expandable`
+ * are — it is a component one site defines in its own pages, and the name is
+ * generic enough that another site will define its own with different props
+ * (`image`, `cta`, `variant`). Coercing those into a card whose title and href
+ * are empty would be worse than leaving them raw, so an unrecognised shape
+ * returns "preserve" — byte-exact `mdx-raw` plus a ledger entry — and a site
+ * that wants its own mapping uses `--components`, which exists for exactly this.
+ */
+const heroCard = {
+    type: "card",
+    container: false,
+    toNode: (attrs) => {
+        const title = attrs.title?.trim();
+        const href = attrs.href?.trim();
+        // The documented shape carries at least a title and a destination.
+        if (!title || !href)
+            return "preserve";
+        const description = attrs.description?.trim();
+        return {
+            type: "card",
+            props: { title, href, ...(description ? { description } : {}) },
+        };
+    },
+};
+export const mintlifyAdapter = {
+    name: "mintlify",
+    components: {
+        HeroCard: heroCard,
+        Update: update,
+        ParamField: paramField,
+        Expandable: expandable,
+        ResponseField: paramField,
+        ContactSalesCard: stripped,
+        Experiment: stripped,
+    },
+    // NOT self-closing, despite an earlier note here saying so. The segmenter
+    // decides pairing from THIS list, not from a mapping's `container` flag, so
+    // declaring them self-closing meant `<Experiment name="x">…</Experiment>`
+    // was never paired: the body stayed in the page and the stray closing tag
+    // was emitted as raw HTML, while the ledger recorded it as "stripped".
+    // Flipping `container: true` on the mapping did not fix it, because nothing
+    // reads `container` at segmentation time. The builtin (no-adapter) path
+    // handled these correctly, so the declaration was a regression against it.
+    selfClosingTags: [],
+};

package/dist/nav-extract.d.ts

@@ -0,0 +1,42 @@
+/**
+ * Static sidebar extraction from a hardcoded Fumadocs page tree.
+ *
+ * Passing a hand-built `PageTree.Root` to `DocsLayout tree={…}` is a
+ * documented first-class Fumadocs pattern; sites that use it (better-auth's
+ * sidebar-content.tsx) keep the REAL sidebar in a TSX data literal and let
+ * meta.json go stale. Page trees must be serializable by design, so the
+ * literal is statically readable: this module captures the exported array
+ * and maps it to NavItem[] — no execution, ever (icons and other JSX
+ * values ride through the balanced scanner and are dropped).
+ *
+ * The mapping is shape-tolerant rather than better-auth-specific: an entry
+ * contributes a nav item when it has a string `title`/`name`/`label`;
+ * `href`/`url` become the link; the first array-valued key among
+ * `list`/`subpages`/`children`/`items`/`pages` becomes the children.
+ *
+ * Href prefix: sites hardcode their mount point (`/docs/introduction`).
+ * When every internal href shares the same first path segment it is
+ * stripped and replaced with the importer's own `hrefPrefix` (auto-detected
+ * — pass `stripPrefix` to override).
+ */
+import type { NavItem } from "@dogsbay/types";
+export interface NavExtractOptions {
+    /** Name of the exported array (default "contents"). */
+    exportName?: string;
+    /** Prefix for emitted hrefs (e.g. "/docs" of the TARGET site). */
+    hrefPrefix?: string;
+    /**
+     * Leading path segment to strip from the source's hardcoded hrefs
+     * (e.g. "/docs"). Auto-detected when omitted: stripped when every
+     * internal href shares the same first segment.
+     */
+    stripPrefix?: string;
+}
+/**
+ * Extract NavItem[] from TSX source containing an exported data-literal
+ * page tree. Returns null when the export is missing or doesn't scan —
+ * callers fall back to the meta.json walk (never guess).
+ */
+export declare function extractNavFromTsx(source: string, opts?: NavExtractOptions): NavItem[] | null;
+/** File-reading convenience for the CLI layer. */
+export declare function extractNavFromTsxFile(filePath: string, opts?: NavExtractOptions): NavItem[] | null;