@dogsbay/format-obsidian 0.2.0-beta.1 → 0.2.0-beta.101

package/dist/project.js

@@ -1,4 +1,18 @@
 import { treeToObsidian } from "./serialize.js";
+/**
+ * Path of a section's folder note.
+ *
+ * Named `_<folder>.md`, not `_index.md`: Obsidian labels graph nodes and tabs
+ * by FILENAME, so a vault of 309 sections showed 309 identical `_index` nodes.
+ * The leading underscore keeps the note sorted to the top of its folder and
+ * distinguishes it from a content page that shares the folder's name — 20
+ * sections in the OpenShift corpus contain `<folder>/<folder>.md`, so the bare
+ * folder name would collide. No page in that corpus starts with `_`.
+ */
+export function sectionNotePath(folderPath) {
+    const leaf = folderPath.slice(folderPath.lastIndexOf("/") + 1);
+    return `${folderPath}/_${leaf}.md`;
+}
 /**
  * Export pages + nav to an Obsidian vault file map.
  */
@@ -16,23 +30,67 @@ export function exportObsidianVault(pages, nav, options = {}) {
     const pathPrefix = section || "";
     assignPaths(nav, pathPrefix, assignments, pageBySlug);
     // Generate pages
+    //
+    // A page the nav does not place used to be flattened to its BASENAME at the
+    // vault root, so any two pages sharing one — `agent/customize` and
+    // `assistant/customize`, or the es/fr/zh translations of the same page —
+    // wrote to the same path and the later one silently overwrote the earlier.
+    // Measured on a real Mintlify export: 988 pages produced 881 files, i.e. 107
+    // pages vanished with no error. An unplaced page now keeps its SLUG PATH,
+    // which mirrors the source tree and cannot collide unless the source did.
+    const taken = new Map();
+    const actualVaultPath = new Map();
+    const collisions = [];
     for (const page of pages) {
+        // A fragment is an include TARGET, not a note. `convert` realizes includes
+        // for this exporter, so the fragment's content is already spliced into
+        // every note that used it — emitting it again produced a duplicate,
+        // usually-untitled note sitting beside the real ones. (format-dogsbay-md
+        // does emit them, correctly: there the `{% include %}` is preserved, so the
+        // target file has to exist.)
+        if (page.fragment || page.frontmatter?._fragment === true)
+            continue;
         const assignment = assignments.get(page.slug);
         const fallbackFolder = section || "";
-        const filePath = assignment
-            ? `${assignment.folderPath}/${fileNameFromSlug(page.slug)}.md`
-            : fallbackFolder
-                ? `${fallbackFolder}/${fileNameFromSlug(page.slug)}.md`
-                : `${fileNameFromSlug(page.slug)}.md`;
+        const unplaced = slugToVaultRelPath(page.slug);
+        // `folderPath` is "" for a root-level nav entry, so joining unconditionally
+        // produced a LEADING SLASH (`/index.md`). The write path tolerated it; the
+        // nav/link map re-derived its own path and silently did not. Now that both
+        // read one value, the join has to be correct.
+        let filePath = assignment
+            ? joinVaultPath(assignment.folderPath, `${fileNameFromSlug(page.slug)}.md`)
+            : joinVaultPath(fallbackFolder, `${unplaced}.md`);
+        // Even with slug paths, a nav placement can still collide (two nav entries
+        // pointing at the same folder + basename). Never overwrite silently:
+        // disambiguate with the slug and record it for the caller to report.
+        // Keyed CASE-INSENSITIVELY. macOS and Windows filesystems are, so
+        // `API/Overview` and `api/overview` are two keys in a case-sensitive Map,
+        // no collision is recorded, both are written — and the second silently
+        // overwrites the first. The vault is a page short, `_nav.yml` points both
+        // entries at the survivor, and the warning that exists to surface exactly
+        // this never fires.
+        const key = filePath.toLowerCase();
+        if (taken.has(key)) {
+            const alt = `${filePath.slice(0, -3)}--${page.slug.replace(/\//g, "-")}.md`;
+            collisions.push({ path: filePath, kept: taken.get(key), renamed: page.slug });
+            filePath = alt;
+        }
+        taken.set(filePath.toLowerCase(), page.slug);
+        // The single source of truth for "where did this page end up". The nav and
+        // link-rewrite maps below MUST read this rather than re-deriving the path:
+        // when they re-derived it they used the basename, so an unplaced nested
+        // page's links pointed at a file that no longer exists, and a collision
+        // rename left the renamed file unreachable from nav.
+        actualVaultPath.set(page.slug, filePath.replace(/\.md$/, ""));
         let content = treeToObsidian(page.tree);
         // Prepend frontmatter — always include title + alias, add sidebar_position if from nav
         if (assignment) {
-            const fm = buildFrontmatter(page.title, assignment.position);
+            const fm = buildFrontmatter(page.title, assignment.position, assignment.categories);
             if (content.startsWith("---\n")) {
                 const endIdx = content.indexOf("\n---\n", 4);
                 if (endIdx !== -1) {
                     const existingFm = content.substring(4, endIdx);
-                    content = `---\n${existingFm}\naliases:\n  - ${yamlStr(page.title)}\nsidebar_position: ${assignment.position}\n---\n${content.substring(endIdx + 5)}`;
+                    content = `---\n${existingFm}\naliases:\n  - ${yamlStr(page.title)}\nsidebar_position: ${assignment.position}${categoryBlock(assignment.categories)}\n---\n${content.substring(endIdx + 5)}`;
                 }
             }
             else {
@@ -48,8 +106,10 @@ export function exportObsidianVault(pages, nav, options = {}) {
         }
         files.set(filePath, content);
     }
-    // Generate _index.md for nav sections (folders)
-    generateSectionIndexes(nav, pathPrefix, files);
+    // Generate a folder note per nav section
+    if (options.sectionIndexes !== false) {
+        generateSectionIndexes(nav, pathPrefix, files, pageBySlug);
+    }
     // Build slug → vault path lookup (without .md extension) for nav yaml and link rewriting
     const slugToVaultPath = new Map();
     // Also build link rewrite map: keys are paths as they appear in content links
@@ -57,19 +117,10 @@ export function exportObsidianVault(pages, nav, options = {}) {
     const linkRewrites = new Map();
     for (const page of pages) {
         const assignment = assignments.get(page.slug);
-        const fallbackFolder = section || "";
-        const fileName = fileNameFromSlug(page.slug);
-        let vaultPath;
-        if (assignment) {
-            vaultPath = assignment.folderPath
-                ? `${assignment.folderPath}/${fileName}`
-                : fileName;
-        }
-        else {
-            vaultPath = fallbackFolder
-                ? `${fallbackFolder}/${fileName}`
-                : fileName;
-        }
+        // Where the page ACTUALLY went, recorded when it was written.
+        const vaultPath = actualVaultPath.get(page.slug);
+        if (!vaultPath)
+            continue;
         slugToVaultPath.set(page.slug, vaultPath);
         // Links in content use section-prefixed paths (e.g. "ddos-protection/managed-rulesets")
         // The vault file path may differ (e.g. "ddos-protection/managed-rulesets/managed-rulesets")
@@ -77,6 +128,18 @@ export function exportObsidianVault(pages, nav, options = {}) {
         if (linkPath !== vaultPath) {
             linkRewrites.set(linkPath, vaultPath);
         }
+        // The importer strips `/index` from a directory-landing slug
+        // (`rest_api/objects/index.md` → slug `rest_api/objects`), but
+        // engine-emitted content links spell the FULL source path
+        // (`rest_api/objects/index#anchor`). Register the index spelling too —
+        // without it every schema cross-reference on every API page dangled
+        // (issue #041: 2,320 stale links in 267 files). NOT unconditional:
+        // format-vitepress keeps `/index` in slugs, so `foo` and `foo/index`
+        // can be DISTINCT pages — the alias must never capture links meant
+        // for the real `/index` page.
+        if (!pageBySlug.has(`${page.slug}/index`)) {
+            linkRewrites.set(`${linkPath}/index`, vaultPath);
+        }
     }
     // Rewrite internal links: source paths → vault file paths
     if (linkRewrites.size > 0) {
@@ -94,11 +157,277 @@ export function exportObsidianVault(pages, nav, options = {}) {
             }
         }
     }
+    // Minimal fence tracker for the two link passes below (format-obsidian
+    // may not depend on format-dogsbay-md at runtime — its tracker lives
+    // there). Open on a ```/~~~ run, close only on a run of the SAME char
+    // at >= the opener's length with nothing after it (a shorter run inside
+    // a longer fence is content).
+    const makeFenceTracker = () => {
+        let open = null;
+        return (line) => {
+            const m = line.match(/^\s*(`{3,}|~{3,})(.*)$/);
+            if (m) {
+                const [, run, rest] = m;
+                if (!open) {
+                    open = { char: run[0], len: run.length };
+                    return "fence";
+                }
+                if (run[0] === open.char && run.length >= open.len && rest.trim() === "") {
+                    open = null;
+                    return "fence";
+                }
+                return "code";
+            }
+            return open ? "code" : "prose";
+        };
+    };
+    // Rescue links that spell the ORIGINAL repo path (#051). An xref can
+    // name a DIFFERENT assembly of the same module than the one nav placed
+    // (`edge_computing/…/update-completing-the-control-plane-only-update`
+    // when the page lives under postinstallation-configuration/…) — the
+    // rewrite map above only knows nav-placed slugs. When the dangling
+    // path's BASENAME names exactly one vault page, that page is the
+    // target; ambiguous basenames stay dangling rather than guessing.
+    {
+        const byBasename = new Map();
+        for (const f of files.keys()) {
+            if (!f.endsWith(".md") || f === sectionNotePath(f.slice(0, f.lastIndexOf("/"))))
+                continue;
+            const base = f.slice(f.lastIndexOf("/") + 1, -3);
+            const list = byBasename.get(base) ?? [];
+            list.push(f.slice(0, -3));
+            byBasename.set(base, list);
+        }
+        let rescued = 0;
+        // Anchored to LINK POSITION (`](…)`) — without the `](` prefix any
+        // parenthesized slash-token in prose was a candidate: the OpenShift
+        // corpus carries 1,533 shapes like `(POST/PUT/PATCH)`, `(read/write)`
+        // and `(CI/CD)` that pass every other guard, and one vault page named
+        // `write` or `patch` would have corrupted prose at scale (review,
+        // HIGH). Fence-masked for the same reason — code samples are full of
+        // `call(a/b)` shapes.
+        const linkRx = /\]\(([^()\s#]+)(#[^)\s]*)?\)/g;
+        for (const [filePath, content] of files) {
+            if (!filePath.endsWith(".md"))
+                continue;
+            const step = makeFenceTracker();
+            const updated = content
+                .split("\n")
+                .map((line) => {
+                if (step(line) !== "prose")
+                    return line;
+                return line.replace(linkRx, (whole, dest, frag = "") => {
+                    // Only vault-internal, multi-segment, non-resolving paths.
+                    if (!dest.includes("/") || /^[a-z][a-z0-9+.-]*:/i.test(dest))
+                        return whole;
+                    if (dest.startsWith("_assets/") || /\.[a-z0-9]{2,4}$/i.test(dest))
+                        return whole;
+                    if (files.has(`${dest}.md`) || files.has(sectionNotePath(dest)))
+                        return whole;
+                    const base = dest.slice(dest.lastIndexOf("/") + 1);
+                    const candidates = byBasename.get(base);
+                    if (!candidates || candidates.length !== 1)
+                        return whole;
+                    rescued += 1;
+                    return `](${candidates[0]}${frag})`;
+                });
+            })
+                .join("\n");
+            if (updated !== content)
+                files.set(filePath, updated);
+        }
+        if (rescued > 0) {
+            console.warn(`obsidian export: rescued ${rescued} link(s) spelling original repo paths (unique-basename match)`);
+        }
+    }
+    // Resolve `#^block` fragments against the TARGET file's actual block
+    // ids (#049). Cross-page xrefs name the SOURCE id, but the vault stamps
+    // anchors with the AsciiDoc `id_{context}` expansion — three mismatch
+    // shapes, all mechanical:
+    //   1. link bare, anchor suffixed  → unique prefix match rewrites
+    //   2. link over-suffixed, anchor bare → unique longest-prefix strip
+    //   3. page-top id the vault never stamped → land on the H1's block id
+    //      (the source intent was "this page"), or drop the fragment when
+    //      the H1 carries none.
+    // The file half of these links already resolves — only the scroll
+    // position was lost. Obsidian resolves fragments literally, so a
+    // fragment the target cannot resolve is worthless to the reader.
+    {
+        const anchorIndex = new Map();
+        const indexFor = (file) => {
+            let entry = anchorIndex.get(file);
+            if (!entry) {
+                const content = files.get(file) ?? "";
+                const ids = new Set();
+                let h1 = null;
+                // Fence-aware: Obsidian does not create block ids inside code
+                // fences, so a code line ending ` ^word` (terminal transcripts,
+                // regex samples) must not become a phantom anchor that steals a
+                // prefix match from the real one (review).
+                const step = makeFenceTracker();
+                for (const line of content.split("\n")) {
+                    if (step(line) !== "prose")
+                        continue;
+                    const m = line.match(/\s\^([A-Za-z0-9-]+)\s*$/);
+                    if (!m)
+                        continue;
+                    ids.add(m[1]);
+                    if (h1 === null && /^#\s/.test(line))
+                        h1 = m[1];
+                }
+                entry = { ids, h1 };
+                anchorIndex.set(file, entry);
+            }
+            return entry;
+        };
+        let anchorRewrites = 0;
+        let anchorDrops = 0;
+        const blockLinkRx = /\(([^()\s#]*)#\^([A-Za-z0-9-]+)\)/g;
+        for (const [filePath, content] of files) {
+            if (!filePath.endsWith(".md"))
+                continue;
+            const updated = content.replace(blockLinkRx, (whole, dest, frag) => {
+                // An empty dest is a SAME-PAGE link — resolve against this file
+                // (cnf-talm's troubleshooting list carried 5 in-page fragments
+                // no anchor matched).
+                const targetFile = dest === ""
+                    ? filePath
+                    : files.has(`${dest}.md`)
+                        ? `${dest}.md`
+                        : files.has(sectionNotePath(dest))
+                            ? sectionNotePath(dest)
+                            : null;
+                // Unresolvable FILE half is a different defect (#051) — leave it
+                // visible rather than masking it here.
+                if (!targetFile)
+                    return whole;
+                const { ids, h1 } = indexFor(targetFile);
+                if (ids.has(frag))
+                    return whole;
+                // 1. Bare source id vs suffixed anchor: unambiguous when the
+                // bare id prefixes exactly one anchor. TWO OR MORE candidate
+                // section anchors are positive evidence the link targeted a
+                // SECTION — declining beats the H1 fallback, which would
+                // destroy that evidence and make the link look "valid" to any
+                // later checker (review; same doctrine as #051's
+                // ambiguous-stays-dangling).
+                const prefixed = [...ids].filter((a) => a.startsWith(`${frag}-`));
+                if (prefixed.length === 1) {
+                    anchorRewrites += 1;
+                    return `(${dest}#^${prefixed[0]})`;
+                }
+                if (prefixed.length > 1)
+                    return whole;
+                // 2. Over-suffixed link vs bare anchor: longest anchor the
+                // fragment extends, unique at that length; a tie declines for
+                // the same reason.
+                const stripped = [...ids]
+                    .filter((a) => frag.startsWith(`${a}-`))
+                    .sort((a, b) => b.length - a.length);
+                if (stripped.length > 0) {
+                    if (stripped.filter((a) => a.length === stripped[0].length).length > 1) {
+                        return whole;
+                    }
+                    anchorRewrites += 1;
+                    return `(${dest}#^${stripped[0]})`;
+                }
+                // A target with NO block ids gives no evidence about its anchor
+                // scheme — leave the link alone rather than guessing (unit
+                // fixtures and hand-authored pages hit this).
+                if (ids.size === 0)
+                    return whole;
+                // 3. Page-top reference the vault cannot name: the H1's block id
+                // preserves "scroll to the top of that page"; no H1 id → plain
+                // page link.
+                if (h1) {
+                    anchorRewrites += 1;
+                    return `(${dest}#^${h1})`;
+                }
+                anchorDrops += 1;
+                return `(${dest})`;
+            });
+            if (updated !== content)
+                files.set(filePath, updated);
+        }
+        if (anchorRewrites + anchorDrops > 0) {
+            console.warn(`obsidian export: resolved ${anchorRewrites} cross-page anchor fragment(s) to real block ids` +
+                (anchorDrops > 0 ? `, dropped ${anchorDrops} unresolvable` : ""));
+        }
+    }
+    // Point every card at a file that EXISTS.
+    //
+    // A `dogsbay-card` href is resolved by the plugin with
+    // `vault.getFileByPath()` — an exact match — so unlike a markdown link it
+    // cannot be extensionless, and unlike a markdown link nothing about it
+    // degrades visibly when it is wrong: the card renders perfectly and the
+    // click silently does nothing.
+    //
+    // A card that targets a SECTION is the case the serializer cannot get right
+    // on its own: `ai-search/get-started` is a folder here, and the note is at
+    // `ai-search/get-started/_index.md`. Only this layer knows that, because
+    // only this layer decided it.
+    for (const [filePath, content] of files) {
+        if (!filePath.endsWith(".md"))
+            continue;
+        const updated = content.replace(/^href: (.+)$/gm, (line, raw) => {
+            const href = raw.trim();
+            if (!href || /^[a-z][a-z0-9+.-]*:/i.test(href) || href.startsWith("#"))
+                return line;
+            if (files.has(href))
+                return line;
+            const bare = href.replace(/\.md$/, "");
+            for (const candidate of [`${bare}.md`, sectionNotePath(bare)]) {
+                if (files.has(candidate))
+                    return `href: ${candidate}`;
+            }
+            return line;
+        });
+        if (updated !== content)
+            files.set(filePath, updated);
+    }
+    // A collision is content that would have been LOST — say so rather than
+    // leaving the operator to notice the file count is short.
+    if (collisions.length > 0) {
+        console.warn(`  warning: ${collisions.length} page(s) collided on a vault path and were ` +
+            `written under a disambiguated name (previously they overwrote each other ` +
+            `silently). First: "${collisions[0].renamed}" vs "${collisions[0].kept}" ` +
+            `at ${collisions[0].path}.`);
+    }
+    // Fill each folder note with a listing of its children. Deferred to here
+    // because it needs `slugToVaultPath`, which is only complete once every page
+    // has been written — and the empty stubs must already exist above, since the
+    // link-rewriting pass keys off the folder note existing.
+    if (options.sectionIndexes !== false && options.sectionIndexLinks !== false) {
+        fillSectionIndexes(nav, pathPrefix, files, slugToVaultPath);
+    }
     // Generate _nav.yml with actual vault paths
     files.set("_nav.yml", navToYaml(nav, 0, slugToVaultPath));
     return { files };
 }
-function assignPaths(items, parentFolder, assignments, pageBySlug) {
+// ── Nav → folder structure ──────────────────────────────
+/**
+ * The category label for a nav section.
+ *
+ * Prefers the nav label — it is the authored wording. Falls back to the title
+ * of the section's own page when a nav entry carries no label, and finally to
+ * the folder slug, so a category is never blank. (Every one of the 2,105 nav
+ * entries in the OpenShift corpus has a label, so the fallbacks are for
+ * corpora whose nav is generated rather than authored.)
+ */
+function sectionCategoryLabel(item, pageBySlug) {
+    if (item.label)
+        return item.label;
+    if (item.href) {
+        const slug = hrefToSlug(item.href);
+        const page = slug ? pageBySlug.get(slug) : undefined;
+        if (page?.title)
+            return page.title;
+        if (slug)
+            return slug.slice(slug.lastIndexOf("/") + 1);
+    }
+    return "Untitled";
+}
+function assignPaths(items, parentFolder, assignments, pageBySlug, ancestors = []) {
     let position = 1;
     for (const item of items) {
         if (item.children && item.children.length > 0) {
@@ -108,39 +437,101 @@ function assignPaths(items, parentFolder, assignments, pageBySlug) {
             const folderName = item.href ? folderNameFromHref(item.href) : slugify(item.label);
             const folderPath = parentFolder ? `${parentFolder}/${folderName}` : folderName;
             // If section has its own page, assign it
+            // A section's label names the section, so a page that IS the section
+            // does not repeat it — its categories are the ancestors above it.
+            const sectionLabel = sectionCategoryLabel(item, pageBySlug);
             if (item.href) {
                 const slug = hrefToSlug(item.href);
                 if (slug && pageBySlug.has(slug)) {
-                    assignments.set(slug, { folderPath, position });
+                    assignments.set(slug, { folderPath, position, categories: ancestors });
                     position++;
                 }
             }
             // Recurse into children
-            assignPaths(item.children, folderPath, assignments, pageBySlug);
+            assignPaths(item.children, folderPath, assignments, pageBySlug, [
+                ...ancestors,
+                sectionLabel,
+            ]);
             position++;
         }
         else if (item.href) {
             // Leaf page
             const slug = hrefToSlug(item.href);
             if (slug && pageBySlug.has(slug)) {
-                assignments.set(slug, { folderPath: parentFolder, position });
+                assignments.set(slug, { folderPath: parentFolder, position, categories: ancestors });
             }
             position++;
         }
     }
 }
-function generateSectionIndexes(items, parentFolder, files) {
+function generateSectionIndexes(items, parentFolder, files, pageBySlug, ancestors = []) {
     for (const item of items) {
         if (item.children && item.children.length > 0) {
             const folderName = item.href ? folderNameFromHref(item.href) : slugify(item.label);
             const folderPath = parentFolder ? `${parentFolder}/${folderName}` : folderName;
-            // Create _index.md for this section
-            files.set(`${folderPath}/_index.md`, `---\ntitle: ${item.label}\n---\n`);
+            const sectionLabel = sectionCategoryLabel(item, pageBySlug);
+            // Create the folder note for this section. Its categories are the
+            // sections ABOVE it — its own label is already the title.
+            files.set(sectionNotePath(folderPath), `---\ntitle: ${yamlStr(sectionLabel)}${categoryBlock(ancestors)}\n---\n`);
             // Recurse
-            generateSectionIndexes(item.children, folderPath, files);
+            generateSectionIndexes(item.children, folderPath, files, pageBySlug, [
+                ...ancestors,
+                sectionLabel,
+            ]);
+        }
+    }
+}
+/**
+ * Second pass over the nav: give each folder note a body listing its children.
+ *
+ * Links are root-relative and extension-less — the same shape `obsidianHref`
+ * produces for body links, so a section index resolves exactly like any other
+ * cross-reference in the vault.
+ */
+function fillSectionIndexes(items, parentFolder, files, slugToVaultPath) {
+    for (const item of items) {
+        if (!item.children || item.children.length === 0)
+            continue;
+        const folderName = item.href ? folderNameFromHref(item.href) : slugify(item.label);
+        const folderPath = parentFolder ? `${parentFolder}/${folderName}` : folderName;
+        const indexPath = sectionNotePath(folderPath);
+        const lines = [];
+        for (const child of item.children) {
+            const target = sectionIndexTarget(child, folderPath, files, slugToVaultPath);
+            lines.push(target ? `- [${child.label}](${target})` : `- ${child.label}`);
+        }
+        const existing = files.get(indexPath);
+        if (existing !== undefined && lines.length > 0) {
+            files.set(indexPath, `${existing}\n${lines.join("\n")}\n`);
         }
+        fillSectionIndexes(item.children, folderPath, files, slugToVaultPath);
     }
 }
+/**
+ * Where a nav child actually landed in the vault, as a root-relative
+ * extension-less path. Returns undefined when the child is an external link,
+ * a bare anchor, or a page that was never written — a label with no link beats
+ * a link that dangles.
+ */
+function sectionIndexTarget(child, folderPath, files, slugToVaultPath) {
+    // A child that is itself a section resolves to that section's own index.
+    if (child.children && child.children.length > 0) {
+        const name = child.href ? folderNameFromHref(child.href) : slugify(child.label);
+        const nested = sectionNotePath(`${folderPath}/${name}`);
+        if (files.has(nested))
+            return nested.slice(0, -3);
+    }
+    if (!child.href)
+        return undefined;
+    if (/^[a-z][a-z0-9+.-]*:\/\//i.test(child.href) || child.href.startsWith("mailto:"))
+        return undefined;
+    if (isAnchorOnly(child.href))
+        return undefined;
+    const vaultPath = slugToVaultPath.get(hrefToSlug(child.href));
+    if (vaultPath && files.has(`${vaultPath}.md`))
+        return vaultPath;
+    return undefined;
+}
 // ── _nav.yml generation ─────────────────────────────────
 function navToYaml(items, indent = 0, slugToVaultPath) {
     const prefix = "  ".repeat(indent);
@@ -165,6 +556,18 @@ function navToYaml(items, indent = 0, slugToVaultPath) {
 }
 /** Resolve an href to the actual vault path, falling back to hrefToPath. */
 function resolveNavPath(href, slugToVaultPath) {
+    // An external link is not a vault path. `hrefToPath` appended `.md` to it,
+    // so a nav entry pointing at https://learn.mintlify.com became
+    // "https://learn.mintlify.com.md" — a dangling path in every generated
+    // _nav.yml that has an external destination.
+    if (/^[a-z][a-z0-9+.-]*:\/\//i.test(href) || href.startsWith("mailto:"))
+        return href;
+    // An in-page anchor is not a vault path either — appending `.md` produced a
+    // `#options.md` nav row pointing at a file that is never written, and if the
+    // row had children it created a folder named `#options/`, which Obsidian
+    // cannot address at all (`#` is reserved in note names).
+    if (isAnchorOnly(href))
+        return href;
     if (slugToVaultPath) {
         const slug = hrefToSlug(href);
         const vaultPath = slugToVaultPath.get(slug);
@@ -174,13 +577,65 @@ function resolveNavPath(href, slugToVaultPath) {
     return hrefToPath(href);
 }
 // ── Frontmatter ─────────────────────────────────────────
-function buildFrontmatter(title, position) {
-    return `---\ntitle: ${yamlStr(title)}\naliases:\n  - ${yamlStr(title)}\nsidebar_position: ${position}\n---`;
+function buildFrontmatter(title, position, categories = []) {
+    return `---\ntitle: ${yamlStr(title)}\naliases:\n  - ${yamlStr(title)}\nsidebar_position: ${position}${categoryBlock(categories)}\n---`;
+}
+/**
+ * `categories` + `tags` lines for a frontmatter block, or "" when there are none.
+ *
+ * Two renderings of the same hierarchy, doing different jobs:
+ *   - `categories` keeps the authored labels, for reading and for Bases
+ *     filters (`categories.contains("Virtualization")`). A LIST, not a
+ *     "/"-joined string, so filtering is set membership rather than the
+ *     substring matching `@dogsbay/chunk`'s facets.ts SC2 rejects.
+ *   - `tags` is the same chain slugified into one nested tag. Obsidian tags
+ *     cannot contain spaces, but nested tags give a collapsible tree in the
+ *     tag pane and make `tag:#virtualization` a valid graph colour-group
+ *     query — which is what lets graph groups be real facets instead of
+ *     text-matching page bodies.
+ */
+function categoryBlock(categories) {
+    if (categories.length === 0)
+        return "";
+    const list = categories.map((c) => `\n  - ${yamlStr(c)}`).join("");
+    const tag = categories.map((c) => slugify(c)).filter(Boolean).join("/");
+    const tagLine = tag ? `\ntags:\n  - ${tag}` : "";
+    return `\ncategories:${list}${tagLine}`;
 }
 // ── Utilities ───────────────────────────────────────────
+/**
+ * Is this href an in-page anchor rather than a reference to a page?
+ *
+ * `#options`, `/#options`, `/docs#options` — every spelling whose PATH part is
+ * empty but which carries a fragment or query. They must not resolve to a
+ * slug: stripping the fragment left `""`, and the `|| "index"` fallback below
+ * turned that into the HOME note, so a decorative "on this page" nav row
+ * hijacked the homepage and dragged it into that row's folder. Checking only
+ * for a LEADING `#` missed the slash-prefixed spellings, which is how the
+ * first version of this guard let the same failure through.
+ */
+function isAnchorOnly(href) {
+    if (!/[#?]/.test(href))
+        return false;
+    const path = href
+        .split(/[#?]/)[0]
+        .replace(/^\/docs\/?/, "")
+        .replace(/^\//, "")
+        .replace(/\/$/, "");
+    return path === "";
+}
 function hrefToSlug(href) {
+    if (isAnchorOnly(href))
+        return href;
     return href
-        .replace(/^\/docs\/?/, "")
+        // Otherwise an anchor or query string is not part of the slug. Left on,
+        // `hrefToPath` appended `.md` to the whole thing and produced
+        // `guide/install#configure.md` — a path matching no file, so that nav
+        // entry was dead.
+        .replace(/[#?].*$/, "")
+        .replace(/^\/docs\/?/, "") // legacy nav form
+        .replace(/^\//, "") // leading slash — a nav href is `/overview`, a page slug is `overview`
+        .replace(/\.md$/, "") // some navs carry the file extension
         .replace(/\/$/, "")
         || "index";
 }
@@ -188,6 +643,19 @@ function hrefToPath(href) {
     const slug = hrefToSlug(href);
     return slug === "index" ? "index.md" : `${slug}.md`;
 }
+/** Join a vault folder and file name, tolerating an empty folder. */
+function joinVaultPath(folder, name) {
+    const clean = folder.replace(/^\/+|\/+$/g, "");
+    return clean ? `${clean}/${name}` : name;
+}
+/**
+ * A page's vault-relative path when the nav does not place it — the slug,
+ * mirroring the source tree, rather than just its last segment.
+ */
+function slugToVaultRelPath(slug) {
+    const parts = slug.split("/").filter(Boolean);
+    return parts.length > 0 ? parts.join("/") : "index";
+}
 function fileNameFromSlug(slug) {
     // "tutorial/first-steps" → "first-steps" (folder handles parent)
     const parts = slug.split("/");