@dogsbay/format-gitbook 0.2.0-beta.130 → 0.2.0-beta.132

package/README.md

@@ -0,0 +1,23 @@
+# @dogsbay/format-gitbook
+
+GitBook (Git Sync) import for Dogsbay: the `{% %}` blocks translated to Dogsbay Markdown,
+`SUMMARY.md` as the navigation, `.gitbook.yaml` read as data. Nothing in the repository is run.
+
+| Entry | For |
+|---|---|
+| `@dogsbay/format-gitbook/migrate` | The browser: a corpus as a map of files → a Dogsbay project as a map of files. No Node |
+| `@dogsbay/format-gitbook` | The parts, with no Node: `parseGitbook`, `gitbookToDogsbayMd`, `importGitbookCorpus`, `gitbookProject` |
+| `@dogsbay/format-gitbook/cli` | Node: the `dogsbay` CLI's format plugin, and a folder as a corpus |
+
+```ts
+import { migrate } from "@dogsbay/format-gitbook/migrate";
+const { files, ledger, redirects } = await migrate({ files: corpus, siteName: "My Docs" });
+```
+
+The CLI's `dogsbay migrate-gitbook` runs the same import and project writer, so both give the
+same project. Find the corpus in a repository with `@dogsbay/detect`. See
+[Migrating from GitBook](https://github.com/dogsbay/dogsbay/blob/main/docs/migrating-gitbook.md).
+
+## License
+
+MIT

package/dist/cli.d.ts

@@ -1,14 +1,11 @@
-import type { FormatPlugin, ExportPage, NavItem } from "@dogsbay/types";
-export interface GitbookImportResult {
-    pages: ExportPage[];
-    nav: NavItem[];
-    redirects: Record<string, string>;
-    spaces: string[];
-    /** Docs roots to mirror non-`.md` assets from (dir + slug prefix). */
-    assetRoots: {
-        dir: string;
-        prefix: string;
-    }[];
-}
-export declare function importGitbook(source: string, opts: Record<string, unknown>): Promise<GitbookImportResult>;
+import type { FormatPlugin } from "@dogsbay/types";
+import { type GitbookImportResult } from "./import.js";
+import { type FolderCorpus } from "./loaders/folder.js";
+export { readFolder, readGitbookFolder, type FolderCorpus } from "./loaders/folder.js";
+export { gitbookProject, type GitbookProject, type GitbookProjectOptions } from "./project.js";
+export type { GitbookImportResult } from "./import.js";
+/** Import a GitBook folder. Prints a one-line summary of the ledger, as the CLI always has. */
+export declare function importGitbook(source: string, opts: Record<string, unknown>): Promise<GitbookImportResult & {
+    corpus: FolderCorpus;
+}>;
 export declare const plugin: FormatPlugin;

package/dist/cli.js

@@ -1,78 +1,38 @@
 /**
- * FormatPlugin for GitBook as a source format.
+ * FormatPlugin for GitBook as a source format (Node: reads a folder).
  *
- * Orchestrates: detect corpus → loadGitbook (config + SUMMARY + pages) →
- * translate each page (parseGitbook) → assemble ExportPage[] + NavItem[].
- * Fragments (`.gitbook/includes/*`) are emitted with `fragment: true` so
- * the CLI writes them as `{% include %}` targets, not routable pages —
- * the same fragment model AsciiBinder/Antora use.
+ * A folder becomes a {@link Corpus} (`loaders/folder.ts`), and the import itself is
+ * `importGitbookCorpus`, the same one the browser entry runs. Fragments
+ * (`.gitbook/includes/*`) come back with `fragment: true` so the CLI writes them as
+ * `{% include %}` targets, not routable pages.
  *
- * The redirects from `.gitbook.yaml` are surfaced on the result so
- * `migrate-gitbook` can carry them into the site config.
+ * The redirects from `.gitbook.yaml` are surfaced on the result so `migrate-gitbook` can
+ * carry them into the site.
  */
-import { existsSync, readFileSync } from "node:fs";
-import { basename } from "node:path";
-import { extractHeadings } from "@dogsbay/format-dogsbay-md";
-import { parseGitbook } from "./parse.js";
-import { loadGitbook, detectGitbook } from "./loaders/load.js";
-function prettify(slug) {
-    return slug
-        .split(/[-_/]/)
-        .filter(Boolean)
-        .map((w) => w.charAt(0).toUpperCase() + w.slice(1))
-        .join(" ");
-}
+import { existsSync } from "node:fs";
+import { importGitbookCorpus } from "./import.js";
+import { detectGitbook, readGitbookFolder } from "./loaders/folder.js";
+export { readFolder, readGitbookFolder } from "./loaders/folder.js";
+export { gitbookProject } from "./project.js";
+/** Import a GitBook folder. Prints a one-line summary of the ledger, as the CLI always has. */
 export async function importGitbook(source, opts) {
     if (!existsSync(source)) {
         throw new Error(`Source directory not found: ${source}`);
     }
     const space = typeof opts.space === "string" ? opts.space : undefined;
-    const hrefPrefix = typeof opts.hrefPrefix === "string" ? opts.hrefPrefix : "";
-    const { pages: pageSources, nav, redirects, spaces, assetRoots } = loadGitbook(source, {
+    const corpus = readGitbookFolder(source, space);
+    const result = importGitbookCorpus(corpus, {
         space,
-        hrefPrefix,
+        hrefPrefix: typeof opts.hrefPrefix === "string" ? opts.hrefPrefix : "",
     });
-    const pages = [];
-    let failed = 0;
-    let ledgerTotal = 0;
-    for (const ps of pageSources) {
-        try {
-            const content = readFileSync(ps.filePath, "utf-8");
-            const { tree, frontmatter, body, ledger } = parseGitbook(content);
-            ledgerTotal += ledger.length;
-            const headings = extractHeadings(tree);
-            const h1 = headings.find((h) => h.depth === 1);
-            // A whitespace-only source `title:` must not win — `.trim()` so a
-            // blank falls through to the H1 / slug (review #6).
-            const fmTitle = typeof frontmatter.title === "string" && frontmatter.title.trim()
-                ? frontmatter.title
-                : undefined;
-            const title = fmTitle || h1?.text || prettify(basename(ps.slug));
-            pages.push({
-                slug: ps.slug,
-                title,
-                tree,
-                headings,
-                frontmatter,
-                meta: {},
-                ...(ps.fragment ? { fragment: true } : {}),
-                // Translated Dogsbay-MD body — what migrate-gitbook writes to disk.
-                bodyMarkdown: body,
-            });
-        }
-        catch (err) {
-            failed += 1;
-            const msg = err instanceof Error ? err.message : String(err);
-            console.warn(`gitbook import: failed to convert ${ps.filePath} (slug "${ps.slug}"), skipping: ${msg}`);
-        }
-    }
-    if (failed > 0) {
-        console.warn(`gitbook import: ${failed} of ${pageSources.length} page(s) failed and were skipped`);
+    for (const e of result.ledger.filter((e) => e.code === "page-failed")) {
+        console.warn(`gitbook import: failed to convert ${e.file}, skipping: ${e.message}`);
     }
-    if (ledgerTotal > 0) {
-        console.warn(`gitbook import: ${ledgerTotal} construct(s) mapped with caveats (see per-page ledger)`);
+    const mapped = result.ledger.filter((e) => e.code === "unmapped-construct").length;
+    if (mapped > 0) {
+        console.warn(`gitbook import: ${mapped} construct(s) mapped with caveats (see the ledger)`);
     }
-    return { pages, nav, redirects, spaces, assetRoots };
+    return { ...result, corpus };
 }
 export const plugin = {
     name: "gitbook",
@@ -87,11 +47,11 @@ export const plugin = {
     ],
     exportOptions: [],
     async import(source, opts) {
-        const { pages, nav, assetRoots } = await importGitbook(source, opts);
-        // Slugs are relative to the space's docs root (`.gitbook.yaml` `root:`,
-        // or the `--space` folder), so references resolve there: a relative
-        // `:::openapi` spec or include looked up from the repo root missed.
-        const only = assetRoots.length === 1 && assetRoots[0].prefix === "" ? assetRoots[0].dir : undefined;
-        return { pages, nav, ...(only ? { contentRoot: only } : {}) };
+        const { pages, nav, assetRoots, ledger, corpus } = await importGitbook(source, opts);
+        // Slugs are relative to the space's docs root (`.gitbook.yaml` `root:`, or the `--space`
+        // folder), so references resolve there: a relative `:::openapi` spec or include looked up
+        // from the repo root missed.
+        const only = assetRoots.length === 1 && assetRoots[0].prefix === "" ? corpus.absolute(assetRoots[0].dir) : undefined;
+        return { pages, nav, ledger, ...(only ? { contentRoot: only } : {}) };
     },
 };

package/dist/corpus.d.ts

@@ -0,0 +1,2 @@
+/** The corpus an importer reads: `@dogsbay/corpus`, shared by every format's browser import. */
+export { corpusFromMap, type Corpus, type CorpusFiles } from "@dogsbay/corpus";

package/dist/corpus.js

@@ -0,0 +1,2 @@
+/** The corpus an importer reads: `@dogsbay/corpus`, shared by every format's browser import. */
+export { corpusFromMap } from "@dogsbay/corpus";

package/dist/import.d.ts

@@ -0,0 +1,27 @@
+/**
+ * GitBook corpus → pages, nav, redirects and a ledger, over a {@link Corpus} (no Node, quiet).
+ * The one import: the plugin's `import()` (`convert`, `site build`), `migrate-gitbook` and
+ * the browser (`./migrate`) all run it.
+ *
+ * Fragments (`.gitbook/includes/*`) come out with `fragment: true`, so a writer emits them as
+ * `{% include %}` targets, not routable pages (the fragment model AsciiBinder/Antora use).
+ */
+import type { ExportPage, ImportLedgerEntry, NavItem } from "@dogsbay/types";
+import type { Corpus } from "./corpus.js";
+import { type GitbookAssetRoot } from "./loaders/load.js";
+export interface GitbookImportOptions {
+    /** Import one space (a subfolder with a SUMMARY.md) of a multi-space repo. */
+    space?: string;
+    /** URL prefix applied to nav hrefs. */
+    hrefPrefix?: string;
+}
+export interface GitbookImportResult {
+    pages: ExportPage[];
+    nav: NavItem[];
+    redirects: Record<string, string>;
+    spaces: string[];
+    /** Docs roots to mirror non-`.md` assets from (corpus-relative folder + slug prefix). */
+    assetRoots: GitbookAssetRoot[];
+    ledger: ImportLedgerEntry[];
+}
+export declare function importGitbookCorpus(corpus: Corpus, opts?: GitbookImportOptions): GitbookImportResult;

package/dist/import.js

@@ -0,0 +1,62 @@
+import { extractHeadings } from "@dogsbay/format-dogsbay-md/browser";
+import { loadGitbookCorpus, prettify } from "./loaders/load.js";
+import { followRenames } from "./links.js";
+import { parseGitbook } from "./parse.js";
+export function importGitbookCorpus(corpus, opts = {}) {
+    const { pages: sources, nav, redirects, spaces, assetRoots } = loadGitbookCorpus(corpus, opts);
+    const pages = [];
+    const ledger = [];
+    // A page written under another file name (README.md → index.md, a landing page → index.md):
+    // links to it follow the rename.
+    const renames = new Map();
+    for (const ps of sources) {
+        if (ps.fragment)
+            continue;
+        const name = `${ps.slug.slice(ps.slug.lastIndexOf("/") + 1)}.md`;
+        if (name !== ps.path.slice(ps.path.lastIndexOf("/") + 1))
+            renames.set(ps.path, name);
+    }
+    for (const ps of sources) {
+        try {
+            const content = corpus.text(ps.path);
+            if (content === undefined)
+                throw new Error("the file could not be read");
+            const { tree, frontmatter, body, ledger: notes, bodyLine } = parseGitbook(content, { links: (body) => followRenames(body, ps.path, renames) });
+            for (const n of notes) {
+                ledger.push({
+                    file: ps.path,
+                    ...(n.line ? { line: n.line + bodyLine - 1 } : {}),
+                    severity: "warning",
+                    code: "unmapped-construct",
+                    message: `${n.construct}: ${n.note}`,
+                });
+            }
+            const headings = extractHeadings(tree);
+            const h1 = headings.find((h) => h.depth === 1);
+            // A whitespace-only source `title:` must not win — `.trim()` so a blank falls through
+            // to the H1 / slug (review #6).
+            const fmTitle = typeof frontmatter.title === "string" && frontmatter.title.trim() ? frontmatter.title : undefined;
+            const title = fmTitle || h1?.text || prettify(ps.slug.slice(ps.slug.lastIndexOf("/") + 1));
+            pages.push({
+                slug: ps.slug,
+                title,
+                tree,
+                headings,
+                frontmatter,
+                meta: {},
+                ...(ps.fragment ? { fragment: true } : {}),
+                // Translated Dogsbay-MD body — what the project writer writes.
+                bodyMarkdown: body,
+            });
+        }
+        catch (err) {
+            ledger.push({
+                file: ps.path,
+                severity: "warning",
+                code: "page-failed",
+                message: `not converted, skipped: ${err instanceof Error ? err.message : String(err)}`,
+            });
+        }
+    }
+    return { pages, nav, redirects, spaces, assetRoots, ledger };
+}

package/dist/index.d.ts

@@ -2,9 +2,13 @@
  * @dogsbay/format-gitbook — GitBook (Git Sync + legacy gitbook-cli)
  * format plugin. Imports GitBook corpora into TreeNode[] by translating
  * the Git Sync markdown dialect to Dogsbay-MD, then parsing with the
- * canonical dogsbay-md parser.
+ * canonical dogsbay-md parser. No Node in this entry or in `./migrate`;
+ * reading a folder is `./cli`.
  *
  * See plans/format-gitbook.md.
  */
 export { parseGitbook, type ParseGitbookResult } from "./parse.js";
 export { gitbookToDogsbayMd, type TranslateResult, type TranslateLedgerEntry, } from "./translate.js";
+export { corpusFromMap, type Corpus, type CorpusFiles } from "./corpus.js";
+export { importGitbookCorpus, type GitbookImportOptions, type GitbookImportResult } from "./import.js";
+export { gitbookProject, type GitbookProject, type GitbookProjectOptions } from "./project.js";

package/dist/index.js

@@ -2,9 +2,13 @@
  * @dogsbay/format-gitbook — GitBook (Git Sync + legacy gitbook-cli)
  * format plugin. Imports GitBook corpora into TreeNode[] by translating
  * the Git Sync markdown dialect to Dogsbay-MD, then parsing with the
- * canonical dogsbay-md parser.
+ * canonical dogsbay-md parser. No Node in this entry or in `./migrate`;
+ * reading a folder is `./cli`.
  *
  * See plans/format-gitbook.md.
  */
 export { parseGitbook } from "./parse.js";
 export { gitbookToDogsbayMd, } from "./translate.js";
+export { corpusFromMap } from "./corpus.js";
+export { importGitbookCorpus } from "./import.js";
+export { gitbookProject } from "./project.js";

package/dist/links.d.ts

@@ -0,0 +1,4 @@
+/** Corpus path of a page → the file name it is written under, when that differs. */
+export type Renames = Map<string, string>;
+/** Rewrite the page links in `markdown`, a page at corpus path `from`. */
+export declare function followRenames(markdown: string, from: string, renames: Renames): string;

package/dist/links.js

@@ -0,0 +1,64 @@
+/**
+ * Page links that follow a renamed file. The migration writes `README.md` as `index.md`, and a
+ * space's landing page (`structure.readme: intro.md`) as `index.md` too, in the same folder.
+ * A link that named the old file (`guide/README.md`, `../intro.md#setup`) would then name
+ * nothing, so it is rewritten to the new file name; everything else is left as written.
+ *
+ * Text work over the translated Dogsbay MD, before it is parsed, so the written page and the
+ * tree agree. Fenced code and code spans are left alone: a page that SHOWS a link keeps it.
+ */
+import { dirOf, joinPath, normalizePath } from "@dogsbay/detect";
+const FENCE_RE = /^\s*(`{3,}|~{3,})/; // any indent: fences sit inside list items and directives
+/** `](dest)` / `](<dest>)`, a reference definition `[x]: dest`, and `href="dest"`. */
+const DEST_RE = /(\]\(\s*)(<[^>\n]*>|[^)\s]+)|(^ {0,3}\[[^\]\n]+\]:\s*)(<[^>\n]*>|\S+)|(\bhref=")([^"\n]*)(")/g;
+/** Rewrite the page links in `markdown`, a page at corpus path `from`. */
+export function followRenames(markdown, from, renames) {
+    if (renames.size === 0)
+        return markdown;
+    const base = dirOf(from);
+    let fence;
+    return markdown
+        .split("\n")
+        .map((line) => {
+        const f = FENCE_RE.exec(line);
+        if (fence) {
+            if (f && f[1][0] === fence[0] && f[1].length >= fence.length && line.trim() === f[1])
+                fence = undefined;
+            return line;
+        }
+        if (f) {
+            fence = f[1];
+            return line;
+        }
+        // Code spans stay as written: rewrite only the text between them
+        return line
+            .split(/(`+[^`]*`+)/)
+            .map((part, i) => (i % 2 ? part : part.replace(DEST_RE, (m, ...g) => rewrite(m, g, base, renames))))
+            .join("");
+    })
+        .join("\n");
+}
+function rewrite(match, g, base, renames) {
+    const [pre, dest, close] = g[0] !== undefined ? [g[0], g[1], ""] : g[2] !== undefined ? [g[2], g[3], ""] : [g[4], g[5], g[6]];
+    const angled = dest.startsWith("<") && dest.endsWith(">");
+    const raw = angled ? dest.slice(1, -1) : dest;
+    const cut = raw.search(/[#?]/);
+    const file = cut < 0 ? raw : raw.slice(0, cut);
+    // Only relative paths: not a scheme, a site path, or a bare #fragment
+    if (!file || /^[a-z][a-z0-9+.-]*:/i.test(file) || file.startsWith("/"))
+        return match;
+    let decoded = file;
+    try {
+        decoded = decodeURIComponent(file);
+    }
+    catch {
+        // keep it as written
+    }
+    const target = normalizePath(joinPath(base, decoded.replace(/^\.\//, "")));
+    const name = target === undefined ? undefined : renames.get(target);
+    if (name === undefined)
+        return match;
+    const slash = file.lastIndexOf("/");
+    const next = `${file.slice(0, slash + 1)}${name}${cut < 0 ? "" : raw.slice(cut)}`;
+    return `${pre}${angled ? `<${next}>` : next}${close}`;
+}

package/dist/loaders/config.d.ts

@@ -4,5 +4,5 @@ export interface GitbookConfig {
     summary: string;
     redirects: Record<string, string>;
 }
-/** Read `.gitbook.yaml` from `dir` if present; else return defaults. */
-export declare function readGitbookConfig(dir: string): GitbookConfig;
+/** Read a `.gitbook.yaml`'s text (undefined: no file); defaults for anything absent or unreadable. */
+export declare function parseGitbookConfig(text: string | undefined): GitbookConfig;

package/dist/loaders/config.js

@@ -8,24 +8,24 @@
  *     summary: SUMMARY.md    # table of contents, default SUMMARY.md
  *   redirects:
  *     old/path: new/page.md  # old URL → target md file
+ *
+ * js-yaml, not `yaml`: the playground already ships it, and its `load` reads plain data only
+ * (no custom tags), which is all `.gitbook.yaml` holds.
  */
-import { existsSync, readFileSync } from "node:fs";
-import { join } from "node:path";
-import YAML from "yaml";
+import * as yaml from "js-yaml";
 const DEFAULTS = {
     root: "./",
     readme: "README.md",
     summary: "SUMMARY.md",
     redirects: {},
 };
-/** Read `.gitbook.yaml` from `dir` if present; else return defaults. */
-export function readGitbookConfig(dir) {
-    const p = join(dir, ".gitbook.yaml");
-    if (!existsSync(p))
+/** Read a `.gitbook.yaml`'s text (undefined: no file); defaults for anything absent or unreadable. */
+export function parseGitbookConfig(text) {
+    if (text === undefined)
         return { ...DEFAULTS };
     let parsed;
     try {
-        parsed = YAML.parse(readFileSync(p, "utf-8"));
+        parsed = yaml.load(text);
     }
     catch {
         return { ...DEFAULTS };

package/dist/loaders/folder.d.ts

@@ -0,0 +1,19 @@
+import { readFolder, type FolderCorpus } from "@dogsbay/corpus/folder";
+import { type GitbookConfig } from "./config.js";
+import { type GitbookLoadOptions, type GitbookLoadResult } from "./load.js";
+export { readFolder, type FolderCorpus };
+/** Read `.gitbook.yaml` from `dir` if present; else return defaults. */
+export declare function readGitbookConfig(dir: string): GitbookConfig;
+/**
+ * Does this directory look like a GitBook corpus? The importer's own rule (a marker at the
+ * top, or subfolders with a SUMMARY.md), over the folder's top two levels, through the shared
+ * path detector (so an mdBook's `src/SUMMARY.md` beside `book.toml` is not claimed).
+ */
+export declare function detectGitbook(sourceDir: string): boolean;
+/**
+ * A GitBook folder as a corpus, its docs roots walked first: the spaces and each one's
+ * `.gitbook.yaml` `root:` are read from the top two levels, the same rule the import applies.
+ */
+export declare function readGitbookFolder(sourceDir: string, space?: string): FolderCorpus;
+/** `loadGitbookCorpus` over a folder. */
+export declare function loadGitbook(sourceDir: string, opts?: GitbookLoadOptions): GitbookLoadResult;

package/dist/loaders/folder.js

@@ -0,0 +1,56 @@
+/**
+ * Node only: a GitBook folder as a corpus (`@dogsbay/corpus/folder`, its docs roots 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, readFileSync, statSync } from "node:fs";
+import { join } from "node:path";
+import { detectGitbook as detectGitbookPaths, gitbookSpaces, joinPath, normalizePath } from "@dogsbay/detect";
+import { readFolder } from "@dogsbay/corpus/folder";
+import { parseGitbookConfig } from "./config.js";
+import { loadGitbookCorpus } from "./load.js";
+export { readFolder };
+/** Read `.gitbook.yaml` from `dir` if present; else return defaults. */
+export function readGitbookConfig(dir) {
+    const p = join(dir, ".gitbook.yaml");
+    return parseGitbookConfig(existsSync(p) ? readFileSync(p, "utf-8") : undefined);
+}
+/**
+ * Does this directory look like a GitBook corpus? The importer's own rule (a marker at the
+ * top, or subfolders with a SUMMARY.md), over the folder's top two levels, through the shared
+ * path detector (so an mdBook's `src/SUMMARY.md` beside `book.toml` is not claimed).
+ */
+export function detectGitbook(sourceDir) {
+    try {
+        if (!existsSync(sourceDir) || !statSync(sourceDir).isDirectory())
+            return false;
+    }
+    catch {
+        return false;
+    }
+    const { paths } = readFolder(sourceDir, 1);
+    return detectGitbookPaths(paths) !== undefined && gitbookSpaces(paths).length > 0;
+}
+/**
+ * A GitBook folder as a corpus, its docs roots walked first: the spaces and each one's
+ * `.gitbook.yaml` `root:` are read from the top two levels, the same rule the import applies.
+ */
+export function readGitbookFolder(sourceDir, space) {
+    const top = readFolder(sourceDir, 1);
+    const spaces = space ? [space] : gitbookSpaces(top.paths);
+    const roots = [];
+    for (const s of spaces.length ? spaces : ["."]) {
+        const spaceDir = normalizePath(s);
+        if (spaceDir === undefined)
+            continue;
+        const { root } = parseGitbookConfig(top.text(joinPath(spaceDir, ".gitbook.yaml")));
+        const docsDir = root && root !== "./" ? normalizePath(joinPath(spaceDir, root)) : spaceDir;
+        if (docsDir)
+            roots.push(docsDir);
+    }
+    return readFolder(sourceDir, Infinity, roots);
+}
+/** `loadGitbookCorpus` over a folder. */
+export function loadGitbook(sourceDir, opts = {}) {
+    return loadGitbookCorpus(readGitbookFolder(sourceDir, opts.space), opts);
+}

package/dist/loaders/load.d.ts

@@ -1,13 +1,30 @@
+/**
+ * GitBook corpus loader, over a {@link Corpus} (no Node): find the spaces, read each
+ * `.gitbook.yaml`, parse `SUMMARY.md` for nav, list every page (including orphans not in the
+ * summary), and surface redirects + include fragments. The CLI runs it over a folder
+ * (`folder.ts`), the playground over a map of files.
+ *
+ * Multi-space corpora (e.g. snyk/user-docs holds six spaces, each a dir with its own
+ * SUMMARY.md) are detected by `gitbookSpaces` (@dogsbay/detect, the rule detection uses too):
+ * when the corpus root has no marker, every direct subfolder with a SUMMARY.md is a space. The
+ * default import concatenates all spaces (each summary's nav becomes a top-level section);
+ * `space` selects one.
+ *
+ * Paths are posix and relative to the corpus root. Pages come out in path order, so the same
+ * corpus always gives the same result (a folder's listing order is the file system's).
+ */
 import type { NavItem } from "@dogsbay/types";
+import type { Corpus } from "../corpus.js";
 export interface GitbookPageSource {
-    filePath: string;
+    /** The page's file, relative to the corpus root. */
+    path: string;
     slug: string;
     /** True for `.gitbook/includes/*` — mirrored as a fragment, not a page. */
     fragment?: boolean;
 }
 /** A resolved docs root to mirror assets from, and its slug prefix. */
 export interface GitbookAssetRoot {
-    /** Absolute docs directory (space dir + `.gitbook.yaml` `root:`). */
+    /** Docs folder (space folder + `.gitbook.yaml` `root:`), relative to the corpus root. */
     dir: string;
     /** Slug prefix for pages/assets under this root ("" or "<space>/"). */
     prefix: string;
@@ -16,17 +33,16 @@ export interface GitbookLoadResult {
     pages: GitbookPageSource[];
     nav: NavItem[];
     redirects: Record<string, string>;
-    /** Space directories detected (relative to source); ≥2 ⇒ multi-space. */
+    /** Space directories detected (relative to the corpus root); ≥2 ⇒ multi-space. */
     spaces: string[];
     /** Docs roots to mirror non-`.md` assets from, with their slug prefix. */
     assetRoots: GitbookAssetRoot[];
 }
 export interface GitbookLoadOptions {
-    /** Restrict to a single space directory (relative to source root). */
+    /** Restrict to a single space directory (relative to the corpus root). */
     space?: string;
     /** URL prefix applied to nav hrefs. */
     hrefPrefix?: string;
 }
-/** Does this directory look like a GitBook corpus? */
-export declare function detectGitbook(sourceDir: string): boolean;
-export declare function loadGitbook(sourceDir: string, opts?: GitbookLoadOptions): GitbookLoadResult;
+export declare function loadGitbookCorpus(corpus: Corpus, opts?: GitbookLoadOptions): GitbookLoadResult;
+export declare function prettify(s: string): string;

package/dist/loaders/load.js

@@ -1,163 +1,35 @@
-/**
- * GitBook corpus loader — discover the docs root, read `.gitbook.yaml`,
- * parse `SUMMARY.md` for nav, enumerate every page (including orphans not
- * in the summary), and surface redirects + include fragments.
- *
- * Multi-space corpora (e.g. snyk/user-docs holds six spaces, each a dir
- * with its own SUMMARY.md) are detected: when the caller doesn't point at
- * a single space, every dir containing a SUMMARY.md is a space. The
- * default import concatenates all spaces (each summary's nav becomes a
- * top-level section); `--space <dir>` selects one.
- */
-import { existsSync, readdirSync, readFileSync, realpathSync, statSync } from "node:fs";
-import { basename, join, relative, sep } from "node:path";
-import { readGitbookConfig } from "./config.js";
+import { gitbookSpaces, gitbookVisible, joinPath, normalizePath, within } from "@dogsbay/detect";
+import { parseGitbookConfig } from "./config.js";
 import { parseSummary, pathToSlug } from "./summary.js";
-/** Does this directory look like a GitBook corpus? */
-export function detectGitbook(sourceDir) {
-    if (!existsSync(sourceDir))
-        return false;
-    try {
-        if (!statSync(sourceDir).isDirectory())
-            return false;
-    }
-    catch {
-        return false;
-    }
-    // A .gitbook.yaml anywhere near the top, or a SUMMARY.md, is the signal.
-    if (existsSync(join(sourceDir, ".gitbook.yaml")))
-        return true;
-    if (existsSync(join(sourceDir, "SUMMARY.md")))
-        return true;
-    // Or a single-level space dir carrying either marker.
-    return findSpaces(sourceDir).length > 0;
-}
 /**
- * Directories (relative) that contain a SUMMARY.md — each is a space.
- *
- * If the ROOT itself has a SUMMARY.md, the corpus is single-space and we
- * return just `["."]` — we do NOT also scan subdirectories, because a
- * nested `SUMMARY.md` (e.g. a stray one under `api/`) would otherwise be
- * misread as a second space, duplicating that subtree's pages and adding
- * a phantom top-level nav section (review #8). Multi-space is the
- * monorepo shape where the root has NO SUMMARY.md but ≥1 subdir does.
+ * The pages under one docs folder: every visible `.md` but SUMMARY and GLOSSARY, and only what
+ * stays in that folder once links resolve (a link from the docs root elsewhere in the repo
+ * does not bring pages in).
  */
-function findSpaces(sourceDir) {
-    if (existsSync(join(sourceDir, "SUMMARY.md")) || existsSync(join(sourceDir, ".gitbook.yaml"))) {
-        return ["."];
-    }
+function pagesUnder(corpus, paths, docsDir, landing) {
     const out = [];
-    const seen = new Set();
-    const consider = (dir) => {
-        if (existsSync(join(dir, "SUMMARY.md"))) {
-            const rel = relative(sourceDir, dir) || ".";
-            if (!seen.has(rel)) {
-                seen.add(rel);
-                out.push(rel);
-            }
-        }
-    };
-    // One level down (the snyk monorepo shape: docs/, platform-administration/…).
-    let entries = [];
-    try {
-        entries = readdirSync(sourceDir);
-    }
-    catch {
-        return out;
-    }
-    for (const name of entries) {
-        if (name.startsWith(".") || name === "node_modules")
+    for (const path of paths) {
+        if (!within(path, docsDir) || path === docsDir)
             continue;
-        const full = join(sourceDir, name);
-        try {
-            if (statSync(full).isDirectory())
-                consider(full);
-        }
-        catch {
-            /* ignore */
-        }
-    }
-    return out;
-}
-/** Walk `spaceDir` for every `.md` file; classify includes as fragments. */
-/** Is `p` (once links resolve) `dir` or inside it? False when either does not exist. */
-function insideDir(p, dir) {
-    try {
-        const real = realpathSync(p);
-        const root = realpathSync(dir);
-        return real === root || real.startsWith(root + sep);
-    }
-    catch {
-        return !existsSync(p);
-    }
-}
-function walkPages(spaceDir, sourceDir) {
-    const out = [];
-    // Inside the docs root once links resolve, and each directory once: a
-    // symlink out of the repo read pages from elsewhere, and two links to `.`
-    // made the walk branch twice per level until ELOOP (about 2^40 visits).
-    let realRoot;
-    try {
-        realRoot = realpathSync(spaceDir);
-    }
-    catch {
-        return out;
+        if (corpus.contains && !corpus.contains(path, docsDir))
+            continue;
+        const rel = docsDir ? path.slice(docsDir.length + 1) : path;
+        if (!gitbookVisible(rel))
+            continue;
+        const name = rel.slice(rel.lastIndexOf("/") + 1);
+        if (!name.toLowerCase().endsWith(".md"))
+            continue;
+        if (name === "SUMMARY.md" || name === "GLOSSARY.md")
+            continue;
+        out.push({ path, slug: pathToSlug(rel, landing), ...(rel.includes(".gitbook/includes/") ? { fragment: true } : {}) });
     }
-    const seen = new Set([realRoot]);
-    const walk = (dir) => {
-        let entries;
-        try {
-            entries = readdirSync(dir);
-        }
-        catch {
-            return;
-        }
-        for (const name of entries) {
-            if (name === "node_modules")
-                continue;
-            const full = join(dir, name);
-            let st;
-            let real;
-            try {
-                real = realpathSync(full);
-                if (real !== realRoot && !real.startsWith(realRoot + sep))
-                    continue;
-                st = statSync(real);
-            }
-            catch {
-                continue;
-            }
-            if (st.isDirectory()) {
-                // Hidden dirs are skipped EXCEPT `.gitbook` (holds includes).
-                if (name.startsWith(".") && name !== ".gitbook")
-                    continue;
-                if (seen.has(real))
-                    continue;
-                seen.add(real);
-                walk(full);
-                continue;
-            }
-            if (!name.toLowerCase().endsWith(".md"))
-                continue;
-            if (name === "SUMMARY.md" || name === "GLOSSARY.md")
-                continue;
-            const relFromSpace = relative(spaceDir, full).replace(/\\/g, "/");
-            const isInclude = relFromSpace.includes(".gitbook/includes/");
-            out.push({
-                filePath: full,
-                slug: pathToSlug(relFromSpace),
-                ...(isInclude ? { fragment: true } : {}),
-            });
-        }
-    };
-    walk(spaceDir);
     return out;
 }
-export function loadGitbook(sourceDir, opts = {}) {
+export function loadGitbookCorpus(corpus, opts = {}) {
     const hrefPrefix = opts.hrefPrefix ?? "";
-    const allSpaces = findSpaces(sourceDir);
-    // Which spaces to load: an explicit --space, else all detected (or the
-    // root itself if none matched).
+    const paths = [...corpus.paths].sort();
+    const allSpaces = gitbookSpaces(paths);
+    // Which spaces to load: an explicit `space`, else all detected (or the root itself if none matched).
     let spaces = opts.space ? [opts.space] : allSpaces;
     if (spaces.length === 0)
         spaces = ["."];
@@ -167,33 +39,38 @@ export function loadGitbook(sourceDir, opts = {}) {
     const assetRoots = [];
     const multi = spaces.length > 1;
     for (const space of spaces) {
-        const spaceDir = space === "." ? sourceDir : join(sourceDir, space);
-        if (!existsSync(spaceDir))
+        const spaceDir = normalizePath(space);
+        if (spaceDir === undefined)
+            throw new Error(`space "${space}" is outside the source directory`);
+        if (spaceDir && !paths.some((p) => within(p, spaceDir)))
             continue;
-        const config = readGitbookConfig(spaceDir);
-        // `root:` relocates the docs dir within the space.
-        const docsDir = config.root && config.root !== "./" ? join(spaceDir, config.root) : spaceDir;
-        // `root:` comes from the repo being imported: it may not lead out of it.
-        if (!insideDir(docsDir, sourceDir)) {
+        const config = parseGitbookConfig(corpus.text(joinPath(spaceDir, ".gitbook.yaml")));
+        // `root:` relocates the docs dir within the space. It comes from the repo being imported:
+        // it may not lead out of it.
+        const docsDir = config.root && config.root !== "./" ? normalizePath(joinPath(spaceDir, config.root)) : spaceDir;
+        if (docsDir === undefined) {
             throw new Error(`.gitbook.yaml in ${space === "." ? "the source" : space}: root "${config.root}" is outside the source directory`);
         }
+        // `structure.readme` names the home page when it is not README.md (`readme: intro.md`).
+        // It becomes `index`, like a README; one that is not in the docs root is ignored.
+        const readme = normalizePath(config.readme);
+        const landing = readme && !/^readme\.md$/i.test(readme) && paths.includes(joinPath(docsDir, readme)) ? readme : undefined;
         // Page prefix so multi-space slugs don't collide (space dir name).
-        const slugPrefix = multi && space !== "." ? `${space}/` : "";
+        const slugPrefix = multi && spaceDir ? `${spaceDir}/` : "";
         assetRoots.push({ dir: docsDir, prefix: slugPrefix });
-        for (const p of walkPages(docsDir, docsDir)) {
+        for (const p of pagesUnder(corpus, paths, docsDir, landing)) {
             pages.push({ ...p, slug: `${slugPrefix}${p.slug}`.replace(/\/+/g, "/") });
         }
         // Nav from SUMMARY.md (under docsDir per config.summary).
-        const summaryPath = join(docsDir, config.summary);
+        const summaryPath = normalizePath(joinPath(docsDir, config.summary));
+        const summary = summaryPath === undefined ? undefined : corpus.text(summaryPath);
         const navPrefix = `${hrefPrefix}${slugPrefix ? "/" + slugPrefix.replace(/\/$/, "") : ""}`;
-        if (existsSync(summaryPath)) {
-            const parsed = parseSummary(readFileSync(summaryPath, "utf-8"), navPrefix);
-            if (multi) {
+        if (summary !== undefined) {
+            const parsed = parseSummary(summary, navPrefix, landing);
+            if (multi)
                 nav.push({ label: prettify(space), children: parsed.nav });
-            }
-            else {
+            else
                 nav.push(...parsed.nav);
-            }
         }
         else {
             // No SUMMARY.md — infer nav from folder structure (paths → slugs).
@@ -203,13 +80,14 @@ export function loadGitbook(sourceDir, opts = {}) {
             else
                 nav.push(...inferred);
         }
-        // Redirect keys (old URL) AND values (target .md) are relative to the
-        // space, so BOTH get the space slug prefix in a multi-space import —
-        // else a redirect in space `docs` would point at an unprefixed target
-        // that doesn't exist under `docs/`.
+        // Redirect keys (old URL) AND values (target .md) are relative to the space, so BOTH get
+        // the space slug prefix in a multi-space import — else a redirect in space `docs` would
+        // point at an unprefixed target that doesn't exist under `docs/`.
         for (const [k, v] of Object.entries(config.redirects)) {
             const key = slugPrefix ? `${slugPrefix}${k}` : k;
-            const val = slugPrefix ? `${slugPrefix}${v.replace(/^\.\//, "")}` : v;
+            // A redirect to the landing page goes to the space's home, as one to its README does
+            const target = landing && normalizePath(v) === landing ? "README.md" : v;
+            const val = slugPrefix ? `${slugPrefix}${target.replace(/^\.\//, "")}` : target;
             redirects[key] = val;
         }
     }
@@ -219,10 +97,10 @@ export function loadGitbook(sourceDir, opts = {}) {
 function inferNavFromPages(pages) {
     return pages
         .filter((p) => p.slug !== "index")
-        .map((p) => ({ label: prettify(basename(p.slug)), href: `/${p.slug}` }))
+        .map((p) => ({ label: prettify(p.slug.slice(p.slug.lastIndexOf("/") + 1)), href: `/${p.slug}` }))
         .sort((a, b) => a.label.localeCompare(b.label));
 }
-function prettify(s) {
+export function prettify(s) {
     return s
         .split(/[-_/]/)
         .filter(Boolean)

package/dist/loaders/summary.d.ts

@@ -22,6 +22,10 @@ export interface ParsedSummary {
     /** Every local page path referenced by the summary (posix, .md kept). */
     referenced: string[];
 }
-/** Normalize a GitBook page path to a Dogsbay slug (README → index). */
-export declare function pathToSlug(relPath: string): string;
-export declare function parseSummary(content: string, hrefPrefix?: string): ParsedSummary;
+/**
+ * Normalize a GitBook page path to a Dogsbay slug (README → index). `landing` is a space's
+ * `.gitbook.yaml` `structure.readme` when it is not README.md: that page is the home page, and
+ * a README.md beside it is an ordinary page, `readme`.
+ */
+export declare function pathToSlug(relPath: string, landing?: string): string;
+export declare function parseSummary(content: string, hrefPrefix?: string, landing?: string): ParsedSummary;

package/dist/loaders/summary.js

@@ -1,6 +1,16 @@
-/** Normalize a GitBook page path to a Dogsbay slug (README → index). */
-export function pathToSlug(relPath) {
+/**
+ * Normalize a GitBook page path to a Dogsbay slug (README → index). `landing` is a space's
+ * `.gitbook.yaml` `structure.readme` when it is not README.md: that page is the home page, and
+ * a README.md beside it is an ordinary page, `readme`.
+ */
+export function pathToSlug(relPath, landing) {
     let p = relPath.replace(/\\/g, "/").replace(/^\.\//, "").replace(/\.md$/i, "");
+    if (landing !== undefined) {
+        if (p === landing.replace(/\.md$/i, ""))
+            return "index";
+        if (p === "README" || p === "readme")
+            return "readme";
+    }
     if (p === "README" || p === "readme")
         return "index";
     p = p.replace(/\/README$/i, "/index");
@@ -16,7 +26,7 @@ const LINK_RE = /^\[([^\]]*)\]\(\s*(?:<([^>]*)>|([^)\s]+))[^)]*\)/;
 const EXTERNAL_RE = /^(https?:\/\/|mailto:|tel:)/i;
 // Strip a trailing `<a href id>` anchor GitBook adds to group headings.
 const ANCHOR_TAIL_RE = /\s*<a\b[^>]*><\/a>\s*$/;
-export function parseSummary(content, hrefPrefix = "") {
+export function parseSummary(content, hrefPrefix = "", landing) {
     const referenced = [];
     const top = [];
     // Current group container the following items attach to (null = top level).
@@ -43,7 +53,7 @@ export function parseSummary(content, hrefPrefix = "") {
         if (!it)
             continue;
         const indent = it[1].replace(/\t/g, "    ").length;
-        const item = parseItem(it[2], hrefPrefix, referenced);
+        const item = parseItem(it[2], hrefPrefix, referenced, landing);
         if (!item)
             continue;
         // Attach by indentation. Pop deeper-or-equal entries; the remaining
@@ -62,7 +72,7 @@ export function parseSummary(content, hrefPrefix = "") {
     strip(top);
     return { nav: top, referenced };
 }
-function parseItem(text, hrefPrefix, referenced) {
+function parseItem(text, hrefPrefix, referenced, landing) {
     const m = text.match(LINK_RE);
     if (!m) {
         // A plain-text item (no link) — a group-ish header without a page.
@@ -79,7 +89,7 @@ function parseItem(text, hrefPrefix, referenced) {
     const frag = hashIdx === -1 ? "" : target.slice(hashIdx);
     if (filePart)
         referenced.push(filePart.replace(/^\.\//, ""));
-    const slug = pathToSlug(filePart);
+    const slug = pathToSlug(filePart, landing);
     const href = `${hrefPrefix}/${slug}`.replace(/\/+/g, "/");
     return { label, href: `${href}${frag}` };
 }

package/dist/migrate.d.ts

@@ -0,0 +1,32 @@
+/**
+ * `@dogsbay/format-gitbook/migrate` — the browser entry. A GitBook corpus as a map of files →
+ * a Dogsbay project as a map of files: the same import and project writer `dogsbay
+ * migrate-gitbook` runs, without the Astro scaffold. No Node, nothing from the corpus is run,
+ * no console, clock or network. Find the corpus with `@dogsbay/detect` first.
+ */
+import type { ImportLedgerEntry } from "@dogsbay/types";
+import { type CorpusFiles } from "./corpus.js";
+export type { CorpusFiles } from "./corpus.js";
+export interface MigrateInput {
+    /** The corpus: paths relative to its root (a detection's `root`), text or bytes. */
+    files: CorpusFiles;
+    /** One space of a multi-space repo (a detection's `choices.spaces`); all when omitted. */
+    choose?: {
+        space?: string;
+    };
+    siteName?: string;
+    siteUrl?: string;
+    /** Where the corpus came from, for MIGRATION.md (e.g. the repo URL). */
+    sourceLabel?: string;
+}
+export interface MigrateResult {
+    /** The Dogsbay project: dogsbay.config.yml, content/** (pages, nav.yml, assets), MIGRATION.md. */
+    files: Map<string, string | Uint8Array>;
+    ledger: ImportLedgerEntry[];
+    /** Old URL → served URL, both root-absolute; the host decides how to serve them. */
+    redirects: {
+        from: string;
+        to: string;
+    }[];
+}
+export declare function migrate(input: MigrateInput): Promise<MigrateResult>;

package/dist/migrate.js

@@ -0,0 +1,19 @@
+import { corpusFromMap } from "./corpus.js";
+import { importGitbookCorpus } from "./import.js";
+import { gitbookProject } from "./project.js";
+export async function migrate(input) {
+    const corpus = corpusFromMap(input.files);
+    const imported = importGitbookCorpus(corpus, { space: input.choose?.space });
+    const project = gitbookProject(imported, corpus, {
+        siteName: input.siteName?.trim() || "Docs",
+        siteUrl: input.siteUrl,
+        sourceLabel: input.sourceLabel ?? "GitBook corpus",
+    });
+    const files = new Map(project.files);
+    for (const { from, to } of project.assets) {
+        const bytes = input.files.get(from);
+        if (bytes !== undefined)
+            files.set(to, bytes);
+    }
+    return { files, ledger: project.ledger, redirects: project.redirects };
+}

package/dist/parse.d.ts

@@ -7,6 +7,12 @@ export interface ParseGitbookResult {
     markdown: string;
     /** Translated body only (no frontmatter) — for callers writing their own. */
     body: string;
+    /** Ledger lines count from the body: the source line the body starts on (1 with no front matter). */
+    bodyLine: number;
     ledger: TranslateLedgerEntry[];
 }
-export declare function parseGitbook(src: string): ParseGitbookResult;
+export interface ParseGitbookOptions {
+    /** Applied to the translated body before it is parsed (the import's renamed page links). */
+    links?: (body: string) => string;
+}
+export declare function parseGitbook(src: string, opts?: ParseGitbookOptions): ParseGitbookResult;

package/dist/parse.js

@@ -15,18 +15,21 @@
  * writes to disk — canonical, editable Dogsbay-MD. `tree` feeds the
  * runtime path (format-astro emit, headings, title).
  */
-import { dogsbayMdToTree } from "@dogsbay/format-dogsbay-md";
+import { dogsbayMdToTree } from "@dogsbay/format-dogsbay-md/browser";
 import { gitbookToDogsbayMd } from "./translate.js";
 const FRONTMATTER_RE = /^---\n([\s\S]*?)\n---\n?/;
-export function parseGitbook(src) {
+export function parseGitbook(src, opts = {}) {
     const normalized = src.replace(/\r\n?/g, "\n");
     const fmMatch = normalized.match(FRONTMATTER_RE);
     const fmBlock = fmMatch ? fmMatch[0] : "";
     const body = fmMatch ? normalized.slice(fmMatch[0].length) : normalized;
-    const { markdown: translatedBody, ledger } = gitbookToDogsbayMd(body);
+    const translated = gitbookToDogsbayMd(body);
+    const { ledger } = translated;
+    const translatedBody = opts.links ? opts.links(translated.markdown) : translated.markdown;
     const markdown = fmBlock ? `${fmBlock.replace(/\n?$/, "\n")}\n${translatedBody}` : translatedBody;
     // dogsbayMdToTree extracts frontmatter itself (gray-matter) and parses
     // the body into TreeNode[]. Feed it the recombined markdown.
     const { tree, frontmatter } = dogsbayMdToTree(markdown);
-    return { tree, frontmatter: frontmatter ?? {}, markdown, body: translatedBody, ledger };
+    const bodyLine = fmBlock ? fmBlock.split("\n").length - (fmBlock.endsWith("\n") ? 1 : 0) + 1 : 1;
+    return { tree, frontmatter: frontmatter ?? {}, markdown, body: translatedBody, bodyLine, ledger };
 }

package/dist/project.d.ts

@@ -0,0 +1,34 @@
+import type { ImportLedgerEntry } from "@dogsbay/types";
+import type { Corpus } from "./corpus.js";
+import type { GitbookImportResult } from "./import.js";
+export interface GitbookProjectOptions {
+    siteName: string;
+    siteUrl?: string;
+    /** Where the corpus came from, for MIGRATION.md (a folder, a repo URL). */
+    sourceLabel: string;
+    /** Where the host writes the redirects, for MIGRATION.md (the CLI: `astro/public/_redirects`). */
+    redirectsFile?: string;
+}
+export interface GitbookProject {
+    /** The project's text files, by path relative to the project root. */
+    files: Map<string, string>;
+    /** Files to copy unchanged: corpus path → project path. */
+    assets: {
+        from: string;
+        to: string;
+    }[];
+    /** Old URL → served URL, both root-absolute (`/old/path` → `/guide`). */
+    redirects: {
+        from: string;
+        to: string;
+    }[];
+    /** The import's ledger plus the writer's own notes (slug collisions). */
+    ledger: ImportLedgerEntry[];
+    stats: {
+        pages: number;
+        fragments: number;
+        collisions: number;
+        spaces: string[];
+    };
+}
+export declare function gitbookProject(result: GitbookImportResult, corpus: Corpus, opts: GitbookProjectOptions): GitbookProject;

package/dist/project.js

@@ -0,0 +1,175 @@
+/**
+ * An imported GitBook corpus → a Dogsbay project, as data (no Node, quiet, deterministic):
+ * `content/<slug>.md` (front matter + translated body), fragments as include targets,
+ * `content/nav.yml` from SUMMARY.md, `dogsbay.config.yml`, `MIGRATION.md`, the assets to copy
+ * and the redirects. `migrate-gitbook` writes it to disk and adds the Astro scaffold and
+ * `_redirects`; the browser (`./migrate`) returns it as a map of files.
+ */
+import * as yaml from "js-yaml";
+import { gitbookVisible, within } from "@dogsbay/detect";
+function yamlQuote(s) {
+    return /[:#&*!|>%@`,'"[\]{}]|^\s|\s$/.test(s) ? JSON.stringify(s) : s;
+}
+/** Serialize NavItem[] to nav.yml (mirrors migrate-asciidoc's navToYaml). */
+function navToYaml(items, indent = 0) {
+    const pad = "  ".repeat(indent);
+    const lines = [];
+    for (const item of items) {
+        const hasChildren = item.children !== undefined && item.children.length > 0;
+        const target = item.href === undefined
+            ? undefined
+            : /^(?:https?:\/\/|mailto:|tel:)/i.test(item.href) || item.href.includes("#")
+                ? item.href
+                : `${item.href.replace(/^\/+/, "")}.md`;
+        if (target !== undefined && !hasChildren) {
+            lines.push(`${pad}- ${yamlQuote(item.label)}: ${target}`);
+        }
+        else {
+            lines.push(`${pad}- ${yamlQuote(item.label)}:`);
+            if (target !== undefined)
+                lines.push(`${pad}    - ${yamlQuote(target)}`);
+            if (hasChildren)
+                lines.push(navToYaml(item.children, indent + 2));
+        }
+    }
+    return lines.join("\n");
+}
+function buildConfig(siteName, siteUrl) {
+    const lines = [`schemaVersion: 1`, `site:`, `  name: ${yamlQuote(siteName)}`, `  basePath: ""`];
+    if (siteUrl)
+        lines.push(`  url: ${yamlQuote(siteUrl)}`);
+    lines.push(`content:`, `  sources:`, `    - path: ./content`, `      from: dogsbay-md`, 
+    // `.gitbook/includes` fragments are `{% include %}` targets, not routable pages.
+    // routablesFrom: nav restricts routes to SUMMARY-named pages; the fragments stay on disk
+    // so includes resolve.
+    `  excludeFromRoutes:`, `    - .gitbook`, `  routablesFrom: nav`, ``);
+    return lines.join("\n");
+}
+/**
+ * Front matter (source keys + a title) as a YAML block. Array/object values (`tags: [a, b]`,
+ * GitBook `cover:` maps) round-trip instead of being dropped (review #4). The title is the
+ * source `title:` only when it's a non-empty string; otherwise the computed title (H1 / slug):
+ * a blank source title must NOT clobber it (review #6).
+ */
+// No `noRefs`: an alias the source used stays an alias. Writing each out in full turned ten
+// lines of nested aliases into hundreds of MB (an alias bomb, review 2026-10-20).
+function frontmatterBlock(fm, title) {
+    const sourceTitle = typeof fm.title === "string" && fm.title.trim() ? fm.title : undefined;
+    const out = { title: sourceTitle ?? title, ...fm };
+    out.title = sourceTitle ?? title;
+    const body = yaml.dump(out, { lineWidth: -1, skipInvalid: true }).replace(/\n$/, "");
+    return `---\n${body}\n---\n\n`;
+}
+/** A redirect's target as the URL it is served at: drop ./ and .md; a README is its folder. */
+function servedUrl(target) {
+    // A bare `README` maps to the site root `/`, not a dead `/README` (review #5).
+    return `/${target.replace(/^\.\//, "").replace(/\.md$/i, "").replace(/(^|\/)README$/i, "$1").replace(/\/$/, "")}`;
+}
+function migrationNotes(a) {
+    const lines = [
+        `# Migration: ${a.siteName}`,
+        ``,
+        `Migrated from a GitBook Git Sync corpus by \`dogsbay migrate-gitbook\`.`,
+        ``,
+        `- **Source**: \`${a.sourceLabel}\``,
+        `- **Pages**: ${a.pages}${a.fragments ? ` (+ ${a.fragments} include fragments)` : ""}`,
+    ];
+    if (a.spaces.length > 1)
+        lines.push(`- **Spaces**: ${a.spaces.join(", ")} (each a top-level nav section)`);
+    if (a.redirects)
+        lines.push(`- **Redirects**: ${a.redirects}${a.redirectsFile ? ` carried into \`${a.redirectsFile}\`` : ""}`);
+    lines.push(``, `## What was converted`, ``, `- GitBook \`{% hint %}\` → \`:::note/:::warning/:::info/:::danger\` callouts`, `- \`{% tabs %}\` / \`{% stepper %}\` / \`{% columns %}\` → \`:::tabs\` / \`:::steps\` / \`:::grid\``, `- \`{% code %}\`, \`{% content-ref %}\`, \`{% embed %}\`, \`{% file %}\`, \`{% page-ref %}\` → native Dogsbay-MD`, `- \`{% include %}\` reusable content preserved (resolved at build time)`, `- \`<figure>\` images, GitBook emoji spans, raw HTML tables handled`, `- \`SUMMARY.md\` → \`content/nav.yml\`; \`.gitbook.yaml\` redirects kept`, ``, `## Known caveats`, ``, `- \`{% openapi %}\` / \`{% swagger %}\` blocks emit \`:::api-endpoint\` placeholders — wire them to the OpenAPI spec for full rendering.`);
+    if (a.ledger.length) {
+        lines.push(``, `## Review these`, ``);
+        for (const e of a.ledger)
+            lines.push(`- \`${e.file ?? "?"}${e.line ? `:${e.line}` : ""}\`: ${e.message}`);
+    }
+    return lines.join("\n") + "\n";
+}
+export function gitbookProject(result, corpus, opts) {
+    const files = new Map();
+    const ledger = [...result.ledger];
+    // Two source files can slugify to the same path (README.md and index.md both → `index`).
+    // Keep the first, skip and note the rest rather than silently overwriting a page (review #3).
+    // Paths compared without case: on macOS and Windows `INDEX.md` overwrites `index.md`.
+    const taken = new Set();
+    let fragments = 0;
+    let collisions = 0;
+    for (const page of result.pages) {
+        const dst = `content/${page.slug}.md`;
+        if (taken.has(dst.toLowerCase())) {
+            collisions += 1;
+            ledger.push({ severity: "warning", code: "slug-collision", message: `two pages map to ${dst}: kept the first, skipped a later one` });
+            continue;
+        }
+        taken.add(dst.toLowerCase());
+        const body = page.bodyMarkdown ?? "";
+        const text = body.endsWith("\n") ? body : body + "\n";
+        if (page.fragment) {
+            // Fragments: pure body, no frontmatter (they're include targets).
+            files.set(dst, text);
+            fragments += 1;
+        }
+        else {
+            files.set(dst, frontmatterBlock(page.frontmatter ?? {}, page.title) + text);
+        }
+    }
+    // Non-`.md` files under each docs root, at the same relative place under content/, so the
+    // translated relative image refs resolve. From the docs root, not the repo root: with
+    // `root: ./docs/gitbook/` unrelated repo source must not land in content/.
+    const assets = [];
+    for (const root of result.assetRoots) {
+        for (const path of corpus.paths) {
+            if (!within(path, root.dir) || path === root.dir)
+                continue;
+            // Only what stays in the docs root once links resolve: a link named `env.txt` to the
+            // repo's `.env`, or `g` to `.git`, must not be published with the site.
+            if (corpus.contains && !corpus.contains(path, root.dir))
+                continue;
+            const rel = root.dir ? path.slice(root.dir.length + 1) : path;
+            if (!gitbookVisible(rel))
+                continue;
+            const name = rel.slice(rel.lastIndexOf("/") + 1);
+            // A hidden file is the repo's (`.env`, `.npmrc`, `.gitbook/assets/.DS_Store`), never a
+            // page's asset; `.gitbook.yaml` is read as config, not published.
+            if (name.toLowerCase().endsWith(".md") || name.startsWith("."))
+                continue;
+            assets.push({ from: path, to: `content/${root.prefix}${rel}` });
+        }
+    }
+    files.set("content/nav.yml", `# Migrated by dogsbay migrate-gitbook.\n# Edit freely.\n\n${navToYaml(result.nav)}\n`);
+    files.set("dogsbay.config.yml", buildConfig(opts.siteName, opts.siteUrl));
+    files.set("MIGRATION.md", "");
+    // A corpus file at a generated path (a `nav.yml` in the docs root) must not replace it, nor
+    // may two assets that differ only in case replace each other
+    for (const f of files.keys())
+        taken.add(f.toLowerCase());
+    const copies = assets.filter((a) => {
+        const key = a.to.toLowerCase();
+        if (!taken.has(key)) {
+            taken.add(key);
+            return true;
+        }
+        ledger.push({ file: a.from, severity: "warning", code: "file-replaced", message: `not copied: ${a.to} would replace a file the migration writes` });
+        return false;
+    });
+    // A redirect is one `_redirects` line: no whitespace or control character in either side, or
+    // a crafted key (`"x  https://evil 301\n/y"`) adds a line of its own. A backslash is a slash
+    // to a browser (`/\evil.example` is another host), and a `*` or `:name` in the old path is a
+    // pattern that would capture the whole site.
+    const redirects = [];
+    for (const [from, target] of Object.entries(result.redirects)) {
+        const r = { from: `/${from.replace(/^\/+/, "")}`, to: servedUrl(target) };
+        if (/[\s\0-\x1f\\]/.test(r.from + r.to) ||
+            r.from.startsWith("//") ||
+            r.to.startsWith("//") ||
+            /\*|(^|\/):/.test(r.from)) {
+            ledger.push({ file: ".gitbook.yaml", severity: "warning", code: "redirect-refused", message: `redirect not kept: ${JSON.stringify(from)} → ${JSON.stringify(target)}` });
+            continue;
+        }
+        redirects.push(r);
+    }
+    const pages = result.pages.filter((p) => !p.fragment).length;
+    files.set("MIGRATION.md", migrationNotes({ ...opts, pages, fragments, spaces: result.spaces, redirects: redirects.length, ledger }));
+    return { files, assets: copies, redirects, ledger, stats: { pages, fragments, collisions, spaces: result.spaces } };
+}

package/package.json

@@ -1,7 +1,7 @@
 {
   "name": "@dogsbay/format-gitbook",
-  "version": "0.2.0-beta.130",
-  "description": "GitBook format plugin for Dogsbay — imports GitBook Git Sync (and legacy gitbook-cli) corpora into TreeNode[] by translating the Git Sync markdown dialect to Dogsbay-MD.",
+  "version": "0.2.0-beta.132",
+  "description": "GitBook format plugin for Dogsbay — imports GitBook Git Sync (and legacy gitbook-cli) corpora by translating the Git Sync markdown dialect to Dogsbay-MD. ./migrate converts a corpus given as a map of files in the browser (no Node), the same import the CLI runs.",
   "type": "module",
   "main": "dist/index.js",
   "types": "dist/index.d.ts",
@@ -13,6 +13,10 @@
     "./cli": {
       "types": "./dist/cli.d.ts",
       "import": "./dist/cli.js"
+    },
+    "./migrate": {
+      "types": "./dist/migrate.d.ts",
+      "import": "./dist/migrate.js"
     }
   },
   "files": [
@@ -20,12 +24,16 @@
     "README.md"
   ],
   "dependencies": {
-    "yaml": "^2.9.0",
-    "@dogsbay/format-dogsbay-md": "0.2.0-beta.130",
-    "@dogsbay/types": "0.2.0-beta.130"
+    "js-yaml": "^5.2.1",
+    "@dogsbay/corpus": "0.2.0-beta.132",
+    "@dogsbay/format-dogsbay-md": "0.2.0-beta.132",
+    "@dogsbay/types": "0.2.0-beta.132",
+    "@dogsbay/detect": "0.2.0-beta.132"
   },
   "devDependencies": {
+    "@types/js-yaml": "^4.0.9",
     "@types/node": "^25.9.5",
+    "esbuild": "^0.25.0",
     "typescript": "^5.9.3",
     "vitest": "^4.1.10"
   },