@dogsbay/format-docusaurus 0.2.0-beta.78

package/dist/adapter.d.ts

@@ -0,0 +1,70 @@
+/**
+ * Docusaurus site adapter — extension points for components and conventions
+ * that a specific site layered on top of *standard* Docusaurus.
+ *
+ * The generic parser handles only built-in Docusaurus syntax (admonitions,
+ * Tabs/TabItem, details, CodeBlock, DocCardList, frontmatter, sidebars).
+ * Anything a site invented — custom MDX components, a variable-substitution
+ * plugin, partial includes — lives in a separate adapter package and is
+ * injected via `--adapter`.
+ *
+ * Usage:
+ *   docusaurusToTree(source)                         // generic only
+ *   docusaurusToTree(source, { adapter: tigera })    // generic + Tigera
+ */
+export interface ComponentMapping {
+    /** TreeNode type to produce (e.g. "card", "callout", "badge"). */
+    type: string;
+    /** Extract props from JSX attributes. */
+    propsFromAttrs?: (attrs: Record<string, string>) => Record<string, unknown>;
+    /** Whether this component wraps children. */
+    container: boolean;
+    /** Strip the component entirely. If container=true, inner content is kept. */
+    strip?: boolean;
+}
+export interface PreprocessContext {
+    /** Absolute path of the source file being parsed (for partial resolution). */
+    filePath?: string;
+    /** Absolute path of the docs instance directory (e.g. .../calico). */
+    instanceDir?: string;
+    /**
+     * Absolute path of the Docusaurus project root (where docusaurus.config.js
+     * lives). Lets adapters resolve `@site/...` import aliases when inlining
+     * partials.
+     */
+    projectDir?: string;
+    /**
+     * How partials are handled (mirrors AsciiDoc's `inlineIncludes`):
+     * - "inline" (default) — partial bodies spliced into each page verbatim.
+     * - "include" — emit `{% include "…" %}` directives + collect partials as
+     *   fragments (resolved at build time by the Minja preprocessor).
+     */
+    partialMode?: "inline" | "include";
+    /**
+     * Fragment collector for `partialMode: "include"`. Maps a resolved partial
+     * source path → its include path (relative to the content root). The importer
+     * drains this after parsing to emit fragment `.md` files. Adapters populate it
+     * when they emit `{% include %}`.
+     */
+    fragments?: Map<string, string>;
+}
+export interface DocusaurusAdapter {
+    /** Adapter name (e.g. "tigera"). */
+    name: string;
+    /**
+     * Raw-text rewrites applied to the MDX source BEFORE any parsing. This is
+     * where non-standard preprocessing lives — e.g. Tigera's `$[variable]`
+     * substitution (a custom remark plugin, not standard Docusaurus) and
+     * `_includes/` partial inlining. Inlined content gets full parser treatment.
+     */
+    preprocess?: (source: string, ctx: PreprocessContext) => string;
+    /** Block-level component mappings (components on their own line). */
+    components?: Record<string, ComponentMapping>;
+    /** Self-closing tags (no closing tag expected). */
+    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)][];
+}

package/dist/adapter.js

@@ -0,0 +1,15 @@
+/**
+ * Docusaurus site adapter — extension points for components and conventions
+ * that a specific site layered on top of *standard* Docusaurus.
+ *
+ * The generic parser handles only built-in Docusaurus syntax (admonitions,
+ * Tabs/TabItem, details, CodeBlock, DocCardList, frontmatter, sidebars).
+ * Anything a site invented — custom MDX components, a variable-substitution
+ * plugin, partial includes — lives in a separate adapter package and is
+ * injected via `--adapter`.
+ *
+ * Usage:
+ *   docusaurusToTree(source)                         // generic only
+ *   docusaurusToTree(source, { adapter: tigera })    // generic + Tigera
+ */
+export {};

package/dist/cli.d.ts

