@dogsbay/format-dogsbay-md 0.2.0-beta.0

package/dist/inline.js

@@ -0,0 +1,122 @@
+import { escapeAttrValue } from "./attributes.js";
+/**
+ * Serialize a flat array of inline nodes to markdown.
+ */
+export function inlineToDogsbayMd(nodes) {
+    if (!nodes || nodes.length === 0)
+        return "";
+    return nodes.map(renderInline).join("");
+}
+function renderInline(node) {
+    switch (node.type) {
+        case "text":
+            return renderText(node);
+        case "link":
+            return renderLink(node);
+        case "image":
+            return renderImage(node);
+        case "code":
+            return renderInlineCode(node.text);
+        case "highlight":
+            return `==${inlineToDogsbayMd(node.children)}==`;
+        case "kbd":
+            return `:kbd[${node.keys.join("+")}]`;
+        case "icon":
+            return renderIcon(node);
+        case "math":
+            return `$${node.latex}$`;
+        case "footnote-ref":
+            return `[^${node.label}]`;
+        case "html-inline":
+            return node.html;
+        case "break":
+            return "  \n";
+        default:
+            // exhaustiveness check
+            return "";
+    }
+}
+function renderText(node) {
+    let text = escapeInlineText(node.text);
+    // Apply annotations from outside in: strikethrough, italic, bold
+    // Order produces canonical output: ~~*_**text**_*~~
+    if (node.bold)
+        text = `**${text}**`;
+    if (node.italic)
+        text = `*${text}*`;
+    if (node.strikethrough)
+        text = `~~${text}~~`;
+    return text;
+}
+function renderLink(node) {
+    const label = inlineToDogsbayMd(node.children);
+    const href = escapeLinkDest(node.href);
+    const title = node.title ? ` ${escapeAttrValue(node.title)}` : "";
+    return `[${label}](${href}${title})`;
+}
+function renderImage(node) {
+    const alt = node.alt ? escapeInlineText(node.alt) : "";
+    const src = escapeLinkDest(node.src);
+    const title = node.title ? ` ${escapeAttrValue(node.title)}` : "";
+    return `![${alt}](${src}${title})`;
+}
+function renderInlineCode(text) {
+    // Choose a backtick run that doesn't appear in the content
+    let maxRun = 0;
+    for (const match of text.matchAll(/`+/g)) {
+        if (match[0].length > maxRun)
+            maxRun = match[0].length;
+    }
+    const fence = "`".repeat(maxRun + 1);
+    // If content starts or ends with backtick, pad with space
+    const needsPad = text.startsWith("`") || text.endsWith("`");
+    const body = needsPad ? ` ${text} ` : text;
+    return `${fence}${body}${fence}`;
+}
+function renderIcon(node) {
+    // Simple form: :name[iconid]. Library/variant encoded via attrs if present.
+    const parts = [node.name];
+    if (node.library)
+        parts.unshift(node.library);
+    const fullName = parts.join(":");
+    // If the icon has additional metadata, switch to directive with attributes
+    const extraAttrs = [];
+    if (node.size)
+        extraAttrs.push(`size=${escapeAttrValue(node.size)}`);
+    if (node.variant)
+        extraAttrs.push(`variant=${escapeAttrValue(node.variant)}`);
+    if (node.attrs) {
+        for (const [k, v] of Object.entries(node.attrs)) {
+            extraAttrs.push(`${k}=${escapeAttrValue(v)}`);
+        }
+    }
+    if (extraAttrs.length === 0) {
+        return `:icon[${fullName}]`;
+    }
+    return `:icon[${fullName}]{${extraAttrs.join(" ")}}`;
+}
+/**
+ * Escape markdown-active characters in inline text.
+ * Balance: aggressive enough to round-trip, not so aggressive that readable text
+ * becomes a thicket of backslashes.
+ */
+function escapeInlineText(text) {
+    // CommonMark rule: `_` is emphasis only at word boundaries (not intraword).
+    // So `snake_case` needs no escaping. Only escape `_` at word boundaries.
+    return text
+        .replace(/\\/g, "\\\\")
+        .replace(/([*`\[\]])/g, "\\$1")
+        .replace(/(^|\W)_/g, "$1\\_")
+        .replace(/_(\W|$)/g, "\\_$1");
+}
+/**
+ * Escape a link/image destination. Angle-bracketed form used when URL contains
+ * parens or whitespace.
+ */
+function escapeLinkDest(dest) {
+    if (/[\s()]/.test(dest)) {
+        return `<${dest}>`;
+    }
+    return dest;
+}
+//# sourceMappingURL=inline.js.map

package/dist/inline.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"inline.js","sourceRoot":"","sources":["../src/inline.ts"],"names":[],"mappings":"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"}

package/dist/nav-file.d.ts

@@ -0,0 +1,38 @@
+import type { NavItem } from "@dogsbay/types";
+/**
+ * Schema for nav file entries. The same shape works across JSON and YAML
+ * after normalization. Each entry has at least one of `file`, `href`,
+ * or `children`. `label` is required.
+ */
+export interface NavFileItem {
+    /** Display label in the sidebar */
+    label: string;
+    /** Internal: relative path to a .md file in the content dir */
+    file?: string;
+    /** External / absolute: passes through to NavItem.href as-is */
+    href?: string;
+    /** Nested items */
+    children?: NavFileItem[];
+}
+export type NavFile = NavFileItem[];
+export interface LoadNavFileOptions {
+    /** Prefix for resolved hrefs. Default: "/docs" */
+    hrefPrefix?: string;
+    /**
+     * Whether to fail or warn on file references that don't exist in the
+     * content dir. Default: "warn".
+     */
+    missingFile?: "warn" | "fail";
+}
+/**
+ * Load + parse a nav file at the given path. Returns a normalized
+ * `NavItem[]` ready for downstream consumers. Throws if the path
+ * doesn't exist, the file is malformed, or required fields are
+ * missing.
+ *
+ * Pass an absolute path or a path relative to the current working
+ * directory. The contentDir is used to verify file references and
+ * to compute slugs.
+ */
+export declare function loadNavFile(path: string, contentDir: string, options?: LoadNavFileOptions): NavItem[];
+//# sourceMappingURL=nav-file.d.ts.map

package/dist/nav-file.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"nav-file.d.ts","sourceRoot":"","sources":["../src/nav-file.ts"],"names":[],"mappings":"AAmBA,OAAO,KAAK,EAAE,OAAO,EAAE,MAAM,gBAAgB,CAAC;AAE9C;;;;GAIG;AACH,MAAM,WAAW,WAAW;IAC1B,mCAAmC;IACnC,KAAK,EAAE,MAAM,CAAC;IACd,+DAA+D;IAC/D,IAAI,CAAC,EAAE,MAAM,CAAC;IACd,gEAAgE;IAChE,IAAI,CAAC,EAAE,MAAM,CAAC;IACd,mBAAmB;IACnB,QAAQ,CAAC,EAAE,WAAW,EAAE,CAAC;CAC1B;AAED,MAAM,MAAM,OAAO,GAAG,WAAW,EAAE,CAAC;AAEpC,MAAM,WAAW,kBAAkB;IACjC,kDAAkD;IAClD,UAAU,CAAC,EAAE,MAAM,CAAC;IACpB;;;OAGG;IACH,WAAW,CAAC,EAAE,MAAM,GAAG,MAAM,CAAC;CAC/B;AAED;;;;;;;;;GASG;AACH,wBAAgB,WAAW,CACzB,IAAI,EAAE,MAAM,EACZ,UAAU,EAAE,MAAM,EAClB,OAAO,GAAE,kBAAuB,GAC/B,OAAO,EAAE,CAyBX"}

package/dist/nav-file.js

@@ -0,0 +1,257 @@
+/**
+ * Explicit nav file loader for Dogsbay MD content directories.
+ *
+ * Supports nav.json (canonical) and nav.yml / nav.yaml (terse,
+ * MkDocs-compatible). The loader is format-agnostic at the call site —
+ * it dispatches by file extension and returns a normalized
+ * `NavItem[]` regardless of source format.
+ *
+ * Resolution order at the call site:
+ *   1. Caller passes an explicit path → use that
+ *   2. Caller asks for heuristic detection → try nav.json, nav.yml,
+ *      nav.yaml in the content root in that order
+ *   3. Caller falls back to `buildNavFromDirectory()` (in nav.ts)
+ *
+ * See `plans/nav-file-support.md` for design context.
+ */
+import { existsSync, readFileSync } from "node:fs";
+import { extname, isAbsolute, resolve } from "node:path";
+import yaml from "js-yaml";
+/**
+ * Load + parse a nav file at the given path. Returns a normalized
+ * `NavItem[]` ready for downstream consumers. Throws if the path
+ * doesn't exist, the file is malformed, or required fields are
+ * missing.
+ *
+ * Pass an absolute path or a path relative to the current working
+ * directory. The contentDir is used to verify file references and
+ * to compute slugs.
+ */
+export function loadNavFile(path, contentDir, options = {}) {
+    const absolutePath = isAbsolute(path) ? path : resolve(path);
+    if (!existsSync(absolutePath)) {
+        throw new Error(`Nav file not found: ${absolutePath}`);
+    }
+    const ext = extname(absolutePath).toLowerCase();
+    const raw = readFileSync(absolutePath, "utf-8");
+    let parsed;
+    if (ext === ".json") {
+        parsed = parseJsonNav(raw, absolutePath);
+    }
+    else if (ext === ".yml" || ext === ".yaml") {
+        parsed = parseYamlNav(raw, absolutePath);
+    }
+    else {
+        throw new Error(`Unsupported nav file extension: ${ext} ` +
+            `(supported: .json, .yml, .yaml). Path: ${absolutePath}`);
+    }
+    const normalized = normalizeNavFile(parsed, absolutePath);
+    const hrefPrefix = options.hrefPrefix ?? "/docs";
+    const missingFileMode = options.missingFile ?? "warn";
+    return convertItems(normalized, contentDir, hrefPrefix, missingFileMode);
+}
+// ── JSON parsing ─────────────────────────────────────────────────
+function parseJsonNav(raw, sourcePath) {
+    try {
+        return JSON.parse(raw);
+    }
+    catch (err) {
+        throw new Error(`Failed to parse nav file as JSON: ${sourcePath}\n  ${err.message}`);
+    }
+}
+// ── YAML parsing (MkDocs-compatible terse syntax) ────────────────
+/**
+ * MkDocs nav YAML uses `Label: target` mappings where target is:
+ *   - A string (leaf):
+ *       - Welcome: welcome.md
+ *   - A list (group):
+ *       - Section:
+ *           - Page A: a.md
+ *           - Page B: b.md
+ *   - A bare string in a group (group's landing page):
+ *       - Section:
+ *           - section/index.md      # bare string → group's `file`
+ *           - Page A: a.md
+ *
+ * This expands the terse YAML form into the canonical `NavFileItem`
+ * shape so the rest of the loader is format-agnostic.
+ */
+function parseYamlNav(raw, sourcePath) {
+    let yamlParsed;
+    try {
+        yamlParsed = yaml.load(raw);
+    }
+    catch (err) {
+        throw new Error(`Failed to parse nav file as YAML: ${sourcePath}\n  ${err.message}`);
+    }
+    if (!Array.isArray(yamlParsed)) {
+        throw new Error(`Nav file must contain a top-level array. Got ${typeof yamlParsed} in ${sourcePath}`);
+    }
+    return yamlParsed.map((entry, i) => expandYamlEntry(entry, sourcePath, `[${i}]`));
+}
+const ABSOLUTE_HREF_RE = /^(?:https?:\/\/|\/|mailto:|tel:|#)/i;
+function expandYamlEntry(entry, sourcePath, context) {
+    // Bare string at a group level → group's landing page.
+    // Caller distinguishes this case by position; here we represent it
+    // as `{ label: "", file: "..." }` and the parent group merges it.
+    if (typeof entry === "string") {
+        return ABSOLUTE_HREF_RE.test(entry)
+            ? { label: "", href: entry }
+            : { label: "", file: entry };
+    }
+    if (typeof entry !== "object" || entry === null || Array.isArray(entry)) {
+        throw new Error(`Nav entry must be a string or single-key map at ${context} in ${sourcePath}. ` +
+            `Got ${typeof entry}.`);
+    }
+    const obj = entry;
+    const keys = Object.keys(obj);
+    if (keys.length !== 1) {
+        throw new Error(`Nav entry must have exactly one key at ${context} in ${sourcePath}. ` +
+            `Got ${keys.length}: ${JSON.stringify(keys)}`);
+    }
+    const label = keys[0];
+    const target = obj[label];
+    // Leaf: value is a string. External URL → href; otherwise file.
+    if (typeof target === "string") {
+        return ABSOLUTE_HREF_RE.test(target)
+            ? { label, href: target }
+            : { label, file: target };
+    }
+    // Group: value is a list. Walk children, then merge any leading
+    // bare-string entry as the group's `file`/`href`.
+    if (Array.isArray(target)) {
+        const expandedChildren = target.map((child, i) => expandYamlEntry(child, sourcePath, `${context}.${label}[${i}]`));
+        // Detect leading "bare string" child (label-empty entry that has
+        // file/href but no label). MkDocs convention: that's the group's
+        // own landing page. Merge it onto the group node.
+        const result = { label };
+        let children = expandedChildren;
+        if (expandedChildren.length > 0 &&
+            typeof expandedChildren[0] === "object" &&
+            expandedChildren[0] !== null) {
+            const first = expandedChildren[0];
+            if (first.label === "" && (first.file !== undefined || first.href !== undefined)) {
+                if (first.file !== undefined)
+                    result.file = first.file;
+                if (first.href !== undefined)
+                    result.href = first.href;
+                children = expandedChildren.slice(1);
+            }
+        }
+        result.children = children;
+        return result;
+    }
+    throw new Error(`Nav entry value must be a string or list at ${context}.${label} in ${sourcePath}. ` +
+        `Got ${typeof target}.`);
+}
+// ── Schema normalization ─────────────────────────────────────────
+/**
+ * Normalize a parsed nav file into `NavFileItem[]`. Validates required
+ * fields and types; throws with a clear path on first violation.
+ *
+ * Both JSON and YAML produce the same shape after parsing
+ * (after YAML's terser syntax is expanded in Step 2), so this
+ * normalizer is shared.
+ */
+function normalizeNavFile(parsed, sourcePath) {
+    if (!Array.isArray(parsed)) {
+        throw new Error(`Nav file must contain a top-level array. Got ${typeof parsed} in ${sourcePath}`);
+    }
+    return parsed.map((item, index) => normalizeItem(item, sourcePath, `[${index}]`));
+}
+function normalizeItem(item, sourcePath, context) {
+    if (typeof item !== "object" || item === null || Array.isArray(item)) {
+        throw new Error(`Nav item must be an object. Got ${typeof item} at ${context} in ${sourcePath}`);
+    }
+    const obj = item;
+    if (typeof obj.label !== "string" || !obj.label) {
+        throw new Error(`Nav item is missing required "label" string at ${context} in ${sourcePath}`);
+    }
+    const result = { label: obj.label };
+    if (obj.file !== undefined) {
+        if (typeof obj.file !== "string") {
+            throw new Error(`Nav item "file" must be a string at ${context} in ${sourcePath}`);
+        }
+        result.file = obj.file;
+    }
+    if (obj.href !== undefined) {
+        if (typeof obj.href !== "string") {
+            throw new Error(`Nav item "href" must be a string at ${context} in ${sourcePath}`);
+        }
+        result.href = obj.href;
+    }
+    if (obj.children !== undefined) {
+        if (!Array.isArray(obj.children)) {
+            throw new Error(`Nav item "children" must be an array at ${context} in ${sourcePath}`);
+        }
+        result.children = obj.children.map((child, i) => normalizeItem(child, sourcePath, `${context}.children[${i}]`));
+    }
+    // Each item must have at least one of file / href / children
+    if (result.file === undefined &&
+        result.href === undefined &&
+        result.children === undefined) {
+        throw new Error(`Nav item "${result.label}" must have at least one of "file", "href", ` +
+            `or "children" at ${context} in ${sourcePath}`);
+    }
+    return result;
+}
+// ── NavFileItem → NavItem conversion ─────────────────────────────
+const EXTERNAL_HREF_RE = /^(?:https?:\/\/|\/|mailto:|tel:|#)/i;
+/**
+ * Convert validated NavFileItem nodes into NavItem (the universal nav
+ * type). Resolves `file` references to slugs, passes external `href`
+ * values through, and warns/fails on missing files per options.
+ */
+function convertItems(items, contentDir, hrefPrefix, missingFileMode) {
+    return items.map((item) => convertItem(item, contentDir, hrefPrefix, missingFileMode));
+}
+function convertItem(item, contentDir, hrefPrefix, missingFileMode) {
+    const result = { label: item.label };
+    if (item.href) {
+        // External / absolute URL — pass through unchanged
+        result.href = item.href;
+    }
+    else if (item.file) {
+        if (EXTERNAL_HREF_RE.test(item.file)) {
+            // Defensive: a writer might put an absolute URL in `file`. Treat
+            // as external rather than trying to resolve it as a slug.
+            result.href = item.file;
+        }
+        else {
+            const fileAbs = resolve(contentDir, item.file);
+            if (!existsSync(fileAbs)) {
+                const message = `Nav file references missing file: ${item.file} ` +
+                    `(resolved: ${fileAbs})`;
+                if (missingFileMode === "fail") {
+                    throw new Error(message);
+                }
+                // Warn and produce a label-only nav entry (no href)
+                console.warn(`[dogsbay] ${message}`);
+            }
+            else {
+                result.href = fileToHref(item.file, hrefPrefix);
+            }
+        }
+    }
+    if (item.children) {
+        result.children = convertItems(item.children, contentDir, hrefPrefix, missingFileMode);
+    }
+    return result;
+}
+/**
+ * Convert a relative .md file path into a public-facing URL, e.g.
+ * "docs-as-code/welcome.md" → "/docs/docs-as-code/welcome".
+ */
+function fileToHref(file, hrefPrefix) {
+    // Normalize path separators to forward slashes (Windows compat)
+    const normalized = file.replace(/\\/g, "/").replace(/^\.\//, "");
+    // Strip .md extension. index.md becomes the directory itself.
+    let slug = normalized.replace(/\.md$/i, "");
+    if (slug.endsWith("/index"))
+        slug = slug.slice(0, -"/index".length);
+    if (slug === "index")
+        slug = "";
+    const prefix = hrefPrefix.endsWith("/") ? hrefPrefix.slice(0, -1) : hrefPrefix;
+    return slug ? `${prefix}/${slug}` : prefix;
+}
+//# sourceMappingURL=nav-file.js.map

package/dist/nav-file.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"nav-file.js","sourceRoot":"","sources":["../src/nav-file.ts"],"names":[],"mappings":"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"}

package/dist/nav.d.ts

@@ -0,0 +1,34 @@
+import type { NavItem } from "@dogsbay/types";
+export interface BuildNavOptions {
+    /** Prefix for hrefs; defaults to "/docs" */
+    hrefPrefix?: string;
+    /**
+     * Explicit nav file path. When set, this file is loaded and the
+     * directory-scan fallback is skipped. Errors thrown from loading
+     * propagate (caller asked for that specific file).
+     */
+    navFilePath?: string;
+    /**
+     * When true, skip heuristic auto-detection and go directly to
+     * directory scan. Useful for existing pipelines that haven't
+     * adopted nav files but might have a file in the content dir
+     * left over from another tool.
+     */
+    skipHeuristic?: boolean;
+}
+/**
+ * Build a hierarchical nav for a Dogsbay MD content directory.
+ *
+ * Resolution order:
+ *   1. options.navFilePath set → load that file; throw on error
+ *   2. options.skipHeuristic NOT set → try nav.{json,yml,yaml} in
+ *      content root; on success use it; on parse error warn + fall
+ *      back to directory scan
+ *   3. Otherwise → walk the directory, read frontmatter
+ *      (sidebar.order / sidebar.label / title), build hierarchy
+ *
+ * Directory index pages (index.md) become the folder's landing page.
+ * Sorting falls back to filename alphabetical when order is not set.
+ */
+export declare function buildNavFromDirectory(contentDir: string, options?: BuildNavOptions): NavItem[];
+//# sourceMappingURL=nav.d.ts.map

package/dist/nav.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"nav.d.ts","sourceRoot":"","sources":["../src/nav.ts"],"names":[],"mappings":"AAeA,OAAO,KAAK,EAAE,OAAO,EAAE,MAAM,gBAAgB,CAAC;AAoB9C,MAAM,WAAW,eAAe;IAC9B,4CAA4C;IAC5C,UAAU,CAAC,EAAE,MAAM,CAAC;IACpB;;;;OAIG;IACH,WAAW,CAAC,EAAE,MAAM,CAAC;IACrB;;;;;OAKG;IACH,aAAa,CAAC,EAAE,OAAO,CAAC;CACzB;AAED;;;;;;;;;;;;;GAaG;AACH,wBAAgB,qBAAqB,CACnC,UAAU,EAAE,MAAM,EAClB,OAAO,GAAE,eAAoB,GAC5B,OAAO,EAAE,CA+BX"}

package/dist/nav.js

@@ -0,0 +1,169 @@
+/**
+ * Nav builder for Dogsbay MD sources.
+ *
+ * Three modes, tried in order:
+ *   1. Explicit `--nav <path>` — caller passes navFilePath (wins)
+ *   2. Heuristic auto-detect — try nav.json / nav.yml / nav.yaml in
+ *      content root; first hit wins
+ *   3. Directory scan + frontmatter — fallback when no nav file is
+ *      present or heuristic detection fails to parse
+ *
+ * Produces NavItem[].
+ */
+import { existsSync, readdirSync, readFileSync, statSync } from "node:fs";
+import { join, relative, basename } from "node:path";
+import matter from "gray-matter";
+import { loadNavFile } from "./nav-file.js";
+/**
+ * File names tried, in priority order, when auto-detecting a nav
+ * file in a content directory. The first existing file wins.
+ */
+const HEURISTIC_NAV_FILES = ["nav.json", "nav.yml", "nav.yaml"];
+/**
+ * Build a hierarchical nav for a Dogsbay MD content directory.
+ *
+ * Resolution order:
+ *   1. options.navFilePath set → load that file; throw on error
+ *   2. options.skipHeuristic NOT set → try nav.{json,yml,yaml} in
+ *      content root; on success use it; on parse error warn + fall
+ *      back to directory scan
+ *   3. Otherwise → walk the directory, read frontmatter
+ *      (sidebar.order / sidebar.label / title), build hierarchy
+ *
+ * Directory index pages (index.md) become the folder's landing page.
+ * Sorting falls back to filename alphabetical when order is not set.
+ */
+export function buildNavFromDirectory(contentDir, options = {}) {
+    const hrefPrefix = options.hrefPrefix ?? "/docs";
+    // Mode 1: explicit path (wins over heuristic + dir scan)
+    if (options.navFilePath) {
+        return loadNavFile(options.navFilePath, contentDir, { hrefPrefix });
+    }
+    // Mode 2: heuristic auto-detection
+    if (!options.skipHeuristic) {
+        for (const fileName of HEURISTIC_NAV_FILES) {
+            const candidate = join(contentDir, fileName);
+            if (!existsSync(candidate))
+                continue;
+            try {
+                return loadNavFile(candidate, contentDir, { hrefPrefix });
+            }
+            catch (err) {
+                // Heuristic-detected file is malformed → warn + fall through
+                // to dir scan. The writer didn't ask for this specific file,
+                // so a hard failure would be unfriendly.
+                console.warn(`[dogsbay] auto-detected nav file ${candidate} is malformed; ` +
+                    `falling back to directory scan. Error: ${err.message}`);
+                break;
+            }
+        }
+    }
+    // Mode 3: directory scan + frontmatter
+    const pages = collectPages(contentDir, contentDir);
+    return buildHierarchy(pages, hrefPrefix);
+}
+function collectPages(dir, rootDir) {
+    const pages = [];
+    for (const entry of readdirSync(dir, { withFileTypes: true })) {
+        const fullPath = join(dir, entry.name);
+        if (entry.isDirectory()) {
+            pages.push(...collectPages(fullPath, rootDir));
+        }
+        else if (entry.name.endsWith(".md")) {
+            const content = readFileSync(fullPath, "utf-8");
+            let frontmatter = {};
+            try {
+                frontmatter = (matter(content).data ?? {});
+            }
+            catch {
+                // Malformed frontmatter — treat as no frontmatter
+            }
+            const sidebar = frontmatter.sidebar ?? {};
+            if (sidebar.hidden === true)
+                continue;
+            const rel = relative(rootDir, fullPath).replace(/\\/g, "/");
+            const slug = rel.replace(/\.md$/, "");
+            const nameWithoutExt = basename(entry.name, ".md");
+            const isIndex = nameWithoutExt === "index";
+            pages.push({
+                title: frontmatter.title ?? prettifyName(nameWithoutExt),
+                sidebarLabel: sidebar.label,
+                sidebarOrder: sidebar.order,
+                sidebarHidden: false,
+                slug,
+                filePath: fullPath,
+                dir: relative(rootDir, dir).replace(/\\/g, "/"),
+                isIndex,
+            });
+        }
+    }
+    return pages;
+}
+/**
+ * Build a nav tree from a flat page list, grouped by directory.
+ * Uses ordering hints: (sidebarOrder ?? Infinity), then title.
+ */
+function buildHierarchy(pages, hrefPrefix) {
+    // Group by top-level directory; index files at the top level become root-level nav items
+    const rootPages = [];
+    const groups = new Map();
+    for (const page of pages) {
+        const firstSegment = page.slug.includes("/") ? page.slug.split("/")[0] : "";
+        if (firstSegment === "") {
+            rootPages.push(page);
+        }
+        else {
+            if (!groups.has(firstSegment))
+                groups.set(firstSegment, []);
+            groups.get(firstSegment).push(page);
+        }
+    }
+    // Build flat items from root pages
+    const items = [];
+    for (const page of rootPages.sort(comparePages)) {
+        if (page.slug === "index")
+            continue; // handled as site root
+        items.push({
+            label: page.sidebarLabel ?? page.title,
+            href: `${hrefPrefix}/${page.slug}`,
+        });
+    }
+    // Build group items for each subdirectory
+    const groupItems = [];
+    for (const [dir, groupPages] of groups.entries()) {
+        const groupIndex = groupPages.find((p) => p.isIndex);
+        const groupChildren = groupPages
+            .filter((p) => !p.isIndex)
+            .sort(comparePages)
+            .map((p) => ({
+            label: p.sidebarLabel ?? p.title,
+            href: `${hrefPrefix}/${p.slug}`,
+        }));
+        const groupLabel = groupIndex?.sidebarLabel
+            ?? groupIndex?.title
+            ?? prettifyName(dir);
+        groupItems.push({
+            label: groupLabel,
+            href: groupIndex ? `${hrefPrefix}/${groupIndex.slug}` : undefined,
+            children: groupChildren,
+        });
+    }
+    // Sort groups by the first-page order heuristic
+    groupItems.sort((a, b) => a.label.localeCompare(b.label));
+    return [...items, ...groupItems];
+}
+function comparePages(a, b) {
+    const oa = a.sidebarOrder ?? Number.POSITIVE_INFINITY;
+    const ob = b.sidebarOrder ?? Number.POSITIVE_INFINITY;
+    if (oa !== ob)
+        return oa - ob;
+    return a.title.localeCompare(b.title);
+}
+function prettifyName(slug) {
+    return slug
+        .split("-")
+        .map((w) => w.charAt(0).toUpperCase() + w.slice(1))
+        .join(" ");
+}
+void statSync; // reserved for future use (e.g. mtime-based caching)
+//# sourceMappingURL=nav.js.map

package/dist/nav.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"nav.js","sourceRoot":"","sources":["../src/nav.ts"],"names":[],"mappings":"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"}