sourcey 3.5.9 → 3.6.0

package/dist/config.js

@@ -1,7 +1,8 @@
-import { access, readdir } from "node:fs/promises";
-import { resolve, relative, dirname, basename, extname } from "node:path";
+import { access } from "node:fs/promises";
+import { resolve, dirname } from "node:path";
 import { createJiti } from "jiti";
 import { normalizeBaseUrl, normalizeSiteUrl } from "./site-url.js";
+import { doxygen as doxygenSource, godoc as godocSource, markdown as markdownSource, mcp as mcpSource, mkdocs as mkdocsSource, openapi as openapiSource, } from "./adapters/index.js";
 export function defineConfig(config) {
     return config;
 }
@@ -40,7 +41,7 @@ export async function loadConfig(configOrDir) {
             `  export default defineConfig({ navigation: { tabs: [...] } });\n`);
     }
     const jiti = createJiti(import.meta.url);
-    const mod = await jiti.import(configPath);
+    const mod = (await jiti.import(configPath));
     const raw = mod.default;
     if (!raw?.navigation?.tabs) {
         throw new Error("sourcey.config.ts must export default defineConfig({ navigation: { tabs: [...] } })");
@@ -60,12 +61,23 @@ export function configFromSpec(specPath) {
         theme: {
             preset: "default",
             colors: { ...DEFAULT_COLORS },
-            fonts: { sans: `'${DEFAULT_FONT_SANS}', ${SYSTEM_SANS}`, mono: SYSTEM_MONO, googleFont: DEFAULT_FONT_SANS },
+            fonts: {
+                sans: `'${DEFAULT_FONT_SANS}', ${SYSTEM_SANS}`,
+                mono: SYSTEM_MONO,
+                googleFont: DEFAULT_FONT_SANS,
+            },
             layout: { ...DEFAULT_LAYOUT },
             css: [],
         },
         codeSamples: ["curl", "javascript", "python"],
-        tabs: [{ label: "API Reference", slug: "api", openapi: absSpec }],
+        tabs: [
+            {
+                label: "API Reference",
+                slug: "api",
+                source: { kind: "openapi", spec: absSpec, watchPaths: [absSpec] },
+                openapi: absSpec,
+            },
+        ],
         navbar: { links: [] },
         footer: { links: [] },
         changelog: { enabled: true, feed: false, permalinks: false, ogImages: false },
@@ -87,8 +99,12 @@ export async function resolveConfigFromRaw(raw, configDir) {
         prettyUrls: resolvePrettyUrls(raw.prettyUrls),
         theme,
         logo,
-        favicon: raw.favicon && !raw.favicon.startsWith("http") && !raw.favicon.startsWith("data:") ? resolve(configDir, raw.favicon) : raw.favicon,
-        ogImage: raw.ogImage && !raw.ogImage.startsWith("http") && !raw.ogImage.startsWith("data:") ? resolve(configDir, raw.ogImage) : raw.ogImage,
+        favicon: raw.favicon && !raw.favicon.startsWith("http") && !raw.favicon.startsWith("data:")
+            ? resolve(configDir, raw.favicon)
+            : raw.favicon,
+        ogImage: raw.ogImage && !raw.ogImage.startsWith("http") && !raw.ogImage.startsWith("data:")
+            ? resolve(configDir, raw.ogImage)
+            : raw.ogImage,
         repo: raw.repo,
         editBranch: raw.editBranch,
         editBasePath: raw.editBasePath,
@@ -136,7 +152,7 @@ function resolveTheme(raw, configDir) {
         toc: raw.theme?.layout?.toc ?? DEFAULT_LAYOUT.toc,
         content: raw.theme?.layout?.content ?? DEFAULT_LAYOUT.content,
     };
-    const css = (raw.theme?.css ?? []).map(p => resolve(configDir, p));
+    const css = (raw.theme?.css ?? []).map((p) => resolve(configDir, p));
     return { preset, colors, fonts, layout, css };
 }
 function resolveLogo(logo, configDir) {
@@ -163,154 +179,79 @@ async function resolveTabs(tabs, configDir) {
     const resolved = [];
     for (const tab of tabs) {
         if (!tab.tab)
-            throw new Error("Tab missing \"tab\" name");
+            throw new Error('Tab missing "tab" name');
         const slug = tab.slug !== undefined ? tab.slug : slugify(tab.tab);
         if (slugs.has(slug))
             throw new Error(`Duplicate tab slug "${slug}" (from "${tab.tab}")`);
         slugs.add(slug);
-        const sources = [tab.openapi, tab.groups, tab.doxygen, tab.mcp, tab.godoc].filter(Boolean).length;
+        const sources = [
+            tab.source,
+            tab.openapi,
+            tab.mkdocs,
+            tab.groups,
+            tab.doxygen,
+            tab.mcp,
+            tab.godoc,
+        ].filter(Boolean).length;
         if (sources > 1) {
-            throw new Error(`Tab "${tab.tab}" has multiple sources; use only one of "openapi", "groups", "doxygen", "mcp", or "godoc"`);
+            throw new Error(`Tab "${tab.tab}" has multiple sources; use only one of "source", "openapi", "mkdocs", "groups", "doxygen", "mcp", or "godoc"`);
         }
         if (sources === 0) {
-            throw new Error(`Tab "${tab.tab}" needs one of "openapi", "groups", "doxygen", "mcp", or "godoc"`);
-        }
-        if (tab.openapi) {
-            if (isUrl(tab.openapi)) {
-                resolved.push({ label: tab.tab, slug, openapi: tab.openapi });
-            }
-            else {
-                const absPath = resolve(configDir, tab.openapi);
-                await assertExists(absPath, `OpenAPI spec "${tab.openapi}" in tab "${tab.tab}"`);
-                resolved.push({ label: tab.tab, slug, openapi: absPath });
-            }
-        }
-        else if (tab.mcp) {
-            if (isUrl(tab.mcp)) {
-                resolved.push({ label: tab.tab, slug, mcp: tab.mcp });
-            }
-            else {
-                const absPath = resolve(configDir, tab.mcp);
-                await assertExists(absPath, `MCP spec "${tab.mcp}" in tab "${tab.tab}"`);
-                resolved.push({ label: tab.tab, slug, mcp: absPath });
-            }
-        }
-        else if (tab.doxygen) {
-            const absXml = resolve(configDir, tab.doxygen.xml);
-            await assertExists(absXml, `Doxygen XML directory "${tab.doxygen.xml}" in tab "${tab.tab}"`);
-            resolved.push({
-                label: tab.tab,
-                slug,
-                doxygen: {
-                    xml: absXml,
-                    language: tab.doxygen.language ?? "cpp",
-                    groups: tab.doxygen.groups ?? false,
-                    index: tab.doxygen.index === false ? "none" : (tab.doxygen.index ?? "auto"),
-                },
-            });
-        }
-        else if (tab.godoc) {
-            const cfg = typeof tab.godoc === "string" ? { module: tab.godoc } : tab.godoc;
-            const moduleAbs = resolve(configDir, cfg.module ?? ".");
-            await assertExists(moduleAbs, `Go module directory "${cfg.module ?? "."}" in tab "${tab.tab}"`);
-            const snapshotAbs = cfg.snapshot ? resolve(configDir, cfg.snapshot) : undefined;
-            resolved.push({
-                label: tab.tab,
-                slug,
-                godoc: {
-                    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 ?? ""),
-                },
-            });
-        }
-        else {
-            const groups = await resolveGroups(tab.groups, tab.tab, configDir);
-            resolved.push({ label: tab.tab, slug, groups });
+            throw new Error(`Tab "${tab.tab}" needs one of "source", "openapi", "mkdocs", "groups", "doxygen", "mcp", or "godoc"`);
         }
+        const adapter = tab.source ?? legacySourceAdapter(tab);
+        const source = await adapter.resolve({
+            configDir,
+            tabName: tab.tab,
+            tabSlug: slug,
+            resolvePath: (path) => resolve(configDir, path),
+            assertExists,
+            isUrl,
+        });
+        resolved.push(resolvedTabFromSource(tab.tab, slug, source));
     }
     return resolved;
 }
-async function resolveGroups(groups, tabName, configDir) {
-    const resolved = [];
-    for (const group of groups) {
-        if (!group.group)
-            throw new Error(`Group missing "group" name in tab "${tabName}"`);
-        if (!group.pages?.length)
-            throw new Error(`Group "${group.group}" in tab "${tabName}" has no pages`);
-        const pages = [];
-        for (const pageSlug of group.pages) {
-            if (pageSlug.includes("*")) {
-                const expanded = await expandGlob(pageSlug, configDir);
-                for (const file of expanded) {
-                    const rel = relative(configDir, file).replace(/\.[^.]+$/, "");
-                    pages.push({ slug: rel, file });
-                }
-            }
-            else {
-                const absPath = await resolvePagePath(pageSlug, configDir);
-                pages.push({ slug: pageSlug, file: absPath });
-            }
-        }
-        resolved.push({ label: group.group, pages });
-    }
-    return resolved;
+function legacySourceAdapter(tab) {
+    if (tab.openapi)
+        return openapiSource(tab.openapi);
+    if (tab.mkdocs)
+        return mkdocsSource(tab.mkdocs);
+    if (tab.mcp)
+        return mcpSource(tab.mcp);
+    if (tab.doxygen)
+        return doxygenSource(tab.doxygen);
+    if (tab.godoc)
+        return godocSource(tab.godoc);
+    return markdownSource({ groups: tab.groups });
 }
-/**
- * Expand a simple glob pattern like "doc/api-*" into matching .md/.mdx files.
- * Supports trailing * only (e.g. "doc/api-*", "guides/*").
- */
-async function expandGlob(pattern, configDir) {
-    const absPattern = resolve(configDir, pattern);
-    const dir = dirname(absPattern);
-    const prefix = basename(absPattern).replace("*", "");
-    try {
-        const entries = await readdir(dir);
-        const matches = entries
-            .filter((f) => {
-            const ext = extname(f);
-            if (ext !== ".md" && ext !== ".mdx")
-                return false;
-            const name = basename(f, ext);
-            return prefix ? name.startsWith(prefix) : true;
-        })
-            .sort()
-            .map((f) => resolve(dir, f));
-        if (!matches.length) {
-            throw new Error(`Glob "${pattern}" matched no files in ${dir}`);
-        }
-        return matches;
-    }
-    catch (err) {
-        if (err.code === "ENOENT") {
-            throw new Error(`Glob directory not found: ${dir}`);
-        }
-        throw err;
+function resolvedTabFromSource(label, slug, source) {
+    const base = { label, slug, source };
+    switch (source.kind) {
+        case "openapi":
+            return { ...base, openapi: source.spec };
+        case "mcp":
+            return { ...base, mcp: source.spec };
+        case "markdown":
+            return {
+                ...base,
+                mkdocs: source.adapter === "mkdocs" ? source.configPath : undefined,
+                groups: source.groups,
+            };
+        case "doxygen":
+            return { ...base, doxygen: source.config };
+        case "godoc":
+            return { ...base, godoc: source.config };
     }
 }
-async function resolvePagePath(slug, configDir) {
-    for (const ext of [".md", ".mdx"]) {
-        const candidate = resolve(configDir, `${slug}${ext}`);
-        try {
-            await access(candidate);
-            return candidate;
-        }
-        catch { /* try next */ }
-    }
-    throw new Error(`Page "${slug}" not found (tried ${slug}.md, ${slug}.mdx in ${configDir})`);
-}
 // ---------------------------------------------------------------------------
 // Utilities
 // ---------------------------------------------------------------------------
 export function slugify(name) {
-    return name.toLowerCase().replace(/[^a-z0-9]+/g, "-").replace(/^-|-$/g, "");
+    return name
+        .toLowerCase()
+        .replace(/[^a-z0-9]+/g, "-")
+        .replace(/^-|-$/g, "");
 }
 /** Build a path under a tab, handling empty slugs (root-level tabs). */
 export function tabPath(tabSlug, file) {
@@ -358,9 +299,6 @@ export function hexToRgb(hex) {
     const b = parseInt(h.slice(4, 6), 16);
     return `${r} ${g} ${b}`;
 }
-function trimSlashes(path) {
-    return path.replace(/^\/+|\/+$/g, "");
-}
 async function assertExists(filePath, label) {
     try {
         await access(filePath);

package/dist/core/doxygen-loader.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"doxygen-loader.d.ts","sourceRoot":"","sources":["../../src/core/doxygen-loader.ts"],"names":[],"mappings":"AACA,OAAO,KAAK,EAAqB,qBAAqB,EAAE,MAAM,cAAc,CAAC;AAE7E,OAAO,KAAK,EAAE,YAAY,EAAE,MAAM,sBAAsB,CAAC;AACzD,OAAO,KAAK,EAAE,OAAO,EAA6B,MAAM,iBAAiB,CAAC;AAM1E,MAAM,WAAW,aAAa;IAC5B,KAAK,EAAE,GAAG,CAAC,MAAM,EAAE,YAAY,CAAC,CAAC;IACjC,MAAM,EAAE,OAAO,CAAC;CACjB;AAED,wBAAgB,2BAA2B,CAAC,WAAW,EAAE,MAAM,EAAE,QAAQ,EAAE,MAAM,GAAG,MAAM,CAMzF;AAED,wBAAgB,kCAAkC,CAAC,WAAW,EAAE,MAAM,GAAG,MAAM,CAoB9E;AAED,wBAAgB,+BAA+B,CAAC,QAAQ,EAAE,MAAM,GAAG,MAAM,CAIxE;AAED,wBAAgB,2BAA2B,CAAC,IAAI,EAAE,MAAM,GAAG,MAAM,CAShE;AAED,wBAAgB,gCAAgC,CAAC,IAAI,EAAE,MAAM,GAAG,MAAM,CAcrE;AAED,wBAAsB,cAAc,CAClC,MAAM,EAAE,qBAAqB,EAC7B,OAAO,EAAE,MAAM,EACf,QAAQ,EAAE,MAAM,GACf,OAAO,CAAC,aAAa,CAAC,CAkGxB"}
+{"version":3,"file":"doxygen-loader.d.ts","sourceRoot":"","sources":["../../src/core/doxygen-loader.ts"],"names":[],"mappings":"AACA,OAAO,KAAK,EAAqB,qBAAqB,EAAE,MAAM,cAAc,CAAC;AAE7E,OAAO,KAAK,EAAE,YAAY,EAAE,MAAM,sBAAsB,CAAC;AACzD,OAAO,KAAK,EAAE,OAAO,EAA6B,MAAM,iBAAiB,CAAC;AAM1E,MAAM,WAAW,aAAa;IAC5B,KAAK,EAAE,GAAG,CAAC,MAAM,EAAE,YAAY,CAAC,CAAC;IACjC,MAAM,EAAE,OAAO,CAAC;CACjB;AAED,wBAAgB,2BAA2B,CAAC,WAAW,EAAE,MAAM,EAAE,QAAQ,EAAE,MAAM,GAAG,MAAM,CAMzF;AAED,wBAAgB,kCAAkC,CAAC,WAAW,EAAE,MAAM,GAAG,MAAM,CAoB9E;AAED,wBAAgB,+BAA+B,CAAC,QAAQ,EAAE,MAAM,GAAG,MAAM,CAIxE;AAED,wBAAgB,2BAA2B,CAAC,IAAI,EAAE,MAAM,GAAG,MAAM,CAShE;AAED,wBAAgB,gCAAgC,CAAC,IAAI,EAAE,MAAM,GAAG,MAAM,CAcrE;AAED,wBAAsB,cAAc,CAClC,MAAM,EAAE,qBAAqB,EAC7B,OAAO,EAAE,MAAM,EACf,QAAQ,EAAE,MAAM,GACf,OAAO,CAAC,aAAa,CAAC,CAoGxB"}

package/dist/core/doxygen-loader.js

@@ -59,6 +59,7 @@ export async function loadDoxygenTab(config, tabSlug, tabLabel) {
     const generated = await generate({
         directory: config.xml,
         language: config.language,
+        sourceUrl: config.sourceUrl,
         quiet: true,
     });
     const pages = new Map();
@@ -79,6 +80,7 @@ export async function loadDoxygenTab(config, tabSlug, tabLabel) {
             headings,
             sourcePath: `api/${page.slug}.md`,
             editPath: page.kind === "group" ? `api/${page.slug}.md` : null,
+            searchEntries: page.searchEntries,
         });
         // Group by the last segment of namespace (e.g. "icy::http" -> "http")
         const groupKey = page.module ?? lastSegment(page.namespace) ?? "API";

package/dist/core/markdown-loader.d.ts

@@ -20,12 +20,19 @@ export interface MarkdownPage {
     editBasePath?: string | null;
     /** Optional page-local entries that should be indexed in addition to headings. */
     searchEntries?: PageSearchEntry[];
+    /** Optional source root used to rewrite source-format-relative assets. */
+    sourceRoot?: string;
 }
 export interface PageSearchEntry {
     title: string;
     content: string;
     anchor?: string;
     category: string;
+    symbolKind?: string;
+    owner?: string;
+    ownerKind?: string;
+    namespace?: string;
+    qualifiedName?: string;
 }
 export interface ChangelogPage {
     kind: "changelog";
@@ -45,7 +52,14 @@ export type { PageHeading } from "../utils/markdown.js";
 export interface LoadDocsPageOptions {
     changelog?: boolean;
     repoUrl?: string;
+    sourceRoot?: string;
+    preprocess?: MarkdownPreprocessor[];
 }
+export interface MarkdownPreprocessContext {
+    filePath: string;
+    sourceRoot?: string;
+}
+export type MarkdownPreprocessor = (body: string, context: MarkdownPreprocessContext) => string;
 /**
  * Load a single markdown file and return a MarkdownPage.
  */

package/dist/core/markdown-loader.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"markdown-loader.d.ts","sourceRoot":"","sources":["../../src/core/markdown-loader.ts"],"names":[],"mappings":"AAMA,OAAO,EAKL,KAAK,WAAW,EACjB,MAAM,sBAAsB,CAAC;AAC9B,OAAO,KAAK,EAAE,mBAAmB,EAAE,MAAM,YAAY,CAAC;AAMtD,MAAM,WAAW,YAAY;IAC3B,IAAI,EAAE,UAAU,CAAC;IACjB,kCAAkC;IAClC,KAAK,EAAE,MAAM,CAAC;IACd,wCAAwC;IACxC,WAAW,EAAE,MAAM,CAAC;IACpB,qDAAqD;IACrD,IAAI,EAAE,MAAM,CAAC;IACb,yBAAyB;IACzB,IAAI,EAAE,MAAM,CAAC;IACb,qDAAqD;IACrD,QAAQ,EAAE,WAAW,EAAE,CAAC;IACxB,sEAAsE;IACtE,UAAU,EAAE,MAAM,CAAC;IACnB,2FAA2F;IAC3F,QAAQ,CAAC,EAAE,MAAM,GAAG,IAAI,CAAC;IACzB,8FAA8F;IAC9F,YAAY,CAAC,EAAE,MAAM,GAAG,IAAI,CAAC;IAC7B,kFAAkF;IAClF,aAAa,CAAC,EAAE,eAAe,EAAE,CAAC;CACnC;AAED,MAAM,WAAW,eAAe;IAC9B,KAAK,EAAE,MAAM,CAAC;IACd,OAAO,EAAE,MAAM,CAAC;IAChB,MAAM,CAAC,EAAE,MAAM,CAAC;IAChB,QAAQ,EAAE,MAAM,CAAC;CAClB;AAED,MAAM,WAAW,aAAa;IAC5B,IAAI,EAAE,WAAW,CAAC;IAClB,KAAK,EAAE,MAAM,CAAC;IACd,WAAW,EAAE,MAAM,CAAC;IACpB,IAAI,EAAE,MAAM,CAAC;IACb,QAAQ,EAAE,WAAW,EAAE,CAAC;IACxB,UAAU,EAAE,MAAM,CAAC;IACnB,QAAQ,CAAC,EAAE,MAAM,GAAG,IAAI,CAAC;IACzB,SAAS,EAAE,mBAAmB,CAAC;IAC/B,OAAO,EAAE,MAAM,CAAC;IAChB,iFAAiF;IACjF,kBAAkB,CAAC,EAAE,MAAM,CAAC;CAC7B;AAED,MAAM,MAAM,QAAQ,GAAG,YAAY,GAAG,aAAa,CAAC;AAEpD,YAAY,EAAE,WAAW,EAAE,MAAM,sBAAsB,CAAC;AAUxD,MAAM,WAAW,mBAAmB;IAClC,SAAS,CAAC,EAAE,OAAO,CAAC;IACpB,OAAO,CAAC,EAAE,MAAM,CAAC;CAClB;AAgnCD;;GAEG;AACH,wBAAsB,gBAAgB,CACpC,QAAQ,EAAE,MAAM,EAChB,IAAI,EAAE,MAAM,GACX,OAAO,CAAC,YAAY,CAAC,CAKvB;AAED,wBAAsB,YAAY,CAChC,QAAQ,EAAE,MAAM,EAChB,IAAI,EAAE,MAAM,EACZ,OAAO,GAAE,mBAAwB,GAChC,OAAO,CAAC,QAAQ,CAAC,CAiCnB;AAuDD;;;;;;GAMG;AACH,wBAAgB,YAAY,CAAC,QAAQ,EAAE,MAAM,GAAG,MAAM,CAIrD"}
+{"version":3,"file":"markdown-loader.d.ts","sourceRoot":"","sources":["../../src/core/markdown-loader.ts"],"names":[],"mappings":"AAMA,OAAO,EAOL,KAAK,WAAW,EACjB,MAAM,sBAAsB,CAAC;AAC9B,OAAO,KAAK,EAAE,mBAAmB,EAAE,MAAM,YAAY,CAAC;AAMtD,MAAM,WAAW,YAAY;IAC3B,IAAI,EAAE,UAAU,CAAC;IACjB,kCAAkC;IAClC,KAAK,EAAE,MAAM,CAAC;IACd,wCAAwC;IACxC,WAAW,EAAE,MAAM,CAAC;IACpB,qDAAqD;IACrD,IAAI,EAAE,MAAM,CAAC;IACb,yBAAyB;IACzB,IAAI,EAAE,MAAM,CAAC;IACb,qDAAqD;IACrD,QAAQ,EAAE,WAAW,EAAE,CAAC;IACxB,sEAAsE;IACtE,UAAU,EAAE,MAAM,CAAC;IACnB,2FAA2F;IAC3F,QAAQ,CAAC,EAAE,MAAM,GAAG,IAAI,CAAC;IACzB,8FAA8F;IAC9F,YAAY,CAAC,EAAE,MAAM,GAAG,IAAI,CAAC;IAC7B,kFAAkF;IAClF,aAAa,CAAC,EAAE,eAAe,EAAE,CAAC;IAClC,0EAA0E;IAC1E,UAAU,CAAC,EAAE,MAAM,CAAC;CACrB;AAED,MAAM,WAAW,eAAe;IAC9B,KAAK,EAAE,MAAM,CAAC;IACd,OAAO,EAAE,MAAM,CAAC;IAChB,MAAM,CAAC,EAAE,MAAM,CAAC;IAChB,QAAQ,EAAE,MAAM,CAAC;IACjB,UAAU,CAAC,EAAE,MAAM,CAAC;IACpB,KAAK,CAAC,EAAE,MAAM,CAAC;IACf,SAAS,CAAC,EAAE,MAAM,CAAC;IACnB,SAAS,CAAC,EAAE,MAAM,CAAC;IACnB,aAAa,CAAC,EAAE,MAAM,CAAC;CACxB;AAED,MAAM,WAAW,aAAa;IAC5B,IAAI,EAAE,WAAW,CAAC;IAClB,KAAK,EAAE,MAAM,CAAC;IACd,WAAW,EAAE,MAAM,CAAC;IACpB,IAAI,EAAE,MAAM,CAAC;IACb,QAAQ,EAAE,WAAW,EAAE,CAAC;IACxB,UAAU,EAAE,MAAM,CAAC;IACnB,QAAQ,CAAC,EAAE,MAAM,GAAG,IAAI,CAAC;IACzB,SAAS,EAAE,mBAAmB,CAAC;IAC/B,OAAO,EAAE,MAAM,CAAC;IAChB,iFAAiF;IACjF,kBAAkB,CAAC,EAAE,MAAM,CAAC;CAC7B;AAED,MAAM,MAAM,QAAQ,GAAG,YAAY,GAAG,aAAa,CAAC;AAEpD,YAAY,EAAE,WAAW,EAAE,MAAM,sBAAsB,CAAC;AAUxD,MAAM,WAAW,mBAAmB;IAClC,SAAS,CAAC,EAAE,OAAO,CAAC;IACpB,OAAO,CAAC,EAAE,MAAM,CAAC;IACjB,UAAU,CAAC,EAAE,MAAM,CAAC;IACpB,UAAU,CAAC,EAAE,oBAAoB,EAAE,CAAC;CACrC;AAED,MAAM,WAAW,yBAAyB;IACxC,QAAQ,EAAE,MAAM,CAAC;IACjB,UAAU,CAAC,EAAE,MAAM,CAAC;CACrB;AAED,MAAM,MAAM,oBAAoB,GAAG,CAAC,IAAI,EAAE,MAAM,EAAE,OAAO,EAAE,yBAAyB,KAAK,MAAM,CAAC;AAknChG;;GAEG;AACH,wBAAsB,gBAAgB,CAAC,QAAQ,EAAE,MAAM,EAAE,IAAI,EAAE,MAAM,GAAG,OAAO,CAAC,YAAY,CAAC,CAK5F;AAED,wBAAsB,YAAY,CAChC,QAAQ,EAAE,MAAM,EAChB,IAAI,EAAE,MAAM,EACZ,OAAO,GAAE,mBAAwB,GAChC,OAAO,CAAC,QAAQ,CAAC,CAgCnB;AA+DD;;;;;;GAMG;AACH,wBAAgB,YAAY,CAAC,QAAQ,EAAE,MAAM,GAAG,MAAM,CAOrD"}

package/dist/core/markdown-loader.js

@@ -1,10 +1,10 @@
-import { readFile } from "node:fs/promises";
+import { readFile as readFileAsync } from "node:fs/promises";
 import { basename, extname, relative } from "node:path";
 import { load as parseYaml } from "js-yaml";
 import { normalizeChangelog } from "./changelog-normalizer.js";
 import { htmlId } from "../utils/html-id.js";
 import { renderIcon } from "../utils/icons.js";
-import { renderCodeBlock, renderMarkdown, renderMarkdownInline, extractHeadings, } from "../utils/markdown.js";
+import { renderCodeBlock, renderMarkdown, renderMarkdownInline, extractHeadings, extractFirstParagraph, stripMarkdownLinks, } from "../utils/markdown.js";
 // ---------------------------------------------------------------------------
 // Frontmatter parsing
 // ---------------------------------------------------------------------------
@@ -502,7 +502,10 @@ ${body}
             return null;
         return `\n\n${buildTabbedHtml(codeBlocks, nextId("cg"), "directive-code-group")}\n`;
     }
-    if (node.name === "Note" || node.name === "Warning" || node.name === "Tip" || node.name === "Info") {
+    if (node.name === "Note" ||
+        node.name === "Warning" ||
+        node.name === "Tip" ||
+        node.name === "Info") {
         const type = node.name.toLowerCase();
         const label = renderMarkdownInline(node.attrs.title?.trim() || node.name.charAt(0).toUpperCase() + node.name.slice(1)).trim();
         const body = renderComponentChildrenToHtml(node.children);
@@ -562,10 +565,7 @@ function escapeRegExp(value) {
     return value.replace(/[.*+?^${}()|[\]\\]/g, "\\$&");
 }
 function escapeHtmlAttr(value) {
-    return value
-        .replace(/&/g, "&")
-        .replace(/"/g, """)
-        .replace(/</g, "&lt;");
+    return value.replace(/&/g, "&amp;").replace(/"/g, "&quot;").replace(/</g, "&lt;");
 }
 function stripDirectiveIndent(line) {
     return line.replace(/^ {0,3}/, "");
@@ -585,9 +585,7 @@ function closesFence(line, fence) {
 }
 /** Build tabbed UI HTML (shared by :::tabs and :::code-group). */
 function buildTabbedHtml(tabs, id, extraClass) {
-    const cls = extraClass
-        ? `directive-tabs ${extraClass} not-prose`
-        : "directive-tabs not-prose";
+    const cls = extraClass ? `directive-tabs ${extraClass} not-prose` : "directive-tabs not-prose";
     const buttons = tabs
         .map((t, i) => `<button class="directive-tab${i === 0 ? " active" : ""}" data-tab-group="${id}" data-tab-index="${i}">${t.title}</button>`)
         .join("\n");
@@ -652,7 +650,10 @@ function splitChildren(content, marker) {
         }
         children.push({
             attrs: parseAttrs(start[1] ?? ""),
-            body: lines.slice(i + 1, j).join("\n").trim(),
+            body: lines
+                .slice(i + 1, j)
+                .join("\n")
+                .trim(),
         });
         i = j + 1;
     }
@@ -696,7 +697,9 @@ const SUPPORTED_DIRECTIVES = new Set([
     "accordion",
 ]);
 function matchDirectiveStart(line) {
-    const match = stripDirectiveIndent(line).trimEnd().match(/^:::(\w[\w-]*)(.*)$/);
+    const match = stripDirectiveIndent(line)
+        .trimEnd()
+        .match(/^:::(\w[\w-]*)(.*)$/);
     if (!match || !SUPPORTED_DIRECTIVES.has(match[1]))
         return null;
     return {
@@ -927,12 +930,12 @@ function preprocessDirectives(body) {
  * Load a single markdown file and return a MarkdownPage.
  */
 export async function loadMarkdownPage(filePath, slug) {
-    const raw = await readFile(filePath, "utf-8");
+    const raw = await readFileAsync(filePath, "utf-8");
     const { meta, body } = parseFrontmatter(raw);
     return loadMarkdownPageFromBody(filePath, slug, body, meta);
 }
 export async function loadDocsPage(filePath, slug, options = {}) {
-    const raw = await readFile(filePath, "utf-8");
+    const raw = await readFileAsync(filePath, "utf-8");
     const { meta, body } = parseFrontmatter(raw);
     if (shouldTreatAsChangelog(filePath, meta, options)) {
         const sourcePath = relative(process.cwd(), filePath);
@@ -941,9 +944,7 @@ export async function loadDocsPage(filePath, slug, options = {}) {
             description: typeof meta.description === "string" ? meta.description : undefined,
             repoUrl: options.repoUrl,
         });
-        const description = typeof meta.description === "string"
-            ? meta.description
-            : changelog.description ?? "";
+        const description = typeof meta.description === "string" ? meta.description : (changelog.description ?? "");
         return {
             kind: "changelog",
             title: changelog.title,
@@ -960,7 +961,7 @@ export async function loadDocsPage(filePath, slug, options = {}) {
             rawBody: body,
         };
     }
-    return loadMarkdownPageFromBody(filePath, slug, body, meta);
+    return loadMarkdownPageFromBody(filePath, slug, body, meta, options);
 }
 function shouldTreatAsChangelog(filePath, meta, options) {
     if (options.changelog === false)
@@ -969,14 +970,15 @@ function shouldTreatAsChangelog(filePath, meta, options) {
         return true;
     return basename(filePath).toLowerCase() === "changelog.md";
 }
-function loadMarkdownPageFromBody(filePath, slug, body, meta) {
+function loadMarkdownPageFromBody(filePath, slug, body, meta, options = {}) {
     resetDirectiveCounter();
-    const componentPreprocessed = preprocessComponents(body);
+    const sourcePreprocessed = preprocessSourceMarkdown(body, filePath, options);
+    const componentPreprocessed = preprocessComponents(sourcePreprocessed);
     const preprocessed = preprocessDirectives(componentPreprocessed);
     const headings = extractHeadings(componentPreprocessed);
     const html = renderMarkdown(preprocessed);
     const title = meta.title ?? extractFirstHeading(componentPreprocessed) ?? slug;
-    const description = meta.description ?? "";
+    const description = normalizeMarkdownDescription(meta.description, componentPreprocessed);
     // Strip leading h1 from rendered HTML when it duplicates the page title
     const cleanHtml = html.replace(/^\s*<h1[^>]*>(.*?)<\/h1>\s*/i, (_m, inner) => inner.replace(/<[^>]+>/g, "").trim() === title ? "" : _m);
     const sourcePath = relative(process.cwd(), filePath);
@@ -989,8 +991,15 @@ function loadMarkdownPageFromBody(filePath, slug, body, meta) {
         headings,
         sourcePath,
         editPath: sourcePath,
+        sourceRoot: options.sourceRoot ? relative(process.cwd(), options.sourceRoot) : undefined,
     };
 }
+function normalizeMarkdownDescription(description, markdown) {
+    if (typeof description === "string" && description.trim()) {
+        return description;
+    }
+    return stripMarkdownLinks(extractFirstParagraph(markdown)).replace(/\s+/g, " ").trim();
+}
 /**
  * Extract the first # heading from markdown as a fallback title.
  */
@@ -1008,5 +1017,37 @@ function extractFirstHeading(md) {
 export function slugFromPath(filePath) {
     const ext = extname(filePath);
     const stripped = ext ? filePath.slice(0, -ext.length) : filePath;
-    return stripped.split("/").map((s) => htmlId(s)).join("/");
+    return stripped
+        .split("/")
+        .map((s) => slugSegmentFromPath(s))
+        .join("/");
+}
+function slugSegmentFromPath(segment) {
+    const normalized = segment
+        .replace(/^operator=$/, "operator-assign")
+        .replace(/^~(.+)$/, "destructor-$1")
+        .replace(/<=>/g, "-spaceship")
+        .replace(/<=/g, "-le")
+        .replace(/>=/g, "-ge")
+        .replace(/==/g, "-eq")
+        .replace(/!=/g, "-ne")
+        .replace(/\[\]/g, "-array")
+        .replace(/\+=/g, "-plus-eq")
+        .replace(/\/=/g, "-slash-eq")
+        .replace(/\//g, "-slash")
+        .replace(/=/g, "-eq")
+        .replace(/\+/g, "-plus")
+        .replace(/</g, "-lt")
+        .replace(/>/g, "-gt");
+    return htmlId(normalized);
+}
+function preprocessSourceMarkdown(body, filePath, options) {
+    let current = body;
+    for (const preprocess of options.preprocess ?? []) {
+        current = preprocess(current, {
+            filePath,
+            sourceRoot: options.sourceRoot,
+        });
+    }
+    return current;
 }

package/dist/core/navigation.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"navigation.d.ts","sourceRoot":"","sources":["../../src/core/navigation.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,cAAc,EAAE,MAAM,YAAY,CAAC;AAGjD,OAAO,KAAK,EAAE,WAAW,EAAE,MAAM,cAAc,CAAC;AAChD,OAAO,KAAK,EAAE,QAAQ,EAAE,MAAM,sBAAsB,CAAC;AAErD,OAAO,EAAgB,KAAK,UAAU,EAAE,MAAM,gBAAgB,CAAC;AAgB/D,MAAM,WAAW,cAAc;IAC7B,IAAI,EAAE,OAAO,EAAE,CAAC;IAChB,aAAa,EAAE,MAAM,CAAC;IACtB,cAAc,EAAE,MAAM,CAAC;CACxB;AAED,MAAM,WAAW,OAAO;IACtB,KAAK,EAAE,MAAM,CAAC;IACd,IAAI,EAAE,MAAM,CAAC;IACb,6DAA6D;IAC7D,IAAI,EAAE,MAAM,CAAC;IACb,IAAI,EAAE,MAAM,GAAG,MAAM,CAAC;IACtB,MAAM,EAAE,YAAY,EAAE,CAAC;CACxB;AAED,MAAM,WAAW,YAAY;IAC3B,KAAK,EAAE,MAAM,CAAC;IACd,KAAK,EAAE,WAAW,EAAE,CAAC;CACtB;AAED,MAAM,WAAW,WAAW;IAC1B,KAAK,EAAE,MAAM,CAAC;IACd,iDAAiD;IACjD,IAAI,EAAE,MAAM,CAAC;IACb,0CAA0C;IAC1C,EAAE,EAAE,MAAM,CAAC;IACX,kEAAkE;IAClE,MAAM,CAAC,EAAE,MAAM,CAAC;CACjB;AAMD;;;;;GAKG;AACH,wBAAgB,gBAAgB,CAC9B,IAAI,EAAE,cAAc,EACpB,OAAO,EAAE,MAAM,EACf,UAAU,GAAE,UAAkB,GAC7B,OAAO,CAiDT;AAED;;;GAGG;AACH,wBAAgB,iBAAiB,CAC/B,GAAG,EAAE,WAAW,EAChB,WAAW,EAAE,GAAG,CAAC,MAAM,EAAE,QAAQ,CAAC,EAClC,UAAU,GAAE,UAAkB,GAC7B,OAAO,CA6BT;AAED;;;GAGG;AACH,wBAAgB,mBAAmB,CAAC,IAAI,EAAE,OAAO,EAAE,GAAG,cAAc,CASnE;AAED;;GAEG;AACH,wBAAgB,cAAc,CAC5B,GAAG,EAAE,cAAc,EACnB,OAAO,EAAE,MAAM,EACf,QAAQ,EAAE,MAAM,GACf,cAAc,CAEhB"}
+{"version":3,"file":"navigation.d.ts","sourceRoot":"","sources":["../../src/core/navigation.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,cAAc,EAAE,MAAM,YAAY,CAAC;AAGjD,OAAO,KAAK,EAAE,WAAW,EAAE,MAAM,cAAc,CAAC;AAChD,OAAO,KAAK,EAAE,QAAQ,EAAE,MAAM,sBAAsB,CAAC;AAErD,OAAO,EAAgB,KAAK,UAAU,EAAE,MAAM,gBAAgB,CAAC;AAgB/D,MAAM,WAAW,cAAc;IAC7B,IAAI,EAAE,OAAO,EAAE,CAAC;IAChB,aAAa,EAAE,MAAM,CAAC;IACtB,cAAc,EAAE,MAAM,CAAC;CACxB;AAED,MAAM,WAAW,OAAO;IACtB,KAAK,EAAE,MAAM,CAAC;IACd,IAAI,EAAE,MAAM,CAAC;IACb,6DAA6D;IAC7D,IAAI,EAAE,MAAM,CAAC;IACb,IAAI,EAAE,MAAM,GAAG,MAAM,CAAC;IACtB,MAAM,EAAE,YAAY,EAAE,CAAC;CACxB;AAED,MAAM,WAAW,YAAY;IAC3B,KAAK,EAAE,MAAM,CAAC;IACd,KAAK,EAAE,WAAW,EAAE,CAAC;CACtB;AAED,MAAM,WAAW,WAAW;IAC1B,KAAK,EAAE,MAAM,CAAC;IACd,iDAAiD;IACjD,IAAI,EAAE,MAAM,CAAC;IACb,0CAA0C;IAC1C,EAAE,EAAE,MAAM,CAAC;IACX,kEAAkE;IAClE,MAAM,CAAC,EAAE,MAAM,CAAC;CACjB;AAMD;;;;;GAKG;AACH,wBAAgB,gBAAgB,CAC9B,IAAI,EAAE,cAAc,EACpB,OAAO,EAAE,MAAM,EACf,UAAU,GAAE,UAAkB,GAC7B,OAAO,CAiDT;AAED;;;GAGG;AACH,wBAAgB,iBAAiB,CAC/B,GAAG,EAAE,WAAW,EAChB,WAAW,EAAE,GAAG,CAAC,MAAM,EAAE,QAAQ,CAAC,EAClC,UAAU,GAAE,UAAkB,GAC7B,OAAO,CA8BT;AAED;;;GAGG;AACH,wBAAgB,mBAAmB,CAAC,IAAI,EAAE,OAAO,EAAE,GAAG,cAAc,CASnE;AAED;;GAEG;AACH,wBAAgB,cAAc,CAC5B,GAAG,EAAE,cAAc,EACnB,OAAO,EAAE,MAAM,EACf,QAAQ,EAAE,MAAM,GACf,cAAc,CAEhB"}

package/dist/core/navigation.js

@@ -73,31 +73,32 @@ export function buildNavFromSpec(spec, tabSlug, prettyUrls = false) {
  * Groups come from the config; items come from loaded page data.
  */
 export function buildNavFromPages(tab, pagesByPath, prettyUrls = false) {
-    const groups = [];
-    if (tab.groups) {
-        for (const group of tab.groups) {
+    const navGroups = [];
+    const sourceGroups = tab.source.kind === "markdown" ? tab.source.groups : tab.groups;
+    if (sourceGroups) {
+        for (const group of sourceGroups) {
             const items = [];
             for (const rp of group.pages) {
                 const page = pagesByPath.get(rp.slug);
                 if (!page)
                     continue;
                 items.push({
-                    label: page.title,
+                    label: rp.label ?? page.title,
                     href: navHref(pageOutputPath(tab.slug, page.slug, prettyUrls), prettyUrls),
                     id: page.slug,
                 });
             }
-            groups.push({ label: group.label, items });
+            navGroups.push({ label: group.label, items });
         }
     }
-    const firstItem = groups[0]?.items[0];
+    const firstItem = navGroups[0]?.items[0];
     const href = firstItem?.href ?? (tab.slug ? `${tab.slug}/` : "");
     return {
         label: tab.label,
         slug: tab.slug,
         href,
         kind: "docs",
-        groups,
+        groups: navGroups,
     };
 }
 /**

package/dist/core/search-indexer.d.ts

@@ -19,6 +19,16 @@ export interface SearchEntry {
     category: string;
     /** Featured in default search results */
     featured?: boolean;
+    /** Source adapter symbol kind, e.g. C++ function, enumvalue, typedef */
+    symbolKind?: string;
+    /** Owning symbol, e.g. icy::Application */
+    owner?: string;
+    /** Owning symbol kind, e.g. class, struct, enum */
+    ownerKind?: string;
+    /** Namespace for source languages that expose one */
+    namespace?: string;
+    /** Fully qualified symbol name */
+    qualifiedName?: string;
 }
 /**
  * Build a search index from specs and markdown pages.

package/dist/core/search-indexer.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"search-indexer.d.ts","sourceRoot":"","sources":["../../src/core/search-indexer.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,cAAc,EAAE,MAAM,YAAY,CAAC;AACjD,OAAO,KAAK,EAAE,QAAQ,EAAE,MAAM,sBAAsB,CAAC;AACrD,OAAO,KAAK,EAAE,cAAc,EAAE,MAAM,iBAAiB,CAAC;AACtD,OAAO,KAAK,EAAE,UAAU,EAAE,MAAM,gBAAgB,CAAC;AASjD,MAAM,WAAW,WAAW;IAC1B,oBAAoB;IACpB,KAAK,EAAE,MAAM,CAAC;IACd,gDAAgD;IAChD,OAAO,EAAE,MAAM,CAAC;IAChB,mDAAmD;IACnD,GAAG,EAAE,MAAM,CAAC;IACZ,qCAAqC;IACrC,MAAM,CAAC,EAAE,MAAM,CAAC;IAChB,8BAA8B;IAC9B,IAAI,CAAC,EAAE,MAAM,CAAC;IACd,gCAAgC;IAChC,GAAG,EAAE,MAAM,CAAC;IACZ,oCAAoC;IACpC,QAAQ,EAAE,MAAM,CAAC;IACjB,yCAAyC;IACzC,QAAQ,CAAC,EAAE,OAAO,CAAC;CACpB;AAMD;;;GAGG;AACH,wBAAgB,gBAAgB,CAC9B,KAAK,EAAE,GAAG,CAAC,MAAM,EAAE,cAAc,CAAC,EAClC,KAAK,EAAE,GAAG,CAAC,MAAM,EAAE,QAAQ,EAAE,CAAC,EAC9B,UAAU,EAAE,cAAc,EAC1B,SAAS,SAAM,EACf,aAAa,GAAE,MAAM,EAAO,EAC5B,UAAU,GAAE,UAAkB,GAC7B,MAAM,CA4FR"}
+{"version":3,"file":"search-indexer.d.ts","sourceRoot":"","sources":["../../src/core/search-indexer.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,cAAc,EAAE,MAAM,YAAY,CAAC;AACjD,OAAO,KAAK,EAAE,QAAQ,EAAE,MAAM,sBAAsB,CAAC;AACrD,OAAO,KAAK,EAAE,cAAc,EAAE,MAAM,iBAAiB,CAAC;AACtD,OAAO,KAAK,EAAE,UAAU,EAAE,MAAM,gBAAgB,CAAC;AASjD,MAAM,WAAW,WAAW;IAC1B,oBAAoB;IACpB,KAAK,EAAE,MAAM,CAAC;IACd,gDAAgD;IAChD,OAAO,EAAE,MAAM,CAAC;IAChB,mDAAmD;IACnD,GAAG,EAAE,MAAM,CAAC;IACZ,qCAAqC;IACrC,MAAM,CAAC,EAAE,MAAM,CAAC;IAChB,8BAA8B;IAC9B,IAAI,CAAC,EAAE,MAAM,CAAC;IACd,gCAAgC;IAChC,GAAG,EAAE,MAAM,CAAC;IACZ,oCAAoC;IACpC,QAAQ,EAAE,MAAM,CAAC;IACjB,yCAAyC;IACzC,QAAQ,CAAC,EAAE,OAAO,CAAC;IACnB,wEAAwE;IACxE,UAAU,CAAC,EAAE,MAAM,CAAC;IACpB,2CAA2C;IAC3C,KAAK,CAAC,EAAE,MAAM,CAAC;IACf,mDAAmD;IACnD,SAAS,CAAC,EAAE,MAAM,CAAC;IACnB,qDAAqD;IACrD,SAAS,CAAC,EAAE,MAAM,CAAC;IACnB,kCAAkC;IAClC,aAAa,CAAC,EAAE,MAAM,CAAC;CACxB;AAMD;;;GAGG;AACH,wBAAgB,gBAAgB,CAC9B,KAAK,EAAE,GAAG,CAAC,MAAM,EAAE,cAAc,CAAC,EAClC,KAAK,EAAE,GAAG,CAAC,MAAM,EAAE,QAAQ,EAAE,CAAC,EAC9B,UAAU,EAAE,cAAc,EAC1B,SAAS,SAAM,EACf,aAAa,GAAE,MAAM,EAAO,EAC5B,UAAU,GAAE,UAAkB,GAC7B,MAAM,CAiGR"}

package/dist/core/search-indexer.js

@@ -75,6 +75,11 @@ export function buildSearchIndex(specs, pages, navigation, assetBase = "/", feat
                         url: entry.anchor ? `${href}#${entry.anchor}` : href,
                         tab: tabLabel,
                         category: entry.category,
+                        ...(entry.symbolKind && { symbolKind: entry.symbolKind }),
+                        ...(entry.owner && { owner: entry.owner }),
+                        ...(entry.ownerKind && { ownerKind: entry.ownerKind }),
+                        ...(entry.namespace && { namespace: entry.namespace }),
+                        ...(entry.qualifiedName && { qualifiedName: entry.qualifiedName }),
                     });
                 }
             }

package/dist/dev-server.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"dev-server.d.ts","sourceRoot":"","sources":["../src/dev-server.ts"],"names":[],"mappings":"AA+CA,MAAM,WAAW,gBAAgB;IAC/B,IAAI,EAAE,MAAM,CAAC;IACb,IAAI,CAAC,EAAE,MAAM,CAAC;IACd,MAAM,CAAC,EAAE,MAAM,CAAC;IAChB,eAAe,CAAC,EAAE,OAAO,CAAC;CAC3B;AAED,wBAAsB,cAAc,CAAC,OAAO,EAAE,gBAAgB,GAAG,OAAO,CAAC,IAAI,CAAC,CAyZ7E"}
+{"version":3,"file":"dev-server.d.ts","sourceRoot":"","sources":["../src/dev-server.ts"],"names":[],"mappings":"AAyDA,MAAM,WAAW,gBAAgB;IAC/B,IAAI,EAAE,MAAM,CAAC;IACb,IAAI,CAAC,EAAE,MAAM,CAAC;IACd,MAAM,CAAC,EAAE,MAAM,CAAC;IAChB,eAAe,CAAC,EAAE,OAAO,CAAC;CAC3B;AAED,wBAAsB,cAAc,CAAC,OAAO,EAAE,gBAAgB,GAAG,OAAO,CAAC,IAAI,CAAC,CA2c7E"}