@dogsbay/format-obsidian 0.2.0-beta.14 → 0.2.0-beta.141

package/dist/capabilities.d.ts

@@ -0,0 +1,25 @@
+/**
+ * What the Obsidian exporter can and cannot represent — a CONTRACT (the
+ * format-docusaurus pattern): `validateCapabilities` rejects any non-full
+ * entry without a note, and a test asserts every `MATRIX_ROWS` type has
+ * exactly one declaration here. Each entry states what a READER sees in the
+ * vault, measured by running `treeToObsidian` on nodes parsed from real
+ * Dogsbay MD — not what the serializer intends.
+ *
+ * Several rich blocks are emitted as `dogsbay-*` fenced code blocks
+ * (`dogsbay-tabs`, `dogsbay-steps`, `dogsbay-deflist`, `dogsbay-card`,
+ * `dogsbay-code`) that the `dogsbay-docs` Obsidian plugin renders. The vault
+ * export bundles that plugin by default; WITHOUT it a reader sees those
+ * blocks as literal code. "full" for them means "full with the plugin".
+ *
+ * IMPORTANT: this exporter keeps NO ledger. `walkInline` is called without a
+ * `report` callback, so even the losses the shared inline walk does report
+ * (unsafe link/image targets, inline types with no emitter) go nowhere. Every
+ * partial/none below is therefore, today, a loss nothing records at export
+ * time — this declaration is the only place it is stated.
+ *
+ * Support levels: full — faithful · partial — survives with reduced fidelity
+ * (note says how) · none — dropped or flattened (note says what is lost).
+ */
+import type { CapabilityDeclaration } from "@dogsbay/serialize-core";
+export declare const OBSIDIAN_CAPABILITIES: CapabilityDeclaration[];

package/dist/capabilities.js

