sourcey 3.5.10 → 3.6.0

package/README.md

@@ -27,8 +27,9 @@ npx sourcey init
 - **API reference from OpenAPI**: endpoints, parameters, request/response schemas, auto-generated code samples in 10 languages (cURL, JavaScript, TypeScript, Python, Go, Ruby, Java, PHP, Rust, C#)
 - **MCP server documentation**: tools, resources, prompts rendered as browsable reference with JSON-RPC, TypeScript, and Python code samples. Color-coded method types, annotation badges, connection config cards
 - **Rich guides**: markdown pages with steps, cards, accordions, syntax-highlighted code blocks, and prose alongside your API reference
+- **MkDocs source import**: point a tab at `mkdocs.yml`; Sourcey reads `docs_dir` and `nav` so existing MkDocs markdown sites can render without hand-copying the sidebar structure
 - **Product story pages**: changelog, roadmap pages, examples, reference material, search, and portable context exports in one source-owned site
-- **C++ and Doxygen**: feed Doxygen XML output, get modern searchable API docs. No new parser, no four-tool Breathe/Exhale/Sphinx pipeline
+- **C++ and Doxygen**: feed Doxygen XML output, get modern searchable API docs with exact member search, source links, templates, qualifiers, examples, inherited members, and relationship sections. No new parser, no four-tool Breathe/Exhale/Sphinx pipeline
 - **Go and godoc**: native package documentation extracted from Go source via the toolchain. Render Go modules as Sourcey tabs, generate standalone static Go docs sites, or commit `godoc.json` snapshots for JS-only docs hosts. No Doxygen detour
 - **Context exports**: auto-generate llms.txt and llms-full.txt alongside your HTML as alternate views of the same documentation graph
 - **TypeScript config**: `sourcey.config.ts` with `defineConfig()` autocomplete; theme, navbar, CTA buttons, footer
@@ -45,12 +46,12 @@ npx sourcey init
 
 The full Sourcey binary handles OpenAPI, Doxygen, godoc, MCP, and Markdown sources.
 
-| Path     | Command                                            | Requires          |
-|----------|----------------------------------------------------|-------------------|
-| npm      | `npm install -g sourcey`                           | Node 20+          |
-| Homebrew | `brew tap sourcey/tap && brew install sourcey`     | macOS / Linuxbrew |
-| Docker   | `docker run -v "$PWD":/docs sourcey/sourcey`       | Docker            |
-| Nix      | `nix run github:sourcey/sourcey`                   | Nix (flakes)      |
+| Path     | Command                                        | Requires          |
+| -------- | ---------------------------------------------- | ----------------- |
+| npm      | `npm install -g sourcey`                       | Node 20+          |
+| Homebrew | `brew tap sourcey/tap && brew install sourcey` | macOS / Linuxbrew |
+| Docker   | `docker run -v "$PWD":/docs sourcey/sourcey`   | Docker            |
+| Nix      | `nix run github:sourcey/sourcey`               | Nix (flakes)      |
 
 Then `sourcey init` to scaffold a new project, or `sourcey build` against an existing one. See [docs/install.md](docs/install.md) for full Docker invocations (`init` / `dev` / `build`), the `--host` flag for containerized dev, Linuxbrew notes, and Nix profile install.
 
@@ -58,10 +59,10 @@ Then `sourcey init` to scaffold a new project, or `sourcey build` against an exi
 
 For Go-only consumers without a JavaScript toolchain, `sourcey-godoc` ships as a separate native binary. It produces static Go docs sites or portable `godoc.json` snapshots.
 
-| Path     | Command |
-|----------|---------|
-| Go       | `go install github.com/sourcey/sourcey/go/sourcey-godoc/cmd/sourcey-godoc@latest` |
-| Homebrew | `brew install sourcey/tap/sourcey-godoc` |
+| Path     | Command                                                                                           |
+| -------- | ------------------------------------------------------------------------------------------------- |
+| Go       | `go install github.com/sourcey/sourcey/go/sourcey-godoc/cmd/sourcey-godoc@latest`                 |
+| Homebrew | `brew install sourcey/tap/sourcey-godoc`                                                          |
 | Scoop    | `scoop bucket add sourcey https://github.com/sourcey/scoop-bucket && scoop install sourcey-godoc` |
 
 ## Quick start
@@ -82,101 +83,29 @@ sourcey dev
 Create `sourcey.config.ts` in your project root:
 
 ```typescript
-import { defineConfig } from "sourcey";
+import { defineConfig, openapi } from "sourcey";
 
 export default defineConfig({
   name: "My API",
-  theme: {
-    preset: "default",  // "default" | "minimal" | "api-first"
-    colors: {
-      primary: "#6366F1",
-      light: "#818CF8",
-      dark: "#4F46E5",
-    },
-  },
-  logo: "./logo.png",
   navigation: {
-    tabs: [
-      {
-        tab: "Documentation",
-        groups: [
-          {
-            group: "Getting Started",
-            pages: ["introduction", "quickstart", "authentication"],
-          },
-        ],
-      },
-      {
-        tab: "API Reference",
-        openapi: "./openapi.yaml",
-      },
-      {
-        tab: "MCP Server",
-        mcp: "./mcp.json",
-      },
-    ],
-  },
-  navbar: {
-    links: [{ type: "github", href: "https://github.com/you/repo" }],
-    primary: { type: "button", label: "Dashboard", href: "https://app.example.com" },
-  },
-  footer: {
-    socials: { github: "https://github.com/you/repo" },
+    tabs: [{ tab: "API Reference", source: openapi("./openapi.yaml") }],
   },
 });
 ```
 
-Each tab is an `openapi` spec, an `mcp` snapshot, a `doxygen` directory, a `godoc` Go module, or `groups` of markdown pages. Pages are referenced by slug (e.g. `"quickstart"` resolves to `quickstart.md`).
+Each tab has one `source`, usually created with `markdown()`, `mkdocs()`, `openapi()`, `mcp()`, `doxygen()`, or `godoc()`. Pages are referenced by slug (e.g. `"quickstart"` resolves to `quickstart.md`). See [docs/configuration.md](docs/configuration.md) for theme, navbar, footer, logo, and full tab options.
 
 ### Go documentation (godoc)
 
-Add a Go module as a tab and Sourcey extracts package docs natively (no Doxygen pipeline):
-
-```typescript
-{
-  tab: "Go API",
-  godoc: {
-    module: ".",
-    packages: ["./internal/core/...", "./cmd/..."],
-    // sourceBasePath: "go/my-module" // repo-relative prefix for source links when module is not at repo root
-    // mode: "auto"   // default; live when Go is available, snapshot otherwise
-    // includeTests: true       // examples from *_test.go (default)
-    // includeUnexported: false // hide unexported symbols (default)
-  },
-}
-```
-
-The string shorthand is `godoc: "."` and expands to `{ module: ".", packages: ["./..."], mode: "auto", includeTests: true }`.
-
-`editBasePath` remains the global base for Markdown "Edit this page" links.
-Use `godoc.sourceBasePath` only when Go source files live under a different
-repository prefix than the docs source.
+Render Go package docs as a tab inside your Sourcey site, branded and styled with the rest of your documentation. Native toolchain extraction (`go list` + `go/parser` + `go/doc`) feeds the same renderer as your OpenAPI, MCP, and Markdown tabs, so signatures, examples from `*_test.go`, and source links sit alongside your guides instead of bouncing readers to pkg.go.dev.
 
-Live mode invokes `go list` + `go/parser` + `go/doc` against the host Go toolchain. To pin a build environment for reproducibility, set `goEnv: { GOOS, GOARCH, tags }`.
-
-Snapshot mode reads a committed `godoc.json` and needs no Go on the build host. Generate it with:
-
-```bash
-sourcey godoc --module . --packages './...' --out docs/godoc.json
-```
-
-then point the tab at it:
+**[Live: scafld's Go API reference →](https://0state.com/scafld/docs/go-api)**
 
 ```typescript
-{
-  tab: "Go API",
-  godoc: { mode: "snapshot", snapshot: "./docs/godoc.json" },
-}
+{ tab: "Go API", source: godoc(".") }
 ```
 
-The extractor is also a standalone Go CLI for projects that want a native Go
-docs generator without installing the full Sourcey npm package:
-
-```bash
-go install github.com/sourcey/sourcey/go/sourcey-godoc/cmd/sourcey-godoc@latest
-sourcey-godoc generate --module . --packages './...' --out site
-sourcey-godoc snapshot --module . --packages './...' --out docs/godoc.json
-```
+The shorthand expands to `{ module: ".", packages: ["./..."], mode: "auto", includeTests: true }`. Live mode uses the host Go toolchain; snapshot mode reads a committed `godoc.json` and needs no Go on the build host. See [docs/configuration.md](docs/configuration.md) for `packages`, `mode`, `goEnv`, `sourceBasePath`, and `includeUnexported`.
 
 ### Markdown components
 
@@ -226,12 +155,7 @@ sourcey godoc --out godoc.json    Snapshot a Go module's docs to JSON
 sourcey-godoc generate --out site Standalone Go CLI for static godoc sites
 ```
 
-| Command | Flag | Description |
-| --- | --- | --- |
-| `build` | `--output, -o` | Output directory (default: `dist`) |
-| `build` | `--embed, -e` | Embeddable output (no html/body wrapper) |
-| `build` | `--quiet, -q` | Suppress output |
-| `dev` | `--port, -p` | Dev server port (default: `4400`) |
+Run `sourcey <command> --help` for flags.
 
 ## Development
 

package/dist/adapters/index.d.ts

@@ -0,0 +1,11 @@
+import type { DoxygenSourceOptions, GodocSourceOptions, MarkdownSourceOptions, McpSourceOptions, MkDocsSourceOptions, OpenApiSourceOptions, SourceAdapter } from "./types.js";
+import { assertLocalPath } from "./shared.js";
+export declare function openapi(specOrOptions: string | OpenApiSourceOptions): SourceAdapter;
+export declare function mcp(specOrOptions: string | McpSourceOptions): SourceAdapter;
+export declare function markdown(options: MarkdownSourceOptions): SourceAdapter;
+export declare function mkdocs(configOrOptions: string | MkDocsSourceOptions): SourceAdapter;
+export declare function doxygen(options: DoxygenSourceOptions): SourceAdapter;
+export declare function godoc(configOrPath: GodocSourceOptions): SourceAdapter;
+export { assertLocalPath };
+export type { DoxygenSourceOptions, GodocSourceOptions, MarkdownSourceOptions, McpSourceOptions, MkDocsSourceOptions, OpenApiSourceOptions, PageMarkdownOptions, ResolvedTabSource, SourceAdapter, SourceAdapterContext, } from "./types.js";
+//# sourceMappingURL=index.d.ts.map

package/dist/adapters/index.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../../src/adapters/index.ts"],"names":[],"mappings":"AACA,OAAO,KAAK,EACV,oBAAoB,EACpB,kBAAkB,EAClB,qBAAqB,EACrB,gBAAgB,EAChB,mBAAmB,EACnB,oBAAoB,EACpB,aAAa,EACd,MAAM,YAAY,CAAC;AACpB,OAAO,EAAE,eAAe,EAAuC,MAAM,aAAa,CAAC;AAGnF,wBAAgB,OAAO,CAAC,aAAa,EAAE,MAAM,GAAG,oBAAoB,GAAG,aAAa,CAanF;AAED,wBAAgB,GAAG,CAAC,aAAa,EAAE,MAAM,GAAG,gBAAgB,GAAG,aAAa,CAa3E;AAED,wBAAgB,QAAQ,CAAC,OAAO,EAAE,qBAAqB,GAAG,aAAa,CAWtE;AAED,wBAAgB,MAAM,CAAC,eAAe,EAAE,MAAM,GAAG,mBAAmB,GAAG,aAAa,CAInF;AAED,wBAAgB,OAAO,CAAC,OAAO,EAAE,oBAAoB,GAAG,aAAa,CAsBpE;AAED,wBAAgB,KAAK,CAAC,YAAY,EAAE,kBAAkB,GAAG,aAAa,CA6BrE;AAMD,OAAO,EAAE,eAAe,EAAE,CAAC;AAC3B,YAAY,EACV,oBAAoB,EACpB,kBAAkB,EAClB,qBAAqB,EACrB,gBAAgB,EAChB,mBAAmB,EACnB,oBAAoB,EACpB,mBAAmB,EACnB,iBAAiB,EACjB,aAAa,EACb,oBAAoB,GACrB,MAAM,YAAY,CAAC"}

package/dist/adapters/index.js

@@ -0,0 +1,98 @@
+import { resolve } from "node:path";
+import { assertLocalPath, resolveMarkdownGroups, toWatchPaths } from "./shared.js";
+import { mkdocs as mkdocsAdapter } from "./mkdocs.js";
+export function openapi(specOrOptions) {
+    const spec = typeof specOrOptions === "string" ? specOrOptions : specOrOptions.spec;
+    return {
+        name: "openapi",
+        async resolve(ctx) {
+            if (ctx.isUrl(spec)) {
+                return { kind: "openapi", spec };
+            }
+            const absPath = ctx.resolvePath(spec);
+            await ctx.assertExists(absPath, `OpenAPI spec "${spec}" in tab "${ctx.tabName}"`);
+            return { kind: "openapi", spec: absPath, watchPaths: [absPath] };
+        },
+    };
+}
+export function mcp(specOrOptions) {
+    const spec = typeof specOrOptions === "string" ? specOrOptions : specOrOptions.spec;
+    return {
+        name: "mcp",
+        async resolve(ctx) {
+            if (ctx.isUrl(spec)) {
+                return { kind: "mcp", spec };
+            }
+            const absPath = ctx.resolvePath(spec);
+            await ctx.assertExists(absPath, `MCP spec "${spec}" in tab "${ctx.tabName}"`);
+            return { kind: "mcp", spec: absPath, watchPaths: [absPath] };
+        },
+    };
+}
+export function markdown(options) {
+    return {
+        name: "markdown",
+        async resolve(ctx) {
+            return {
+                kind: "markdown",
+                adapter: "markdown",
+                groups: await resolveMarkdownGroups(options.groups, ctx.tabName, ctx.configDir),
+            };
+        },
+    };
+}
+export function mkdocs(configOrOptions) {
+    const options = typeof configOrOptions === "string" ? { config: configOrOptions } : configOrOptions;
+    return mkdocsAdapter(options);
+}
+export function doxygen(options) {
+    return {
+        name: "doxygen",
+        async resolve(ctx) {
+            const absXml = ctx.resolvePath(options.xml);
+            await ctx.assertExists(absXml, `Doxygen XML directory "${options.xml}" in tab "${ctx.tabName}"`);
+            return {
+                kind: "doxygen",
+                config: {
+                    xml: absXml,
+                    language: options.language ?? "cpp",
+                    groups: options.groups ?? false,
+                    index: options.index === false ? "none" : (options.index ?? "auto"),
+                    sourceUrl: options.sourceUrl,
+                },
+                watchPaths: [absXml],
+            };
+        },
+    };
+}
+export function godoc(configOrPath) {
+    return {
+        name: "godoc",
+        async resolve(ctx) {
+            const cfg = typeof configOrPath === "string" ? { module: configOrPath } : configOrPath;
+            const moduleAbs = resolve(ctx.configDir, cfg.module ?? ".");
+            await ctx.assertExists(moduleAbs, `Go module directory "${cfg.module ?? "."}" in tab "${ctx.tabName}"`);
+            const snapshotAbs = cfg.snapshot ? ctx.resolvePath(cfg.snapshot) : undefined;
+            return {
+                kind: "godoc",
+                config: {
+                    module: moduleAbs,
+                    packages: cfg.packages?.length ? cfg.packages : ["./..."],
+                    snapshot: snapshotAbs,
+                    mode: cfg.mode ?? "auto",
+                    includeTests: cfg.includeTests ?? true,
+                    includeUnexported: cfg.includeUnexported ?? false,
+                    hideUndocumented: cfg.hideUndocumented ?? false,
+                    exclude: cfg.exclude ?? [],
+                    goEnv: cfg.goEnv,
+                    sourceBasePath: trimSlashes(cfg.sourceBasePath ?? ""),
+                },
+                watchPaths: toWatchPaths([snapshotAbs]),
+            };
+        },
+    };
+}
+function trimSlashes(value) {
+    return value.replace(/^\/+|\/+$/g, "");
+}
+export { assertLocalPath };

package/dist/adapters/mkdocs.d.ts

@@ -0,0 +1,5 @@
+import type { MarkdownPreprocessor } from "../core/markdown-loader.js";
+import type { MkDocsSourceOptions, SourceAdapter } from "./types.js";
+export declare function mkdocs(options: MkDocsSourceOptions): SourceAdapter;
+export declare const preprocessMkDocsMarkdown: MarkdownPreprocessor;
+//# sourceMappingURL=mkdocs.d.ts.map

package/dist/adapters/mkdocs.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"mkdocs.d.ts","sourceRoot":"","sources":["../../src/adapters/mkdocs.ts"],"names":[],"mappings":"AAKA,OAAO,KAAK,EAAE,oBAAoB,EAAE,MAAM,4BAA4B,CAAC;AACvE,OAAO,KAAK,EAAE,mBAAmB,EAAE,aAAa,EAAE,MAAM,YAAY,CAAC;AAcrE,wBAAgB,MAAM,CAAC,OAAO,EAAE,mBAAmB,GAAG,aAAa,CAoBlE;AAiLD,eAAO,MAAM,wBAAwB,EAAE,oBAWtC,CAAC"}

package/dist/adapters/mkdocs.js

@@ -0,0 +1,367 @@
+import { readFileSync } from "node:fs";
+import { access, readFile, readdir } from "node:fs/promises";
+import { dirname, isAbsolute, join, relative, resolve } from "node:path";
+import { load as parseYaml } from "js-yaml";
+import { assertLocalPath, collectStaticAssets } from "./shared.js";
+export function mkdocs(options) {
+    return {
+        name: "mkdocs",
+        async resolve(ctx) {
+            const configPath = assertLocalPath(ctx, options.config, "MkDocs config");
+            await ctx.assertExists(configPath, `MkDocs config "${options.config}" in tab "${ctx.tabName}"`);
+            const { docsDir, groups } = await resolveMkDocsGroups(configPath);
+            return {
+                kind: "markdown",
+                adapter: "mkdocs",
+                configPath,
+                groups,
+                assets: await collectStaticAssets(docsDir),
+                watchPaths: [configPath, docsDir],
+            };
+        },
+    };
+}
+async function resolveMkDocsGroups(configPath) {
+    const raw = await readFile(configPath, "utf-8");
+    const parsed = parseYaml(sanitizeMkDocsYaml(raw));
+    if (!parsed || typeof parsed !== "object" || Array.isArray(parsed)) {
+        throw new Error(`MkDocs config must be a YAML object: ${configPath}`);
+    }
+    const configDir = dirname(configPath);
+    const docsDirName = typeof parsed.docs_dir === "string" && parsed.docs_dir.trim() ? parsed.docs_dir.trim() : "docs";
+    const docsDir = resolve(configDir, docsDirName);
+    const nav = parsed.nav ?? parsed.pages;
+    const groups = Array.isArray(nav)
+        ? mkDocsGroupsFromNav(nav, docsDir)
+        : [{ label: "Pages", pages: await discoverMkDocsPages(docsDir) }];
+    const nonEmptyGroups = groups.filter((group) => group.pages.length > 0);
+    if (nonEmptyGroups.length === 0) {
+        throw new Error(`MkDocs config did not resolve any markdown pages: ${configPath}`);
+    }
+    for (const group of nonEmptyGroups) {
+        for (const page of group.pages) {
+            await access(page.file).catch(() => {
+                throw new Error(`MkDocs nav page "${relative(docsDir, page.file).replace(/\\/g, "/")}" not found`);
+            });
+        }
+    }
+    return { docsDir, groups: nonEmptyGroups };
+}
+function sanitizeMkDocsYaml(raw) {
+    return raw.replace(/!!python\/name:[^\s\]]+/g, "").replace(/!ENV\b/g, "");
+}
+function mkDocsGroupsFromNav(nav, docsDir) {
+    const groups = [];
+    const loosePages = [];
+    const seenPaths = new Set();
+    for (const entry of nav) {
+        if (typeof entry === "string") {
+            const page = resolveMkDocsNavPage({ path: entry }, docsDir, seenPaths);
+            if (page)
+                loosePages.push(page);
+            continue;
+        }
+        if (!isPlainRecord(entry))
+            continue;
+        for (const [label, value] of Object.entries(entry)) {
+            if (typeof value === "string") {
+                const page = resolveMkDocsNavPage({ path: value, label }, docsDir, seenPaths);
+                if (page)
+                    loosePages.push(page);
+                continue;
+            }
+            const pages = collectMkDocsNavPages(value, [])
+                .map((page) => resolveMkDocsNavPage(page, docsDir, seenPaths))
+                .filter((page) => Boolean(page));
+            if (pages.length > 0) {
+                groups.push({ label, pages });
+            }
+        }
+    }
+    return loosePages.length > 0 ? [{ label: "Pages", pages: loosePages }, ...groups] : groups;
+}
+function collectMkDocsNavPages(value, labelParts) {
+    if (typeof value === "string") {
+        return [
+            {
+                path: value,
+                label: isMkDocsIndexPage(value) ? labelParts.join(" / ") || undefined : undefined,
+            },
+        ];
+    }
+    if (Array.isArray(value)) {
+        return value.flatMap((entry) => collectMkDocsNavPages(entry, labelParts));
+    }
+    if (!isPlainRecord(value)) {
+        return [];
+    }
+    return Object.entries(value).flatMap(([label, nested]) => {
+        if (typeof nested === "string") {
+            return [
+                {
+                    path: nested,
+                    label: [...labelParts, label].join(" / "),
+                },
+            ];
+        }
+        return collectMkDocsNavPages(nested, [...labelParts, label]);
+    });
+}
+function resolveMkDocsNavPage(page, docsDir, seenPaths) {
+    const navPath = normalizeMkDocsPagePath(page.path);
+    if (!navPath || seenPaths.has(navPath)) {
+        return undefined;
+    }
+    const file = resolveWithinRoot(docsDir, navPath);
+    if (!file) {
+        throw new Error(`MkDocs nav page "${page.path}" escapes docs_dir: ${docsDir}`);
+    }
+    seenPaths.add(navPath);
+    return {
+        slug: slugFromMkDocsPath(navPath),
+        file,
+        label: page.label,
+        sourceRoot: docsDir,
+        preprocess: [preprocessMkDocsMarkdown],
+    };
+}
+function normalizeMkDocsPagePath(value) {
+    const text = value.trim();
+    if (!text || isExternalNavTarget(text) || !/\.(?:md|mdx)$/i.test(text)) {
+        return undefined;
+    }
+    return text.replace(/\\/g, "/").replace(/^\/+/, "");
+}
+function isExternalNavTarget(value) {
+    return /^(?:https?:|mailto:|tel:|#)/i.test(value);
+}
+function slugFromMkDocsPath(value) {
+    return value.replace(/\.(?:md|mdx)$/i, "");
+}
+function isMkDocsIndexPage(value) {
+    return /(^|\/)index\.(?:md|mdx)$/i.test(value.trim());
+}
+async function discoverMkDocsPages(docsDir) {
+    const pages = [];
+    async function walk(dir) {
+        const entries = await readdir(dir, { withFileTypes: true });
+        for (const entry of entries.sort((left, right) => left.name.localeCompare(right.name))) {
+            if (entry.name.startsWith("."))
+                continue;
+            const absolutePath = join(dir, entry.name);
+            if (entry.isDirectory()) {
+                await walk(absolutePath);
+                continue;
+            }
+            if (!entry.isFile() || !/\.(?:md|mdx)$/i.test(entry.name))
+                continue;
+            const relPath = relative(docsDir, absolutePath).replace(/\\/g, "/");
+            pages.push({
+                slug: slugFromMkDocsPath(relPath),
+                file: absolutePath,
+                sourceRoot: docsDir,
+                preprocess: [preprocessMkDocsMarkdown],
+            });
+        }
+    }
+    await walk(docsDir);
+    return pages;
+}
+export const preprocessMkDocsMarkdown = (body, context) => {
+    if (!context.sourceRoot)
+        return body;
+    return normalizeMkDocsAdmonitions(normalizeMkDocsTabs(escapeMkDocsCppTemplateAngles(stripMkDocsInlineLanguageMarkers(expandMkDocsSnippets(body, context.filePath, context.sourceRoot)))));
+};
+function expandMkDocsSnippets(body, filePath, sourceRoot) {
+    return body
+        .split("\n")
+        .map((line) => {
+        const match = line.match(/^(\s*)--8<--\s+"([^"]+)"\s*$/);
+        if (!match)
+            return line;
+        const [, indent, includePath] = match;
+        const included = readMkDocsSnippet(includePath, filePath, sourceRoot);
+        if (included === undefined)
+            return line;
+        return included
+            .replace(/\r\n?/g, "\n")
+            .split("\n")
+            .map((includedLine) => (includedLine ? `${indent}${includedLine}` : includedLine))
+            .join("\n");
+    })
+        .join("\n");
+}
+function readMkDocsSnippet(includePath, filePath, sourceRoot) {
+    const candidates = uniquePaths([
+        isAbsolute(includePath) ? includePath : resolve(sourceRoot, includePath),
+        isAbsolute(includePath) ? includePath : resolve(dirname(filePath), includePath),
+    ]);
+    const safeCandidates = candidates.filter((candidate) => isWithinRoot(sourceRoot, candidate));
+    if (safeCandidates.length === 0) {
+        throw new Error(`MkDocs snippet "${includePath}" escapes docs_dir: ${sourceRoot}`);
+    }
+    for (const candidate of safeCandidates) {
+        try {
+            return readFileSync(candidate, "utf-8");
+        }
+        catch (err) {
+            if (err.code !== "ENOENT")
+                throw err;
+        }
+    }
+    return undefined;
+}
+function stripMkDocsInlineLanguageMarkers(body) {
+    return body
+        .replace(/`#!([A-Za-z0-9_+.-]+)\s+([^`]+)`/g, "`$2`")
+        .replace(/`#!([A-Za-z0-9_+.-]+)\s*`/g, "");
+}
+function escapeMkDocsCppTemplateAngles(body) {
+    return body.replace(/<([A-Za-z_][A-Za-z0-9_:]*)(\\?)>/g, (match, name, escaped) => {
+        if (!escaped && HTML_TAG_NAMES.has(name.toLowerCase()))
+            return match;
+        return `&lt;${name}&gt;`;
+    });
+}
+const HTML_TAG_NAMES = new Set([
+    "a",
+    "abbr",
+    "article",
+    "aside",
+    "b",
+    "blockquote",
+    "br",
+    "button",
+    "caption",
+    "code",
+    "dd",
+    "del",
+    "details",
+    "div",
+    "dl",
+    "dt",
+    "em",
+    "figcaption",
+    "figure",
+    "h1",
+    "h2",
+    "h3",
+    "h4",
+    "h5",
+    "h6",
+    "hr",
+    "i",
+    "iframe",
+    "img",
+    "input",
+    "ins",
+    "kbd",
+    "li",
+    "mark",
+    "ol",
+    "p",
+    "pre",
+    "s",
+    "section",
+    "small",
+    "span",
+    "strong",
+    "sub",
+    "summary",
+    "sup",
+    "table",
+    "tbody",
+    "td",
+    "th",
+    "thead",
+    "tr",
+    "u",
+    "ul",
+]);
+function normalizeMkDocsTabs(body) {
+    const lines = body.split("\n");
+    const out = [];
+    for (let i = 0; i < lines.length;) {
+        const tab = lines[i].match(/^(\s*)===\s+"([^"]+)"\s*$/);
+        if (!tab) {
+            out.push(lines[i]);
+            i += 1;
+            continue;
+        }
+        const [, indent, title] = tab;
+        out.push(`${indent}**${title}**`);
+        i += 1;
+        while (i < lines.length) {
+            if (lines[i].match(new RegExp(`^${escapeRegExp(indent)}===\\s+"[^"]+"\\s*$`))) {
+                break;
+            }
+            if (/^\s*$/.test(lines[i])) {
+                out.push(lines[i]);
+                i += 1;
+                continue;
+            }
+            if (!lines[i].startsWith(`${indent}    `)) {
+                break;
+            }
+            out.push(indent + lines[i].slice(indent.length + 4));
+            i += 1;
+        }
+    }
+    return out.join("\n");
+}
+function normalizeMkDocsAdmonitions(body) {
+    const lines = body.split("\n");
+    const out = [];
+    for (let i = 0; i < lines.length;) {
+        const admonition = lines[i].match(/^(\s*)(!!!|\?\?\?)\s+([A-Za-z0-9_-]+)(?:\s+"([^"]+)")?\s*$/);
+        if (!admonition) {
+            out.push(lines[i]);
+            i += 1;
+            continue;
+        }
+        const [, indent, , type, title] = admonition;
+        out.push(`${indent}> **${formatMkDocsAdmonitionTitle(type, title)}**`);
+        i += 1;
+        const content = [];
+        while (i < lines.length) {
+            if (/^\s*$/.test(lines[i])) {
+                content.push("");
+                i += 1;
+                continue;
+            }
+            if (!lines[i].startsWith(`${indent}    `)) {
+                break;
+            }
+            content.push(lines[i].slice(indent.length + 4));
+            i += 1;
+        }
+        for (const line of normalizeMkDocsAdmonitions(content.join("\n")).split("\n")) {
+            out.push(line ? `${indent}> ${line}` : `${indent}>`);
+        }
+    }
+    return out.join("\n");
+}
+function formatMkDocsAdmonitionTitle(type, title) {
+    if (title?.trim())
+        return title.trim();
+    return type.slice(0, 1).toUpperCase() + type.slice(1).replace(/-/g, " ");
+}
+function escapeRegExp(value) {
+    return value.replace(/[.*+?^${}()|[\]\\]/g, "\\$&");
+}
+function isPlainRecord(value) {
+    return typeof value === "object" && value !== null && !Array.isArray(value);
+}
+function resolveWithinRoot(root, path) {
+    const candidate = resolve(root, path);
+    return isWithinRoot(root, candidate) ? candidate : undefined;
+}
+function isWithinRoot(root, candidate) {
+    const rootAbs = resolve(root);
+    const candidateAbs = resolve(candidate);
+    const rel = relative(rootAbs, candidateAbs);
+    return rel === "" || (!rel.startsWith("..") && !isAbsolute(rel));
+}
+function uniquePaths(paths) {
+    return [...new Set(paths)];
+}