@@ -0,0 +1,2 @@
+import type { FormatPlugin } from "@dogsbay/types";
+export declare const plugin: FormatPlugin;

package/dist/cli.js

@@ -0,0 +1,246 @@
+import { existsSync, readFileSync, readdirSync } from "node:fs";
+import { join, relative, isAbsolute } from "node:path";
+import { parseMeta } from "@dogsbay/types";
+import { extractFrontmatter } from "./frontmatter.js";
+import { docusaurusToTree } from "./parse-mdx.js";
+import { findConfig, parseDocusaurusConfig, selectInstance } from "./config.js";
+import { buildNav, makeDocHref, makeDocLabel } from "./nav.js";
+/**
+ * Detect a Docusaurus project: a docusaurus.config.* at the root, or a
+ * sidebars*.js alongside docs content.
+ */
+function detectDocusaurusSource(path) {
+    if (findConfig(path))
+        return true;
+    try {
+        const entries = readdirSync(path);
+        if (entries.some((e) => /^sidebars.*\.(js|ts|cjs|mjs)$/.test(e)))
+            return true;
+    }
+    catch {
+        // not a directory
+    }
+    return false;
+}
+/** Collect doc files in an instance dir, skipping `_`-prefixed files/dirs. */
+function walkDocFiles(dir, rootDir) {
+    const results = [];
+    for (const entry of readdirSync(dir, { withFileTypes: true })) {
+        if (entry.name.startsWith("_"))
+            continue; // _includes, _category_.json, partials
+        const fullPath = join(dir, entry.name);
+        if (entry.isDirectory()) {
+            results.push(...walkDocFiles(fullPath, rootDir));
+        }
+        else if (entry.name.endsWith(".mdx") || entry.name.endsWith(".md")) {
+            const slug = relative(rootDir, fullPath)
+                .replace(/\\/g, "/")
+                .replace(/\.mdx?$/, "")
+                .replace(/\/index$/, "") || "index";
+            results.push({ filePath: fullPath, slug });
+        }
+    }
+    return results;
+}
+async function importDocusaurus(source, opts) {
+    const projectDir = source;
+    // Default to root ("") — the platform's default basePath is now host-root
+    // (plans/default-basepath-root.md), so pages emit at /<slug>, not /docs/<slug>.
+    // `site build` threads the real basePath via opts.hrefPrefix; only the
+    // prefix-less `convert` path falls back to this default.
+    const hrefPrefix = typeof opts.hrefPrefix === "string" ? opts.hrefPrefix : "";
+    // The CLI resolves `--adapter <name>` to an adapter object and threads it here,
+    // keeping this generic package free of any site-specific imports.
+    const adapter = opts.adapterInstance;
+    // Partial handling: "inline" (default) splices bodies in; "include" emits
+    // {% include %} directives + collects partials as fragment pages (mirrors the
+    // AsciiDoc importer). Structural mode targets dogsbay-md, where the directives
+    // stay live for `site build`'s Minja preprocessor to resolve.
+    const partialMode = opts.partialMode === "include" ? "include" : "inline";
+    if (partialMode === "include" && opts.to && opts.to !== "dogsbay-md") {
+        throw new Error(`--partial-mode include requires --to dogsbay-md (the directives must stay ` +
+            `live for \`site build\` to resolve). Got --to ${opts.to}.`);
+    }
+    // resolvedPartialPath → include path; drained into fragment pages after parsing.
+    const fragments = new Map();
+    // Resolve which docs instance to import.
+    const configPath = findConfig(projectDir);
+    let instanceDir = projectDir;
+    let routeBasePath = "docs";
+    let sidebarPath = null;
+    if (configPath) {
+        const instances = parseDocusaurusConfig(configPath);
+        const instance = selectInstance(instances, opts.instance);
+        instanceDir = isAbsolute(instance.path) ? instance.path : join(projectDir, instance.path);
+        routeBasePath = instance.routeBasePath;
+        if (instance.sidebarPath) {
+            sidebarPath = isAbsolute(instance.sidebarPath)
+                ? instance.sidebarPath
+                : join(projectDir, instance.sidebarPath);
+        }
+        console.log(`Docs instance: ${instance.id} (path: ${instance.path}, route: /${routeBasePath})`);
+    }
+    else {
+        // No config — treat the source itself as a docs dir; look for a sibling sidebar.
+        for (const name of readdirSync(projectDir)) {
+            if (/^sidebars.*\.(js|ts|cjs|mjs)$/.test(name)) {
+                sidebarPath = join(projectDir, name);
+                break;
+            }
+        }
+    }
+    if (!existsSync(instanceDir)) {
+        throw new Error(`Docs instance directory not found: ${instanceDir}`);
+    }
+    // Docusaurus serves the project's `static/` directory at the site root
+    // (`static/img/foo.svg` → `/img/foo.svg`). Dogsbay's standard is the
+    // `content/_assets/` convention (docs/images.md) — content imagery rooted at
+    // `/_assets/...`, with `public/` reserved for site-level files. So we map
+    // Docusaurus static → `_assets`: signal the dir for the exporter to copy into
+    // `_assets/`, and the parser rewrites image srcs `/img/…` → `/_assets/img/…`.
+    // Threaded through opts so convert + site-build flows pick it up.
+    const staticDir = join(projectDir, "static");
+    if (existsSync(staticDir)) {
+        const existing = Array.isArray(opts.assetMounts)
+            ? opts.assetMounts
+            : [];
+        opts.assetMounts = [...existing, { dir: staticDir }];
+    }
+    // When a static dir is mounted into _assets, root-absolute image srcs are
+    // rewritten `/img/x` → `/_assets/img/x` (the Dogsbay convention).
+    const assetPrefix = opts.assetMounts ? "/_assets" : undefined;
+    // Resolve a doc id (e.g. from <DocCardLink docId=…>) to its href + title.
+    const docHref = makeDocHref(hrefPrefix);
+    const docLabel = makeDocLabel(instanceDir);
+    const resolveDoc = (docId) => ({ href: docHref(docId), title: docLabel(docId) });
+    // Build nav up front so DocCardList (which renders the current page's sidebar
+    // category as a card grid) can resolve a page's category children. Map each
+    // clickable category's href → its child nav items.
+    const nav = await buildNav({ instanceDir, hrefPrefix, sidebarPath });
+    const docCardListMap = new Map();
+    const collectCategories = (items) => {
+        for (const it of items) {
+            if (it.children && it.children.length > 0) {
+                if (it.href)
+                    docCardListMap.set(it.href, it.children);
+                collectCategories(it.children);
+            }
+        }
+    };
+    collectCategories(nav);
+    const resolveDocCardList = (slug) => docCardListMap.get(docHref(slug));
+    // Parse pages.
+    const docFiles = walkDocFiles(instanceDir, instanceDir);
+    const taxonomyNames = Array.isArray(opts.taxonomyNames)
+        ? opts.taxonomyNames
+        : undefined;
+    const warnings = new Map();
+    const onWarn = (msg) => warnings.set(msg, (warnings.get(msg) ?? 0) + 1);
+    const pages = [];
+    for (const { filePath, slug } of docFiles) {
+        const content = readFileSync(filePath, "utf-8");
+        const { frontmatter, raw, body } = extractFrontmatter(content);
+        if (frontmatter.draft)
+            continue;
+        const tree = docusaurusToTree(content, {
+            adapter,
+            routeBasePath,
+            hrefPrefix,
+            assetPrefix,
+            currentSlug: slug,
+            resolveDoc,
+            resolveDocCardList,
+            preprocessContext: { filePath, instanceDir, projectDir, partialMode, fragments },
+            onWarn,
+        });
+        const headings = tree
+            .filter((n) => n.type === "heading")
+            .map((n) => ({
+            depth: n.props?.level,
+            text: n.props?.text,
+            slug: n.props?.slug,
+        }));
+        const title = frontmatter.title ||
+            headingTitle(body) ||
+            slug.split("/").pop() ||
+            slug;
+        pages.push({
+            slug,
+            title,
+            tree,
+            headings,
+            frontmatter: raw,
+            meta: parseMeta(raw, { slug, taxonomyNames }),
+        });
+    }
+    // Drain collected fragments (partialMode "include" only). Each referenced
+    // partial is converted the same way — recursively, since a fragment may
+    // reference more partials — and emitted as a frontmatter-less fragment page
+    // at its include path. The exporter writes these as plain `.md` include
+    // targets; they never enter nav. Mirrors migrate-asciidoc's fragments.
+    const processed = new Set();
+    while (fragments.size > processed.size) {
+        for (const [resolvedPath, includePath] of [...fragments]) {
+            if (processed.has(resolvedPath))
+                continue;
+            processed.add(resolvedPath);
+            if (!existsSync(resolvedPath))
+                continue;
+            const fragContent = readFileSync(resolvedPath, "utf-8");
+            const fragTree = docusaurusToTree(fragContent, {
+                adapter,
+                routeBasePath,
+                hrefPrefix,
+                assetPrefix,
+                currentSlug: includePath.replace(/\.md$/, ""),
+                resolveDoc,
+                resolveDocCardList,
+                preprocessContext: {
+                    filePath: resolvedPath,
+                    instanceDir,
+                    projectDir,
+                    partialMode,
+                    fragments,
+                },
+                onWarn,
+            });
+            pages.push({
+                slug: includePath.replace(/\.md$/, ""),
+                title: "",
+                tree: fragTree,
+                headings: [],
+                frontmatter: {},
+                fragment: true,
+            });
+        }
+    }
+    // Infer site name from the index page if not provided.
+    if (!opts.siteName && pages.length > 0) {
+        const indexPage = pages.find((p) => p.slug === "index" || p.slug === "");
+        if (indexPage)
+            opts.siteName = indexPage.title;
+    }
+    // Summarize warnings once.
+    for (const [msg, count] of warnings) {
+        console.warn(`Warning (${count}×): ${msg}`);
+    }
+    console.log(`Parsed ${pages.length} pages`);
+    return { pages, nav };
+}
+function headingTitle(body) {
+    const m = body.match(/^#\s+(.+?)\s*$/m);
+    return m ? m[1].trim() : undefined;
+}
+export const plugin = {
+    name: "docusaurus",
+    canImport: true,
+    canExport: false,
+    detectSource: detectDocusaurusSource,
+    importOptions: [
+        { flags: "--instance <id>", description: "plugin-content-docs instance id to import (e.g. calico)" },
+        { flags: "--adapter <name>", description: "Site adapter for custom components (e.g. tigera)" },
+    ],
+    async import(source, opts) {
+        return importDocusaurus(source, opts);
+    },
+};

package/dist/code-meta.d.ts

@@ -0,0 +1,20 @@
+/**
+ * Parse a Docusaurus fenced-code metastring.
+ *
+ * Docusaurus extends the info string after the language with:
+ *   - title="..." or title='...'   → code block title
+ *   - {1,4-6,11}                    → highlighted line ranges
+ *   - showLineNumbers               → render line numbers
+ *
+ * Example:  ```jsx title="src/foo.js" {1,4-6} showLineNumbers
+ *
+ * Docs: https://docusaurus.io/docs/markdown-features/code-blocks
+ */
+export interface CodeMeta {
+    lang: string;
+    title?: string;
+    /** Expanded list of highlighted line numbers (1-based). */
+    highlights?: number[];
+    showLineNumbers?: boolean;
+}
+export declare function parseCodeMeta(info: string): CodeMeta;

package/dist/code-meta.js

@@ -0,0 +1,54 @@
+/**
+ * Parse a Docusaurus fenced-code metastring.
+ *
+ * Docusaurus extends the info string after the language with:
+ *   - title="..." or title='...'   → code block title
+ *   - {1,4-6,11}                    → highlighted line ranges
+ *   - showLineNumbers               → render line numbers
+ *
+ * Example:  ```jsx title="src/foo.js" {1,4-6} showLineNumbers
+ *
+ * Docs: https://docusaurus.io/docs/markdown-features/code-blocks
+ */
+/** Expand a range spec like "1,4-6,11" into [1,4,5,6,11]. */
+function expandRanges(spec) {
+    const out = [];
+    for (const part of spec.split(",")) {
+        const trimmed = part.trim();
+        if (!trimmed)
+            continue;
+        const range = trimmed.match(/^(\d+)\s*-\s*(\d+)$/);
+        if (range) {
+            const start = parseInt(range[1], 10);
+            const end = parseInt(range[2], 10);
+            const [lo, hi] = start <= end ? [start, end] : [end, start];
+            for (let n = lo; n <= hi; n++)
+                out.push(n);
+        }
+        else if (/^\d+$/.test(trimmed)) {
+            out.push(parseInt(trimmed, 10));
+        }
+    }
+    return out;
+}
+export function parseCodeMeta(info) {
+    const raw = (info ?? "").trim();
+    if (!raw)
+        return { lang: "plaintext" };
+    // Language is the first whitespace-delimited token.
+    const lang = raw.split(/\s+/)[0] || "plaintext";
+    const rest = raw.slice(lang.length);
+    const titleMatch = rest.match(/title=(?:"([^"]*)"|'([^']*)')/);
+    const title = titleMatch ? (titleMatch[1] ?? titleMatch[2]) : undefined;
+    const highlightMatch = rest.match(/\{([\d\s,-]+)\}/);
+    const highlights = highlightMatch ? expandRanges(highlightMatch[1]) : undefined;
+    const showLineNumbers = /\bshowLineNumbers\b/.test(rest) || undefined;
+    const meta = { lang };
+    if (title)
+        meta.title = title;
+    if (highlights && highlights.length)
+        meta.highlights = highlights;
+    if (showLineNumbers)
+        meta.showLineNumbers = true;
+    return meta;
+}

package/dist/config.d.ts

@@ -0,0 +1,18 @@
+export interface DocsInstance {
+    /** Plugin instance id (e.g. "calico"); "default" for the preset docs. */
+    id: string;
+    /** Source directory relative to the project root (e.g. "calico"). */
+    path: string;
+    /** URL route base (e.g. "calico"). Defaults to "docs" when unset. */
+    routeBasePath: string;
+    /** Sidebar module path relative to the project root, or null if disabled. */
+    sidebarPath: string | null;
+}
+/** Find the docusaurus config file in a project directory. */
+export declare function findConfig(projectDir: string): string | null;
+export declare function parseDocusaurusConfig(configPath: string): DocsInstance[];
+/**
+ * Resolve a single instance by id, or the sole instance when there is exactly
+ * one usable one. Throws a helpful error otherwise.
+ */
+export declare function selectInstance(instances: DocsInstance[], requestedId?: string): DocsInstance;

package/dist/config.js

@@ -0,0 +1,183 @@
+/**
+ * Extract plugin-content-docs instances from a `docusaurus.config.js`/`.ts`.
+ *
+ * We STATICALLY PARSE the config rather than executing it. A real Docusaurus
+ * config commonly imports theme packages (prism-react-renderer), remark
+ * plugins, and may be an async function — executing it would require the source
+ * repo's node_modules and run arbitrary code. The instance metadata we need
+ * (id / path / routeBasePath / sidebarPath) are simple string literals, so a
+ * lightweight brace-aware scan is both more robust and safer.
+ *
+ * Recognised instance sources:
+ *   - preset `docs: { path, routeBasePath, sidebarPath }`  (id defaults to "default")
+ *   - each `['@docusaurus/plugin-content-docs', { id, path, routeBasePath, sidebarPath }]`
+ */
+import { existsSync, readFileSync } from "node:fs";
+import { join } from "node:path";
+const CONFIG_NAMES = [
+    "docusaurus.config.js",
+    "docusaurus.config.ts",
+    "docusaurus.config.mjs",
+    "docusaurus.config.cjs",
+];
+/** Find the docusaurus config file in a project directory. */
+export function findConfig(projectDir) {
+    for (const name of CONFIG_NAMES) {
+        const p = join(projectDir, name);
+        if (existsSync(p))
+            return p;
+    }
+    return null;
+}
+/**
+ * Strip `//` and block comments while preserving string/template literals.
+ * Necessary because Docusaurus configs annotate instances with JSDoc comments
+ * like `/** @type {import('...').Options} *​/` whose braces would otherwise be
+ * mistaken for the object literal.
+ */
+function stripJsComments(src) {
+    let out = "";
+    let i = 0;
+    let inStr = null;
+    while (i < src.length) {
+        const ch = src[i];
+        const next = src[i + 1];
+        if (inStr) {
+            out += ch;
+            if (ch === "\\") {
+                out += next ?? "";
+                i += 2;
+                continue;
+            }
+            if (ch === inStr)
+                inStr = null;
+            i++;
+            continue;
+        }
+        if (ch === '"' || ch === "'" || ch === "`") {
+            inStr = ch;
+            out += ch;
+            i++;
+            continue;
+        }
+        if (ch === "/" && next === "/") {
+            while (i < src.length && src[i] !== "\n")
+                i++;
+            continue;
+        }
+        if (ch === "/" && next === "*") {
+            i += 2;
+            while (i < src.length && !(src[i] === "*" && src[i + 1] === "/"))
+                i++;
+            i += 2;
+            continue;
+        }
+        out += ch;
+        i++;
+    }
+    return out;
+}
+/** Extract the `{...}` object literal that follows `fromIndex` (balanced braces). */
+function extractObjectAfter(src, fromIndex) {
+    const open = src.indexOf("{", fromIndex);
+    if (open === -1)
+        return null;
+    let depth = 0;
+    let inStr = null;
+    for (let i = open; i < src.length; i++) {
+        const ch = src[i];
+        const prev = src[i - 1];
+        if (inStr) {
+            if (ch === inStr && prev !== "\\")
+                inStr = null;
+            continue;
+        }
+        if (ch === '"' || ch === "'" || ch === "`") {
+            inStr = ch;
+            continue;
+        }
+        if (ch === "{")
+            depth++;
+        else if (ch === "}") {
+            depth--;
+            if (depth === 0)
+                return src.slice(open, i + 1);
+        }
+    }
+    return null;
+}
+/** Read a top-level `key: 'value'` string literal from an object-literal source. */
+function readStringKey(objSrc, key) {
+    const re = new RegExp(`\\b${key}\\s*:\\s*(?:"([^"]*)"|'([^']*)'|\`([^\`]*)\`)`);
+    const m = objSrc.match(re);
+    if (!m)
+        return undefined;
+    return m[1] ?? m[2] ?? m[3];
+}
+/** Detect `key: false` (e.g. `sidebarPath: false`). */
+function isFalseKey(objSrc, key) {
+    return new RegExp(`\\b${key}\\s*:\\s*false\\b`).test(objSrc);
+}
+function toInstance(objSrc, idFallback) {
+    const path = readStringKey(objSrc, "path");
+    // The preset `docs` block has no plugin id; plugins carry their own id.
+    const id = readStringKey(objSrc, "id") ?? idFallback;
+    const routeBasePath = readStringKey(objSrc, "routeBasePath") ?? path ?? "docs";
+    const sidebarPath = isFalseKey(objSrc, "sidebarPath")
+        ? null
+        : readStringKey(objSrc, "sidebarPath") ?? null;
+    if (!path)
+        return null;
+    return { id, path, routeBasePath, sidebarPath };
+}
+export function parseDocusaurusConfig(configPath) {
+    const src = stripJsComments(readFileSync(configPath, "utf-8"));
+    const instances = [];
+    // Each plugin-content-docs entry: ['@docusaurus/plugin-content-docs', { ... }]
+    const pluginRe = /['"]@docusaurus\/plugin-content-docs['"]\s*,/g;
+    let m;
+    while ((m = pluginRe.exec(src)) !== null) {
+        const objSrc = extractObjectAfter(src, m.index + m[0].length);
+        if (!objSrc)
+            continue;
+        const inst = toInstance(objSrc, "default");
+        if (inst)
+            instances.push(inst);
+    }
+    // Preset docs instance: `docs: { ... }` (id defaults to "default").
+    const docsKey = src.match(/\bdocs\s*:\s*\{/);
+    if (docsKey) {
+        const objSrc = extractObjectAfter(src, docsKey.index);
+        if (objSrc) {
+            const inst = toInstance(objSrc, "default");
+            // Only include if it has a real path (skip `docs: false` etc.).
+            if (inst && inst.path && inst.path !== "default") {
+                instances.push(inst);
+            }
+            else if (inst && inst.path === "default") {
+                // Tigera's placeholder default instance — keep it so callers can see it.
+                instances.push(inst);
+            }
+        }
+    }
+    return instances;
+}
+/**
+ * Resolve a single instance by id, or the sole instance when there is exactly
+ * one usable one. Throws a helpful error otherwise.
+ */
+export function selectInstance(instances, requestedId) {
+    const usable = instances.filter((i) => i.path && i.path !== "default");
+    if (requestedId) {
+        const found = instances.find((i) => i.id === requestedId);
+        if (!found) {
+            const ids = instances.map((i) => i.id).join(", ");
+            throw new Error(`No plugin-content-docs instance with id "${requestedId}". Available: ${ids || "(none)"}`);
+        }
+        return found;
+    }
+    if (usable.length === 1)
+        return usable[0];
+    const ids = usable.map((i) => i.id).join(", ");
+    throw new Error(`Multiple docs instances found (${ids}). Pass --instance <id> to choose one.`);
+}

package/dist/frontmatter.d.ts

@@ -0,0 +1,35 @@
+export interface DocusaurusFrontmatter {
+    /** Explicit doc id (overrides the file-path-derived id). */
+    id?: string;
+    /** Page title. Falls back to the first H1 when absent. */
+    title?: string;
+    /** Custom URL segment(s) for this page. */
+    slug?: string;
+    /** Sort weight within its sidebar category (lower = earlier). */
+    sidebar_position?: number;
+    /** Sidebar display label (overrides title in the sidebar). */
+    sidebar_label?: string;
+    /** Extra class on the sidebar item. */
+    sidebar_class_name?: string;
+    /** Hide this page from the autogenerated sidebar. */
+    sidebar_custom_props?: Record<string, unknown>;
+    /** Meta description. */
+    description?: string;
+    /** Suppress the auto-rendered H1 title. */
+    hide_title?: boolean;
+    /** Exclude from production builds. */
+    draft?: boolean;
+    /** Tags. */
+    tags?: unknown;
+    /** Pagination label override. */
+    pagination_label?: string;
+}
+export interface ExtractedFrontmatter {
+    /** Typed subset of well-known fields. */
+    frontmatter: DocusaurusFrontmatter;
+    /** Full YAML as a flat record — includes all custom fields. */
+    raw: Record<string, unknown>;
+    /** Source with the frontmatter block removed. */
+    body: string;
+}
+export declare function extractFrontmatter(source: string): ExtractedFrontmatter;