@@ -0,0 +1,171 @@
+export const OBSIDIAN_CAPABILITIES = [
+    // ── Blocks ───────────────────────────────────────────────
+    { feature: "heading", support: "full", rendersAs: "`#`–`######` + a sanitized, per-page-unique `^block-id` from the slug" },
+    { feature: "paragraph", support: "full" },
+    { feature: "blockquote", support: "full", rendersAs: "`> …`" },
+    { feature: "unordered-list", support: "full", rendersAs: "`- item`" },
+    { feature: "ordered-list", support: "full", rendersAs: "`1. item` (honours `start`)" },
+    { feature: "hr", support: "full", rendersAs: "`---`" },
+    {
+        feature: "table",
+        support: "partial",
+        rendersAs: "GFM pipe table",
+        note: "Cells are single-line: a block inside a cell (list, code, paragraphs) is flattened to one line of text (`- a - b`). A table `caption` is dropped.",
+    },
+    {
+        feature: "code",
+        support: "partial",
+        rendersAs: "plain fence; `dogsbay-code` block (lang/file/highlight/annotations header) when it carries a title, highlights or annotations",
+        note: "Faithful at top level and one container deep. Nested two or more containers deep (tabs/steps/deflist) it becomes a 4-space indented code block: language, title, highlights and annotations are lost.",
+    },
+    { feature: "math-block", support: "full", rendersAs: "`$$ … $$` (native Obsidian MathJax)" },
+    { feature: "deflist", support: "full", rendersAs: "`dogsbay-deflist` block (plugin renders a `<dl>`; definition bodies are full block markdown)" },
+    {
+        feature: "figure",
+        support: "partial",
+        rendersAs: "the image, then the caption as an italic paragraph",
+        note: "No figure/figcaption semantics; the caption is a separate paragraph.",
+    },
+    { feature: "footnote-list", support: "full", rendersAs: "`[^label]: …` definitions (native Obsidian footnotes)" },
+    {
+        feature: "html",
+        support: "partial",
+        rendersAs: "raw HTML passed through (`/_assets/` src/href made vault-relative)",
+        note: "Obsidian's reading-view sanitizer strips scripts, `style`, `class`, `data-*` and most attributes; layout-only markup does nothing. Markdown inside the HTML block is not rendered.",
+    },
+    {
+        feature: "html-container",
+        support: "partial",
+        rendersAs: "its HTML (Obsidian sanitizes it), or its children in place",
+        note: "A children-only container's own markup (tag, class) is dropped; the content is kept.",
+    },
+    { feature: "diagram", support: "full", rendersAs: "```mermaid fence (native Obsidian Mermaid)" },
+    {
+        feature: "youtube",
+        support: "partial",
+        rendersAs: "thumbnail image linking to youtube.com/watch",
+        note: "Not an embedded player: the video opens in a browser.",
+    },
+    // ── Components ───────────────────────────────────────────
+    {
+        feature: "callout",
+        support: "partial",
+        rendersAs: "Obsidian callout `> [!variant] Title`",
+        note: "Variant names pass through verbatim; one Obsidian does not know renders as a note. A custom `icon` is dropped.",
+    },
+    { feature: "details", support: "full", rendersAs: "foldable callout `> [!variant]- Title` (`+` when open)" },
+    { feature: "details-sheet", support: "partial", rendersAs: "a normal collapsible block", note: "Obsidian has no side-sheet component: a `sheet` details is written as an ordinary collapsible block, content intact." },
+    { feature: "theme", support: "partial", rendersAs: "the content, unthemed", note: "Obsidian has no scoped themes: the wrapper is dropped and the content kept, in the page's own theme." },
+    { feature: "tabs-variant", support: "partial", rendersAs: "the default tabs", note: "Obsidian draws one tab style: a pills or underline variant shows as the default." },
+    { feature: "tone", support: "partial", rendersAs: "untinted cards", note: "Obsidian cards take no tone: the colour is lost, the content kept." },
+    { feature: "tabs", support: "full", rendersAs: "`dogsbay-tabs` block (plugin renders tabs; fence characters alternate by nesting depth)" },
+    { feature: "steps", support: "full", rendersAs: "`dogsbay-steps` block (plugin renders numbered steps with titles)" },
+    {
+        feature: "accordion",
+        support: "partial",
+        rendersAs: "one collapsed foldable callout per item, `> [!note]- Label`",
+        note: "Obsidian has no accordion: items fold independently, so opening one does not close the others, and a `defaultValue` is not applied.",
+    },
+    {
+        feature: "cards",
+        support: "partial",
+        rendersAs: "each card as its own `dogsbay-card` block, stacked",
+        note: "No grid container: the column layout is lost.",
+    },
+    {
+        feature: "card",
+        support: "partial",
+        rendersAs: "`dogsbay-card` block (title, href with `.md`, icon, body)",
+        note: "An icon that is a registry NAME (`open-book`, `discord`) is dropped — the vault has no icon registry; image-path and emoji icons are kept.",
+    },
+    {
+        feature: "link-card",
+        support: "partial",
+        rendersAs: "`dogsbay-card` block (title, href, description as the body)",
+        note: "Rendered as a card by the dogsbay-docs plugin; the link-card's compact styling is not distinct from a card's.",
+    },
+    {
+        feature: "files",
+        support: "partial",
+        rendersAs: "the nested list",
+        note: "No file-tree view: folders and files are a nested bulleted list.",
+    },
+    {
+        feature: "grid",
+        support: "partial",
+        rendersAs: "its children stacked (cards as `dogsbay-card` blocks)",
+        note: "No grid container: the column layout is lost.",
+    },
+    {
+        feature: "link-button",
+        support: "partial",
+        rendersAs: "an ordinary Markdown link",
+        note: "Button styling and variant are lost; an unsafe href leaves the label as plain text.",
+    },
+    { feature: "related", support: "full", rendersAs: "bold label + the link list" },
+    {
+        feature: "example",
+        support: "partial",
+        rendersAs: "the rendered example content",
+        note: "No case: the fallthrough renders children only. The example's frame and its `source` (the Markdown shown alongside the result) are dropped.",
+    },
+    {
+        feature: "container",
+        support: "partial",
+        rendersAs: "its children in place",
+        note: "No case: the container's name and title (`props.title` / `meta.title`) are dropped; only the body survives.",
+    },
+    { feature: "annotation-list", support: "full", rendersAs: "its children; the annotations also ride in the `dogsbay-code` header" },
+    // ── API reference ────────────────────────────────────────
+    {
+        feature: "endpoint",
+        support: "partial",
+        rendersAs: "`### METHOD path` heading, summary, description, Markdown tables for parameters / request body / responses, folded `[!example]` callouts for samples and examples",
+        note: "Static: no try-it, no response-tab switching. Spec descriptions are neutralized (their Markdown headings become bold lines); nested schema properties flatten to dotted rows.",
+    },
+    {
+        feature: "api-doc",
+        support: "partial",
+        rendersAs: "the doc HTML converted to Markdown",
+        note: "Inline tags become Markdown and the rest is stripped (flatten mode): block structure inside the docstring HTML (lists, tables) is flattened.",
+    },
+    { feature: "api-class", support: "full", rendersAs: "`### kind \\`name\\``, `Bases:` line, signature in a python fence, children" },
+    { feature: "api-member", support: "full", rendersAs: "`#### kind \\`name\\``, signature in a python fence, children" },
+    { feature: "api-params", support: "full", rendersAs: "HTML table (name, description, TYPE / DEFAULT / REQUIRED meta)" },
+    { feature: "api-source", support: "full", rendersAs: "`*Source: file:line*` + the source in a fence" },
+    // ── Inline ───────────────────────────────────────────────
+    {
+        feature: "link",
+        support: "full",
+        rendersAs: "`[text](vault/path#^block-id)` — site paths made vault-relative, anchors as block-id refs",
+        note: "An unsafe scheme keeps the text and drops the target (not recorded).",
+    },
+    {
+        feature: "image",
+        support: "partial",
+        rendersAs: "`![alt](_assets/…)` (site root stripped)",
+        note: "The image `title` is dropped; an unsafe source leaves only the alt text.",
+    },
+    { feature: "kbd", support: "full", rendersAs: "`<kbd>Ctrl</kbd>+<kbd>S</kbd>` (Obsidian keeps `<kbd>`)" },
+    { feature: "math", support: "full", rendersAs: "`$…$`" },
+    { feature: "highlight", support: "full", rendersAs: "`==text==`" },
+    {
+        feature: "badge",
+        support: "partial",
+        rendersAs: "the badge text as plain text",
+        note: "No inline emitter: the shared walk's fallback writes the text and its report goes nowhere. Variant/styling lost — `Beta` reads as a word in the sentence.",
+    },
+    {
+        feature: "icon",
+        support: "partial",
+        rendersAs: "`:name:` shortcode text",
+        note: "Obsidian does not render emoji/icon shortcodes: the reader sees the literal `:name:`.",
+    },
+    { feature: "footnote-ref", support: "full", rendersAs: "`[^label]`" },
+    {
+        feature: "html-inline",
+        support: "partial",
+        rendersAs: "raw inline HTML passed through",
+        note: "Obsidian's sanitizer strips attributes and most tags in reading view; `<kbd>`, `<b>`, `<i>` and similar survive.",
+    },
+];