package/dist/adapters/shared.d.ts

@@ -0,0 +1,12 @@
+import type { ResolvedGroup, ResolvedPage } from "../config.js";
+import type { PageMarkdownOptions, ResolvedSourceAsset, SourceAdapterContext } from "./types.js";
+export declare const STATIC_ASSET_EXTENSIONS: Set<string>;
+export declare function resolveMarkdownGroups(groups: {
+    group: string;
+    pages: string[];
+}[], tabName: string, configDir: string, markdown?: PageMarkdownOptions): Promise<ResolvedGroup[]>;
+export declare function collectStaticAssets(sourceRoot: string): Promise<ResolvedSourceAsset[]>;
+export declare function toWatchPaths(paths: Array<string | undefined>): string[];
+export declare function assertLocalPath(ctx: SourceAdapterContext, source: string, label: string): string;
+export declare function outputSlugForPage(page: ResolvedPage): string;
+//# sourceMappingURL=shared.d.ts.map

package/dist/adapters/shared.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"shared.d.ts","sourceRoot":"","sources":["../../src/adapters/shared.ts"],"names":[],"mappings":"AAGA,OAAO,KAAK,EAAE,aAAa,EAAE,YAAY,EAAE,MAAM,cAAc,CAAC;AAEhE,OAAO,KAAK,EAAE,mBAAmB,EAAE,mBAAmB,EAAE,oBAAoB,EAAE,MAAM,YAAY,CAAC;AAEjG,eAAO,MAAM,uBAAuB,aAsBlC,CAAC;AAEH,wBAAsB,qBAAqB,CACzC,MAAM,EAAE;IAAE,KAAK,EAAE,MAAM,CAAC;IAAC,KAAK,EAAE,MAAM,EAAE,CAAA;CAAE,EAAE,EAC5C,OAAO,EAAE,MAAM,EACf,SAAS,EAAE,MAAM,EACjB,QAAQ,CAAC,EAAE,mBAAmB,GAC7B,OAAO,CAAC,aAAa,EAAE,CAAC,CA0B1B;AAED,wBAAsB,mBAAmB,CAAC,UAAU,EAAE,MAAM,GAAG,OAAO,CAAC,mBAAmB,EAAE,CAAC,CAuB5F;AAED,wBAAgB,YAAY,CAAC,KAAK,EAAE,KAAK,CAAC,MAAM,GAAG,SAAS,CAAC,GAAG,MAAM,EAAE,CAEvE;AAED,wBAAgB,eAAe,CAAC,GAAG,EAAE,oBAAoB,EAAE,MAAM,EAAE,MAAM,EAAE,KAAK,EAAE,MAAM,GAAG,MAAM,CAKhG;AA0DD,wBAAgB,iBAAiB,CAAC,IAAI,EAAE,YAAY,GAAG,MAAM,CAE5D"}