@dogsbay/format-vitepress 0.2.0-beta.131 → 0.2.0-beta.133

package/README.md

@@ -32,6 +32,15 @@ import { importVitepress } from "@dogsbay/format-vitepress/cli";
 const { pages, nav } = await importVitepress("./docs", { hrefPrefix: "/docs" });
 ```
 
+In a browser (no Node, nothing from the repository is run), a project as a map of files to
+the Dogsbay project `dogsbay convert --to dogsbay-md` writes, under `content/`:
+
+```ts
+import { migrate } from "@dogsbay/format-vitepress/migrate";
+
+const { files, ledger } = await migrate({ files: new Map([[".vitepress/config.ts", "…"], ["index.md", "# Home"]]) });
+```
+
 Or the pieces:
 
 ```ts

package/dist/cli.d.ts

@@ -1,3 +1,14 @@
+/**
+ * FormatPlugin for VitePress as a source format.
+ *
+ * The project on disk is read into a corpus (`loaders/folder.ts`), then imported by
+ * `importVitepressCorpus`, the import the browser runs too (`./migrate`). This file adds
+ * the disk and the console summary.
+ *
+ * VitePress content is `.md`, so this plugin MUST be registered before the
+ * generic dogsbay-md detector. `detectVitepress` requires an actual
+ * `.vitepress/config.*`, so it cannot claim a plain-Markdown corpus.
+ */
 import type { FormatPlugin, ExportPage, NavItem } from "@dogsbay/types";
 export interface VitepressImportResult {
     pages: ExportPage[];

package/dist/cli.js

@@ -1,71 +1,24 @@
-/**
- * FormatPlugin for VitePress as a source format.
- *
- * Orchestrates: detect corpus → loadVitepress (config + page walk + nav) →
- * translate each page (parseVitepress) → assemble ExportPage[] + NavItem[].
- *
- * VitePress content is `.md`, so this plugin MUST be registered before the
- * generic dogsbay-md detector. `detectVitepress` requires an actual
- * `.vitepress/config.*`, so it cannot claim a plain-Markdown corpus.
- */
-import { readFileSync } from "node:fs";
-import { extractHeadings } from "@dogsbay/format-dogsbay-md";
-import { parseVitepress } from "./parse.js";
-import { loadVitepress, detectVitepress, translateOptionsFor, titleFromSlug, } from "./loaders/load.js";
+import { importVitepressCorpus } from "./import.js";
+import { detectVitepress, readVitepressFolder } from "./loaders/folder.js";
 export async function importVitepress(source, opts = {}) {
     const hrefPrefix = typeof opts.hrefPrefix === "string" ? opts.hrefPrefix : "";
-    const loaded = await loadVitepress(source, {
-        hrefPrefix,
+    const { corpus, config, warnings } = await readVitepressFolder(source, {
         evalConfig: opts.evalConfig === true || opts.evalConfig === "true",
     });
-    const pages = [];
-    const components = {};
-    let ledgerTotal = 0;
-    let failed = 0;
-    for (const ps of loaded.pages) {
-        try {
-            const content = readFileSync(ps.filePath, "utf-8");
-            const tOpts = translateOptionsFor(ps, loaded.srcDir, loaded.root, loaded.warnings);
-            const { tree, frontmatter, body, ledger, components: comps } = parseVitepress(content, tOpts);
-            ledgerTotal += ledger.length;
-            for (const [name, n] of Object.entries(comps)) {
-                components[name] = (components[name] ?? 0) + n;
-            }
-            const headings = extractHeadings(tree);
-            const h1 = headings.find((h) => h.depth === 1);
-            const fmTitle = typeof frontmatter.title === "string" && frontmatter.title.trim()
-                ? frontmatter.title.trim()
-                : undefined;
-            // A `layout: home` page carries its name in `hero.name`, not a heading.
-            const heroName = typeof frontmatter.hero?.name === "string"
-                ? (frontmatter.hero.name)
-                : undefined;
-            pages.push({
-                slug: ps.slug,
-                title: fmTitle || h1?.text || heroName || titleFromSlug(ps.slug),
-                tree,
-                headings,
-                frontmatter,
-                meta: (ledger.length
-                    ? { vitepressLedger: ledger }
-                    : {}),
-                bodyMarkdown: body,
-            });
-        }
-        catch (err) {
-            failed += 1;
-            const msg = err instanceof Error ? err.message : String(err);
-            console.warn(`vitepress import: failed to convert ${ps.filePath} (slug "${ps.slug}"), skipping: ${msg}`);
-        }
+    const imported = importVitepressCorpus(corpus, { hrefPrefix, config, warnings });
+    const failed = imported.ledger.filter((e) => e.code === "page-failed");
+    for (const e of failed) {
+        console.warn(`vitepress import: failed to convert ${corpus.absolute(e.file ?? "")}, skipping: ${e.message}`);
     }
-    reportSummary(loaded.warnings, failed, loaded.pages.length, ledgerTotal, components, loaded.navSource);
+    const ledgerTotal = imported.ledger.filter((e) => e.code === "unmapped-construct").length;
+    reportSummary(imported.warnings, failed.length, imported.pages.length + failed.length, ledgerTotal, imported.components, imported.navSource);
     return {
-        pages,
-        nav: loaded.nav,
-        srcDir: loaded.srcDir,
-        navSource: loaded.navSource,
-        assetMounts: loaded.assetDirs,
-        siteName: loaded.config.title,
+        pages: imported.pages,
+        nav: imported.nav,
+        srcDir: corpus.absolute(imported.srcDir),
+        navSource: imported.navSource,
+        assetMounts: imported.assetDirs.map((a) => ({ ...a, dir: corpus.absolute(a.dir) })),
+        ...(imported.siteName ? { siteName: imported.siteName } : {}),
     };
 }
 /**

package/dist/config-node.d.ts

@@ -0,0 +1,20 @@
+import { type VitePressConfig } from "./config.js";
+/**
+ * Locate `.vitepress/config.*`.
+ *
+ * VitePress also permits `.vitepress/config/index.*` — the split-config layout
+ * used by larger sites (Element Plus, Vue's own docs).
+ */
+export declare function findConfigFile(vitepressDir: string): string | undefined;
+/** Read the config file statically (no execution). */
+export declare function readConfig(configPath: string): VitePressConfig;
+/**
+ * Read the config by IMPORTING it. Opt-in (`--eval-config`).
+ *
+ * SECURITY: this EXECUTES JavaScript/TypeScript from the source repository,
+ * and needs a loader that understands TS (`tsx`, or a `.mjs`/`.js` config).
+ * Acceptable for a local migration CLI pointed at a repo you already trust
+ * enough to `npm install`; not acceptable for untrusted input. All execution
+ * funnels through this one function so it can later be sandboxed.
+ */
+export declare function evalConfig(configPath: string): Promise<VitePressConfig>;

package/dist/config-node.js

@@ -0,0 +1,51 @@
+/**
+ * Node only: `.vitepress/config.*` on disk. `readConfig` reads it statically (no execution);
+ * `evalConfig` imports it, opt-in (`--eval-config`).
+ */
+import { existsSync, readFileSync } from "node:fs";
+import { join } from "node:path";
+import { pathToFileURL } from "node:url";
+import { asObject } from "@dogsbay/literal";
+import { parseConfig, shapeConfig } from "./config.js";
+const CONFIG_EXTS = [".ts", ".mts", ".mjs", ".js", ".cts", ".cjs"];
+/**
+ * Locate `.vitepress/config.*`.
+ *
+ * VitePress also permits `.vitepress/config/index.*` — the split-config layout
+ * used by larger sites (Element Plus, Vue's own docs).
+ */
+export function findConfigFile(vitepressDir) {
+    for (const ext of CONFIG_EXTS) {
+        const p = join(vitepressDir, "config" + ext);
+        if (existsSync(p))
+            return p;
+    }
+    for (const ext of CONFIG_EXTS) {
+        const p = join(vitepressDir, "config", "index" + ext);
+        if (existsSync(p))
+            return p;
+    }
+    return undefined;
+}
+/** Read the config file statically (no execution). */
+export function readConfig(configPath) {
+    return parseConfig(readFileSync(configPath, "utf-8"), configPath);
+}
+/**
+ * Read the config by IMPORTING it. Opt-in (`--eval-config`).
+ *
+ * SECURITY: this EXECUTES JavaScript/TypeScript from the source repository,
+ * and needs a loader that understands TS (`tsx`, or a `.mjs`/`.js` config).
+ * Acceptable for a local migration CLI pointed at a repo you already trust
+ * enough to `npm install`; not acceptable for untrusted input. All execution
+ * funnels through this one function so it can later be sandboxed.
+ */
+export async function evalConfig(configPath) {
+    const mod = (await import(pathToFileURL(configPath).href));
+    const raw = (mod.default ?? mod);
+    const root = asObject(raw);
+    if (!root) {
+        throw new Error(`${configPath}: default export is not an object`);
+    }
+    return shapeConfig(root, configPath, []);
+}

package/dist/config.d.ts

@@ -1,3 +1,13 @@
+/**
+ * Read `.vitepress/config.*` into the typed slice this importer needs. No Node: the text
+ * comes from the corpus (`config-node.ts` has the file-system half).
+ *
+ * STATICALLY, by default — see `@dogsbay/literal` for why. `--eval-config` swaps in
+ * a real `import()` for repos whose config outruns the literal subset AND
+ * whose dependencies are installed; that path executes code from the source
+ * repository and is therefore opt-in, never the default.
+ */
+import { type LiteralValue } from "@dogsbay/literal";
 /** A sidebar/nav entry as VitePress declares it. */
 export interface RawNavItem {
     text?: string;
@@ -22,27 +32,11 @@ export interface VitePressConfig {
     nav?: RawNavItem[];
     /** Locale keys other than `root`, so the loader can report what it skipped. */
     locales?: string[];
-    /** Absolute path of the config file that was read. */
+    /** The config file that was read (a corpus path, or absolute from `readConfig`). */
     configPath: string;
     /** Expressions the static reader could not evaluate. */
     unresolved: string[];
 }
-/**
- * Locate `.vitepress/config.*`.
- *
- * VitePress also permits `.vitepress/config/index.*` — the split-config layout
- * used by larger sites (Element Plus, Vue's own docs).
- */
-export declare function findConfigFile(vitepressDir: string): string | undefined;
-/** Read the config file statically (no execution). */
-export declare function readConfig(configPath: string): VitePressConfig;
-/**
- * Read the config by IMPORTING it. Opt-in (`--eval-config`).
- *
- * SECURITY: this EXECUTES JavaScript/TypeScript from the source repository,
- * and needs a loader that understands TS (`tsx`, or a `.mjs`/`.js` config).
- * Acceptable for a local migration CLI pointed at a repo you already trust
- * enough to `npm install`; not acceptable for untrusted input. All execution
- * funnels through this one function so it can later be sandboxed.
- */
-export declare function evalConfig(configPath: string): Promise<VitePressConfig>;
+export declare function shapeConfig(root: Record<string, LiteralValue>, configPath: string, unresolved: string[]): VitePressConfig;
+/** Read a config file's text statically (no execution). `configPath` is for messages. */
+export declare function parseConfig(src: string, configPath: string): VitePressConfig;

package/dist/config.js

@@ -1,38 +1,13 @@
 /**
- * Read `.vitepress/config.*` into the typed slice this importer needs.
+ * Read `.vitepress/config.*` into the typed slice this importer needs. No Node: the text
+ * comes from the corpus (`config-node.ts` has the file-system half).
  *
- * STATICALLY, by default — see `literal.ts` for why. `--eval-config` swaps in
+ * STATICALLY, by default — see `@dogsbay/literal` for why. `--eval-config` swaps in
  * a real `import()` for repos whose config outruns the literal subset AND
  * whose dependencies are installed; that path executes code from the source
  * repository and is therefore opt-in, never the default.
  */
-import { existsSync, readFileSync } from "node:fs";
-import { join } from "node:path";
-import { pathToFileURL } from "node:url";
-import { evaluateModule, asArray, asObject, asString, UNRESOLVED } from "./literal.js";
-const CONFIG_BASENAMES = ["config"];
-const CONFIG_EXTS = [".ts", ".mts", ".mjs", ".js", ".cts", ".cjs"];
-/**
- * Locate `.vitepress/config.*`.
- *
- * VitePress also permits `.vitepress/config/index.*` — the split-config layout
- * used by larger sites (Element Plus, Vue's own docs).
- */
-export function findConfigFile(vitepressDir) {
-    for (const base of CONFIG_BASENAMES) {
-        for (const ext of CONFIG_EXTS) {
-            const p = join(vitepressDir, base + ext);
-            if (existsSync(p))
-                return p;
-        }
-    }
-    for (const ext of CONFIG_EXTS) {
-        const p = join(vitepressDir, "config", "index" + ext);
-        if (existsSync(p))
-            return p;
-    }
-    return undefined;
-}
+import { evaluateModule, asArray, asObject, asString, UNRESOLVED } from "@dogsbay/literal";
 /**
  * VitePress merges `locales.root` over the top-level config, and each locale's
  * `themeConfig` over the top-level `themeConfig`. Vitest puts its entire
@@ -105,7 +80,7 @@ function toRawSidebar(v) {
     }
     return Object.keys(out).length > 0 ? out : undefined;
 }
-function shapeConfig(root, configPath, unresolved) {
+export function shapeConfig(root, configPath, unresolved) {
     const { theme, localeKeys } = mergedThemeConfig(root);
     const cfg = { configPath, unresolved };
     const title = asString(root.title);
@@ -146,9 +121,8 @@ function shapeConfig(root, configPath, unresolved) {
         cfg.locales = localeKeys;
     return cfg;
 }
-/** Read the config file statically (no execution). */
-export function readConfig(configPath) {
-    const src = readFileSync(configPath, "utf-8");
+/** Read a config file's text statically (no execution). `configPath` is for messages. */
+export function parseConfig(src, configPath) {
     const { value, unresolved } = evaluateModule(src);
     const root = asObject(value);
     if (!root) {
@@ -162,21 +136,3 @@ export function readConfig(configPath) {
     }
     return shapeConfig(root, configPath, unresolved);
 }
-/**
- * Read the config by IMPORTING it. Opt-in (`--eval-config`).
- *
- * SECURITY: this EXECUTES JavaScript/TypeScript from the source repository,
- * and needs a loader that understands TS (`tsx`, or a `.mjs`/`.js` config).
- * Acceptable for a local migration CLI pointed at a repo you already trust
- * enough to `npm install`; not acceptable for untrusted input. All execution
- * funnels through this one function so it can later be sandboxed.
- */
-export async function evalConfig(configPath) {
-    const mod = (await import(pathToFileURL(configPath).href));
-    const raw = (mod.default ?? mod);
-    const root = asObject(raw);
-    if (!root) {
-        throw new Error(`${configPath}: default export is not an object`);
-    }
-    return shapeConfig(root, configPath, []);
-}

package/dist/import.d.ts

@@ -0,0 +1,28 @@
+/**
+ * VitePress corpus → pages, nav, asset directories and a ledger, over a {@link Corpus} (no
+ * Node, quiet). The plugin's `import()` (`convert`, `site build`) and the browser
+ * (`./migrate`) both run it.
+ */
+import type { ExportPage, ImportLedgerEntry, NavItem } from "@dogsbay/types";
+import type { Corpus } from "@dogsbay/corpus";
+import { type VitepressAssetDir, type VitepressLoadOptions } from "./loaders/load.js";
+export interface VitepressCorpusImport {
+    pages: ExportPage[];
+    nav: NavItem[];
+    /** The project folder (holding `.vitepress`), relative to the corpus root. */
+    root: string;
+    /** The folder page slugs are relative to (`srcDir`), relative to the corpus root. */
+    srcDir: string;
+    navSource: "sidebar" | "directory";
+    /** Asset directories to mirror, relative to the corpus root. */
+    assetDirs: VitepressAssetDir[];
+    /** Site title from the config, when it had one. */
+    siteName?: string;
+    /** What the loader could not read or resolve (config, rewrites, snippets), as written. */
+    warnings: string[];
+    /** Vue component tag → occurrences removed. */
+    components: Record<string, number>;
+    /** Per-page constructs mapped with caveats, pages that failed, and the loader's warnings. */
+    ledger: ImportLedgerEntry[];
+}
+export declare function importVitepressCorpus(corpus: Corpus, opts?: VitepressLoadOptions): VitepressCorpusImport;

package/dist/import.js

@@ -0,0 +1,76 @@
+import { extractHeadings } from "@dogsbay/format-dogsbay-md/browser";
+import { dirOf } from "@dogsbay/detect";
+import { parseVitepress } from "./parse.js";
+import { loadVitepressCorpus, optionsForDir, titleFromSlug, } from "./loaders/load.js";
+export function importVitepressCorpus(corpus, opts = {}) {
+    const loaded = loadVitepressCorpus(corpus, opts);
+    const listed = new Set(corpus.paths);
+    const pages = [];
+    const components = {};
+    const ledger = [];
+    for (const ps of loaded.pages) {
+        try {
+            const content = corpus.text(ps.path);
+            if (content === undefined)
+                throw new Error("the file could not be read");
+            const tOpts = optionsForDir(corpus, listed, dirOf(ps.path), loaded.srcDir, loaded.root);
+            const { tree, frontmatter, body, ledger: notes, components: comps } = parseVitepress(content, tOpts);
+            for (const n of notes) {
+                ledger.push({ file: ps.path, line: n.line, severity: "warning", code: "unmapped-construct", message: `${n.construct}: ${n.note}` });
+            }
+            for (const [name, n] of Object.entries(comps)) {
+                components[name] = (components[name] ?? 0) + n;
+            }
+            const headings = extractHeadings(tree);
+            const h1 = headings.find((h) => h.depth === 1);
+            const fmTitle = typeof frontmatter.title === "string" && frontmatter.title.trim()
+                ? frontmatter.title.trim()
+                : undefined;
+            // A `layout: home` page carries its name in `hero.name`, not a heading.
+            const heroName = typeof frontmatter.hero?.name === "string"
+                ? (frontmatter.hero.name)
+                : undefined;
+            pages.push({
+                slug: ps.slug,
+                title: fmTitle || h1?.text || heroName || titleFromSlug(ps.slug),
+                tree,
+                headings,
+                frontmatter,
+                meta: (notes.length
+                    ? { vitepressLedger: notes }
+                    : {}),
+                bodyMarkdown: body,
+            });
+        }
+        catch (err) {
+            ledger.push({
+                file: ps.path,
+                severity: "warning",
+                code: "page-failed",
+                message: `not converted, skipped (slug "${ps.slug}"): ${err instanceof Error ? err.message : String(err)}`,
+            });
+        }
+    }
+    for (const w of loaded.warnings)
+        ledger.push({ severity: "warning", code: "vitepress-load", message: w });
+    const removed = Object.entries(components).sort((a, b) => b[1] - a[1] || a[0].localeCompare(b[0]));
+    if (removed.length) {
+        ledger.push({
+            severity: "info",
+            code: "vue-components-removed",
+            message: `Vue components removed: ${removed.map(([n, c]) => `${n}×${c}`).join(", ")}`,
+        });
+    }
+    return {
+        pages,
+        nav: loaded.nav,
+        root: loaded.root,
+        srcDir: loaded.srcDir,
+        navSource: loaded.navSource,
+        assetDirs: loaded.assetDirs,
+        ...(loaded.config.title ? { siteName: loaded.config.title } : {}),
+        warnings: loaded.warnings,
+        components,
+        ledger,
+    };
+}

package/dist/index.d.ts

@@ -5,13 +5,18 @@
  * containers, code-fence conventions, snippets and includes to Dogsbay-MD,
  * then parsing with the canonical dogsbay-md parser (zero new node types).
  *
- * Nav comes from `.vitepress/config.*`, read STATICALLY — see `literal.ts`.
+ * Nav comes from `.vitepress/config.*`, read STATICALLY — see `@dogsbay/literal`. The
+ * import runs over a corpus (`importVitepressCorpus`), so the CLI and the browser
+ * (`./migrate`) share it.
  *
  * See plans/format-vitepress.md.
  */
 export { parseVitepress, type ParseVitepressResult } from "./parse.js";
-export { vitepressToDogsbayMd, translateFenceInfo, splitRegion, type TranslateResult, type TranslateLedgerEntry, type TranslateOptions, type SnippetRequest, } from "./translate.js";
-export { findConfigFile, readConfig, evalConfig, type VitePressConfig, type RawNavItem, type RawSidebar, } from "./config.js";
-export { evaluateModule, UNRESOLVED, type EvalResult, type LiteralValue, } from "./literal.js";
+export { vitepressToDogsbayMd, translateFenceInfo, splitRegion, type TranslateResult, type TranslateLedgerEntry, type TranslateOptions, type SnippetRequest, type SnippetMiss, } from "./translate.js";
+export { parseConfig, type VitePressConfig, type RawNavItem, type RawSidebar } from "./config.js";
+export { findConfigFile, readConfig, evalConfig } from "./config-node.js";
+export { evaluateModule, UNRESOLVED, type EvalResult, type LiteralValue, } from "@dogsbay/literal";
 export { buildNav, itemsToNav, navFromSlugs, linkToSlug, slugToHref, type NavContext, } from "./nav.js";
-export { loadVitepress, detectVitepress, findVitepressDir, pathToSlug, globToRegExp, extractRegion, dedent, translateOptionsFor, titleFromSlug, type VitepressLoadResult, type VitepressPageSource, type VitepressLoadOptions, } from "./loaders/load.js";
+export { loadVitepress, detectVitepress, findVitepressDir, readVitepressFolder } from "./loaders/folder.js";
+export { importVitepressCorpus, type VitepressCorpusImport } from "./import.js";
+export { loadVitepressCorpus, findVitepressProject, optionsForDir, pathToSlug, globToRegExp, extractRegion, dedent, translateOptionsFor, titleFromSlug, type VitepressLoadResult, type VitepressPageSource, type VitepressLoadOptions, type VitepressAssetDir, } from "./loaders/load.js";

package/dist/index.js

@@ -5,13 +5,18 @@
  * containers, code-fence conventions, snippets and includes to Dogsbay-MD,
  * then parsing with the canonical dogsbay-md parser (zero new node types).
  *
- * Nav comes from `.vitepress/config.*`, read STATICALLY — see `literal.ts`.
+ * Nav comes from `.vitepress/config.*`, read STATICALLY — see `@dogsbay/literal`. The
+ * import runs over a corpus (`importVitepressCorpus`), so the CLI and the browser
+ * (`./migrate`) share it.
  *
  * See plans/format-vitepress.md.
  */
 export { parseVitepress } from "./parse.js";
 export { vitepressToDogsbayMd, translateFenceInfo, splitRegion, } from "./translate.js";
-export { findConfigFile, readConfig, evalConfig, } from "./config.js";
-export { evaluateModule, UNRESOLVED, } from "./literal.js";
+export { parseConfig } from "./config.js";
+export { findConfigFile, readConfig, evalConfig } from "./config-node.js";
+export { evaluateModule, UNRESOLVED, } from "@dogsbay/literal";
 export { buildNav, itemsToNav, navFromSlugs, linkToSlug, slugToHref, } from "./nav.js";
-export { loadVitepress, detectVitepress, findVitepressDir, pathToSlug, globToRegExp, extractRegion, dedent, translateOptionsFor, titleFromSlug, } from "./loaders/load.js";
+export { loadVitepress, detectVitepress, findVitepressDir, readVitepressFolder } from "./loaders/folder.js";
+export { importVitepressCorpus } from "./import.js";
+export { loadVitepressCorpus, findVitepressProject, optionsForDir, pathToSlug, globToRegExp, extractRegion, dedent, translateOptionsFor, titleFromSlug, } from "./loaders/load.js";

package/dist/loaders/folder.d.ts

@@ -0,0 +1,31 @@
+import { type FolderCorpus } from "@dogsbay/corpus/folder";
+import type { VitePressConfig } from "../config.js";
+import { type VitepressLoadResult } from "./load.js";
+/**
+ * `.vitepress/config.*` is the only unambiguous marker. Requiring it is what
+ * lets this plugin sit safely in the registry among the other Markdown
+ * importers: it cannot claim a plain-Markdown, MkDocs or GitBook corpus.
+ */
+export declare function findVitepressDir(source: string): string | undefined;
+export declare function detectVitepress(source: string): boolean;
+export interface VitepressFolder {
+    /** The project (the folder holding `.vitepress`) as a corpus. */
+    corpus: FolderCorpus;
+    /** The config, read statically or (`evalConfig`) by importing it. */
+    config: VitePressConfig;
+    warnings: string[];
+}
+/**
+ * The VitePress project under `source` as a corpus rooted at its project folder, with
+ * `srcDir` walked first (a `srcDir` reached through a link is listed under its own name).
+ */
+export declare function readVitepressFolder(source: string, opts?: {
+    evalConfig?: boolean;
+}): Promise<VitepressFolder>;
+/** `loadVitepressCorpus` over a folder, with the corpus it read. */
+export declare function loadVitepress(source: string, opts?: {
+    hrefPrefix?: string;
+    evalConfig?: boolean;
+}): Promise<VitepressLoadResult & {
+    corpus: FolderCorpus;
+}>;

package/dist/loaders/folder.js

@@ -0,0 +1,90 @@
+/**
+ * Node only: a VitePress project on disk as a corpus (`@dogsbay/corpus/folder`, rooted at the
+ * folder holding `.vitepress`, its `srcDir` walked first), and the CLI's on-disk detector.
+ * Everything else in the loader reads the corpus, so the CLI and the browser import run the
+ * same code.
+ */
+import { existsSync, readdirSync, statSync } from "node:fs";
+import { dirname, join } from "node:path";
+import { normalizePath } from "@dogsbay/detect";
+import { readFolder } from "@dogsbay/corpus/folder";
+import { evalConfig, findConfigFile, readConfig } from "../config-node.js";
+import { loadVitepressCorpus } from "./load.js";
+/**
+ * `.vitepress/config.*` is the only unambiguous marker. Requiring it is what
+ * lets this plugin sit safely in the registry among the other Markdown
+ * importers: it cannot claim a plain-Markdown, MkDocs or GitBook corpus.
+ */
+export function findVitepressDir(source) {
+    const candidates = [source, join(source, "docs"), join(source, "site"), join(source, "website")];
+    for (const dir of candidates) {
+        const vp = join(dir, ".vitepress");
+        if (existsSync(vp) && findConfigFile(vp))
+            return vp;
+    }
+    // One level down, for monorepos whose docs live in an unconventional dir.
+    let entries = [];
+    try {
+        entries = readdirSync(source).sort();
+    }
+    catch {
+        return undefined;
+    }
+    for (const name of entries) {
+        if (name.startsWith(".") || name === "node_modules")
+            continue;
+        const vp = join(source, name, ".vitepress");
+        try {
+            if (statSync(vp).isDirectory() && findConfigFile(vp))
+                return vp;
+        }
+        catch {
+            /* not a directory */
+        }
+    }
+    return undefined;
+}
+export function detectVitepress(source) {
+    try {
+        if (!existsSync(source) || !statSync(source).isDirectory())
+            return false;
+    }
+    catch {
+        return false;
+    }
+    return findVitepressDir(source) !== undefined;
+}
+/**
+ * The VitePress project under `source` as a corpus rooted at its project folder, with
+ * `srcDir` walked first (a `srcDir` reached through a link is listed under its own name).
+ */
+export async function readVitepressFolder(source, opts = {}) {
+    const vitepressDir = findVitepressDir(source);
+    if (!vitepressDir)
+        throw new Error(`No .vitepress/config.* found under ${source}`);
+    const configPath = findConfigFile(vitepressDir);
+    if (!configPath)
+        throw new Error(`No config file in ${vitepressDir}`);
+    const warnings = [];
+    let config;
+    if (opts.evalConfig) {
+        try {
+            config = await evalConfig(configPath);
+        }
+        catch (err) {
+            const msg = err instanceof Error ? err.message : String(err);
+            warnings.push(`--eval-config failed (${msg}); falling back to static reading`);
+            config = readConfig(configPath);
+        }
+    }
+    else {
+        config = readConfig(configPath);
+    }
+    const srcDir = config.srcDir ? normalizePath(config.srcDir) : undefined;
+    return { corpus: readFolder(dirname(vitepressDir), Infinity, srcDir ? [srcDir] : []), config, warnings };
+}
+/** `loadVitepressCorpus` over a folder, with the corpus it read. */
+export async function loadVitepress(source, opts = {}) {
+    const { corpus, config, warnings } = await readVitepressFolder(source, opts);
+    return { ...loadVitepressCorpus(corpus, { hrefPrefix: opts.hrefPrefix, config, warnings }), corpus };
+}