package/dist/cli.d.ts

@@ -1,3 +1,2 @@
 import type { FormatPlugin } from "@dogsbay/types";
 export declare const plugin: FormatPlugin;
-//# sourceMappingURL=cli.d.ts.map

package/dist/cli.js

@@ -1,17 +1,20 @@
-import { existsSync, mkdirSync, writeFileSync, cpSync, readdirSync, statSync } from "node:fs";
+import { existsSync, mkdirSync, writeFileSync, readFileSync, cpSync, readdirSync, statSync } from "node:fs";
 import { join, dirname, resolve, relative } from "node:path";
 import { fileURLToPath } from "node:url";
 import { exportObsidianVault } from "./project.js";
+import { OBSIDIAN_CAPABILITIES } from "./capabilities.js";
 const PLUGIN_ID = "dogsbay-docs";
 export const plugin = {
     name: "obsidian",
     canImport: false,
     canExport: true,
+    capabilities: OBSIDIAN_CAPABILITIES,
     detectSource: (path) => existsSync(join(path, ".obsidian")),
     importOptions: [],
     exportOptions: [
         { flags: "--tabs <mode>", description: "Tab handling: dogsbay-tabs (default) or flatten", default: "dogsbay-tabs" },
         { flags: "--plugin <mode>", description: "Plugin setup: bundled (copy into vault), registry (list only), none", default: "bundled" },
+        { flags: "--graph-groups <path>", description: "JSON file of graph-view colour groups: [{ \"query\": \"path:guides\", \"color\": \"#F2B36F\" }]. Replaces the default hub group. Ignored if the vault already has a graph.json" },
     ],
     async export(pages, nav, output, opts) {
         const pluginMode = opts.plugin ?? "bundled";
@@ -26,7 +29,34 @@ export const plugin = {
             writeFileSync(fullPath, content);
         }
         console.log(`Generated ${result.files.size} vault files`);
-        // Copy images from source docs directory into vault
+        // Mounted asset dirs (a Starlight `src/assets`, a Docusaurus `static/`),
+        // copied to `_assets/` to match the `/_assets/…` refs importers rewrite
+        // image paths to. Without this the vault carried the reference and not the
+        // file — the note renders with a broken image and nothing reports it.
+        const mounts = opts.assetMounts;
+        for (const mount of mounts ?? []) {
+            if (!existsSync(mount.dir))
+                continue;
+            // The mount carries the root its refs were rewritten to — `_assets`
+            // for an imported corpus, `images`/`assets` for hand-authored content.
+            // Hardcoding `_assets` here would copy the file somewhere the
+            // reference does not point, which is the broken-image-and-no-report
+            // failure this copy exists to prevent.
+            const root = mount.root ?? "_assets";
+            const dest = mount.into ? join(output, root, mount.into) : join(output, root);
+            mkdirSync(dest, { recursive: true });
+            // `mediaOnly` mounts are whole docs trees (the Docusaurus and VitePress
+            // importers mount their entire docs dir this way) — copying them wholesale
+            // buries hundreds of duplicate .md/.mdx notes under _assets/. Take only
+            // the media, matching format-dogsbay-md's copyMediaTree.
+            if (mount.mediaOnly) {
+                copyMediaTree(mount.dir, dest);
+                continue;
+            }
+            cpSync(mount.dir, dest, { recursive: true });
+        }
+        // Co-located images from the source docs directory (the mkdocs shape,
+        // where media sits next to the markdown rather than in its own tree).
         const sourceDir = opts.sourceDir;
         if (sourceDir) {
             copyImages(sourceDir, output);
@@ -38,8 +68,8 @@ export const plugin = {
         else if (pluginMode === "registry") {
             installRegistryRef(output);
         }
-        // Pre-configure Front Matter Title plugin (graph view shows title, not filename)
-        installFrontMatterTitleConfig(output);
+        // Pre-configure graph view: colour groups + forces tuned for a docs vault
+        installGraphConfig(output, opts.graphGroups);
     },
 };
 /**
@@ -72,12 +102,17 @@ function installBundledPlugin(vaultDir) {
  * Write .obsidian/community-plugins.json listing the plugin.
  * Obsidian will prompt the user to install it from the registry.
  */
-/** Recommended community plugins — listed so Obsidian prompts to install them */
-const FRONT_MATTER_TITLE_ID = "obsidian-front-matter-title-plugin";
-const RECOMMENDED_PLUGINS = [
-    PLUGIN_ID,
-    FRONT_MATTER_TITLE_ID, // Shows frontmatter title in graph view instead of filename
-];
+/**
+ * Plugins listed in community-plugins.json.
+ *
+ * Only plugins the vault actually SHIPS belong here. Listing one we don't
+ * bundle made Obsidian report it as enabled while nothing loaded — the vault
+ * carried a data.json for Front Matter Title and no plugin, so graph labels
+ * silently fell back to filenames. Section notes are named `_<folder>.md` for
+ * exactly that reason, and readers who want frontmatter titles everywhere can
+ * install Front Matter Title themselves (see docs/obsidian-vaults.md).
+ */
+const RECOMMENDED_PLUGINS = [PLUGIN_ID];
 function installRegistryRef(vaultDir) {
     const obsidianDir = join(vaultDir, ".obsidian");
     mkdirSync(obsidianDir, { recursive: true });
@@ -85,29 +120,85 @@ function installRegistryRef(vaultDir) {
     console.log(`Listed plugins in community-plugins.json: ${RECOMMENDED_PLUGINS.join(", ")}`);
 }
 /**
- * Pre-configure Front Matter Title plugin so graph view shows titles.
- * User still needs to install the plugin from community browser,
- * but the settings will be ready when they do.
+ * Read `--graph-groups <path>`: `[{ "query": "path:guides", "color": "#F2B36F" }]`.
+ *
+ * Colours are accepted as `#RRGGBB`, `RRGGBB`, or a raw number, and converted
+ * to the decimal int Obsidian stores — asking an author to write `15905647`
+ * would be a needless papercut.
+ *
+ * Throws on a malformed file rather than silently shipping the default: a
+ * caller who passed the flag wants THEIR groups, and a quiet fallback would
+ * look like the flag being ignored.
  */
-function installFrontMatterTitleConfig(vaultDir) {
-    const configDir = join(vaultDir, ".obsidian", "plugins", FRONT_MATTER_TITLE_ID);
-    mkdirSync(configDir, { recursive: true });
-    const settings = {
-        templates: {
-            common: { main: "title", fallback: "fallback_title" },
-        },
-        features: {
-            graph: { enabled: true, templates: { main: "", fallback: "" } },
-            explorer: { enabled: true, templates: { main: "", fallback: "" } },
-            tab: { enabled: true, templates: { main: "", fallback: "" } },
-        },
-    };
-    writeFileSync(join(configDir, "data.json"), JSON.stringify(settings, null, 2) + "\n");
+function readGraphGroups(path) {
+    let raw;
+    try {
+        raw = JSON.parse(readFileSync(path, "utf8"));
+    }
+    catch (err) {
+        throw new Error(`--graph-groups: could not parse ${path} as JSON: ${err.message}`);
+    }
+    if (!Array.isArray(raw)) {
+        throw new Error(`--graph-groups: ${path} must contain a JSON array of { query, color }`);
+    }
+    return raw.map((entry, i) => {
+        const g = entry;
+        if (!g || typeof g.query !== "string" || !g.query) {
+            throw new Error(`--graph-groups: entry ${i} needs a non-empty "query" string`);
+        }
+        let rgb;
+        if (typeof g.color === "number") {
+            rgb = g.color;
+        }
+        else if (typeof g.color === "string") {
+            const hex = g.color.replace(/^#/, "");
+            if (!/^[0-9a-fA-F]{6}$/.test(hex)) {
+                throw new Error(`--graph-groups: entry ${i} colour "${g.color}" is not #RRGGBB`);
+            }
+            rgb = parseInt(hex, 16);
+        }
+        else {
+            throw new Error(`--graph-groups: entry ${i} needs a "color" (#RRGGBB or a number)`);
+        }
+        return { query: g.query, color: { a: 1, rgb } };
+    });
+}
+function installGraphConfig(vaultDir, groupsPath) {
+    const obsidianDir = join(vaultDir, ".obsidian");
+    const graphPath = join(obsidianDir, "graph.json");
+    if (existsSync(graphPath))
+        return; // the reader's own view state — leave it
+    const colorGroups = groupsPath
+        ? readGraphGroups(groupsPath)
+        : // Default: only the group that is true of EVERY Dogsbay vault. Anything
+            // corpus-specific (a genre axis, a per-book split) belongs to whoever
+            // knows the corpus — pass --graph-groups for those.
+            [{ query: "file:/^_/", color: { a: 1, rgb: 0xf2b3_6f } }];
+    mkdirSync(obsidianDir, { recursive: true });
+    writeFileSync(graphPath, JSON.stringify({
+        "collapse-filter": false,
+        search: "",
+        showTags: false,
+        showAttachments: false,
+        hideUnresolved: true, // unresolved links are noise, not nodes
+        showOrphans: true,
+        "collapse-color-groups": false,
+        colorGroups,
+        "collapse-display": true,
+        showArrow: true, // direction matters when hubs point outward
+        textFadeMultiplier: -1.5, // labels only when zoomed in; a docs vault is dense
+        nodeSizeMultiplier: 0.9,
+        lineSizeMultiplier: 0.7,
+        "collapse-forces": true,
+        centerStrength: 0.5,
+        repelStrength: 7, // below the default 10 — let clusters tighten
+        linkStrength: 1,
+        linkDistance: 180,
+        scale: 1,
+        close: false,
+    }, null, 2) + "\n");
+    console.log("Pre-configured graph view (.obsidian/graph.json)");
 }
-/**
- * Copy images from source docs directory into the vault root.
- * Image paths in markdown (e.g. /img/foo.png) become relative vault paths.
- */
 function copyImages(sourceDir, vaultDir) {
     const imageExts = new Set([".png", ".jpg", ".jpeg", ".gif", ".svg", ".webp"]);
     let count = 0;
@@ -158,4 +249,29 @@ function resolvePluginDist() {
     }
     return null;
 }
-//# sourceMappingURL=cli.js.map
+/** Media extensions carried across for a `mediaOnly` mount — mirrors format-dogsbay-md. */
+const MEDIA_EXTS = new Set([
+    ".png", ".jpg", ".jpeg", ".gif", ".webp", ".avif",
+    ".svg", ".ico", ".pdf", ".mp4", ".webm",
+]);
+/**
+ * Copy only media files out of a mount, preserving its subtree shape.
+ *
+ * A `mediaOnly` mount is a whole docs directory (Docusaurus and VitePress both
+ * mount theirs that way), so a recursive copy would bury every `.md`/`.mdx` in
+ * the source under `_assets/` as duplicate notes.
+ */
+function copyMediaTree(srcDir, destDir) {
+    for (const entry of readdirSync(srcDir, { withFileTypes: true })) {
+        const full = join(srcDir, entry.name);
+        if (entry.isDirectory()) {
+            copyMediaTree(full, join(destDir, entry.name));
+            continue;
+        }
+        const dot = entry.name.lastIndexOf(".");
+        if (dot === -1 || !MEDIA_EXTS.has(entry.name.slice(dot).toLowerCase()))
+            continue;
+        mkdirSync(destDir, { recursive: true });
+        cpSync(full, join(destDir, entry.name));
+    }
+}

package/dist/index.d.ts

@@ -1,5 +1,5 @@
 export { treeToObsidian } from "./serialize.js";
 export { exportObsidianVault } from "./project.js";
+export { OBSIDIAN_CAPABILITIES } from "./capabilities.js";
 export type { ObsidianVaultOptions, ObsidianVaultExport } from "./project.js";
 export type { TreeNode, InlineNode, ExportPage, NavItem } from "@dogsbay/types";
-//# sourceMappingURL=index.d.ts.map

package/dist/index.js

@@ -1,4 +1,4 @@
 // Obsidian format plugin — serialize (tree → Obsidian markdown) + vault export
 export { treeToObsidian } from "./serialize.js";
 export { exportObsidianVault } from "./project.js";
-//# sourceMappingURL=index.js.map
+export { OBSIDIAN_CAPABILITIES } from "./capabilities.js";

package/dist/project.d.ts

@@ -2,21 +2,67 @@
  * Obsidian vault exporter.
  *
  * Takes ExportPage[] + NavItem[] and generates a complete Obsidian vault
- * with folder structure from nav, sidebar_position frontmatter, _index.md
+ * with folder structure from nav, sidebar_position frontmatter, folder notes
  * per section, and _nav.yml for lossless round-trip.
  */
 import type { ExportPage, NavItem } from "@dogsbay/types";
 export interface ObsidianVaultOptions {
     vaultName?: string;
-    assetsDir?: string;
     /** Section name — pages go under this subfolder, nav gets a top-level entry */
     section?: string;
+    /**
+     * Emit a `_<folder>.md` folder note per nav section (default `true`).
+     *
+     * These are **invented by this exporter** — no source format supplies them,
+     * and they do not appear in `_nav.yml` (a section is a label-only nav entry
+     * with no path), so the folder note is the only thing that makes a section
+     * addressable at all.
+     *
+     * Measured on the OpenShift 4.22 vault (2,105 notes), they are load-bearing
+     * once populated — they carry the nav as real links, and are the sole
+     * inbound link for ~470 content pages that no prose links to:
+     *
+     * | | notes | edges | no inbound | isolated |
+     * |---|---|---|---|---|
+     * | with, populated | 2,105 | 6,954 | 44 | 0 |
+     * | without | 1,796 | 4,893 | 523 | 278 |
+     *
+     * Set `false` for a vault that mirrors the source exactly — at the cost of
+     * the folder-click affordance and the nav-as-links layer.
+     */
+    sectionIndexes?: boolean;
+    /**
+     * Give every folder note a body listing its children (default `true`).
+     * Ignored when `sectionIndexes` is `false`.
+     *
+     * Without it a section index is frontmatter and nothing else: clicking a
+     * folder in Obsidian yields a title and white space, and the note has no
+     * outbound links, so it sits outside the graph. On the OpenShift 4.22 export
+     * that was 309 of 309 section indexes with zero links — the entire outer
+     * ring of orphans in the graph view.
+     *
+     * The listing is ordinary markdown links, so it also feeds backlinks, the
+     * local graph, and any consumer that reads links rather than a nav file.
+     *
+     * Set `false` to keep the frontmatter-only stubs (previous behaviour).
+     */
+    sectionIndexLinks?: boolean;
 }
 export interface ObsidianVaultExport {
     files: Map<string, string>;
 }
+/**
+ * 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 declare function sectionNotePath(folderPath: string): string;
 /**
  * Export pages + nav to an Obsidian vault file map.
  */
 export declare function exportObsidianVault(pages: ExportPage[], nav: NavItem[], options?: ObsidianVaultOptions): ObsidianVaultExport;
-//# sourceMappingURL=project.d.ts.map