@dogsbay/format-dogsbay-md 0.2.0-beta.14 → 0.2.0-beta.140

package/dist/attributes.d.ts

@@ -8,12 +8,27 @@
 export interface RenderedAttrs {
     id?: string;
     classes?: string[];
-    props?: Record<string, string | number | boolean | undefined>;
+    /**
+     * Props captured from `TreeNode.props`. Primitive values (string,
+     * number, boolean) round-trip through inline `{key="value"}` form.
+     * Arrays / plain objects are preserved here too — `renderAttrs`
+     * skips them (inline form can't represent them) but the
+     * directive renderer's `shouldUseYaml` branch picks them up and
+     * routes the directive to YAML body form, where complex values
+     * survive intact.
+     */
+    props?: Record<string, unknown>;
 }
 /**
  * Render an attribute block.
  * Returns `{ #id .a .b key="value" }` or "" if no attrs.
  * Leading space included so callers can append directly to content.
+ *
+ * Inline form can only carry primitive values. Arrays / objects in
+ * `props` are silently skipped here — the caller is expected to have
+ * already routed those to YAML body form (see `shouldUseYaml` in
+ * directives.ts). If a non-primitive does reach this point, dropping
+ * it is the safest fallback (there's no inline syntax for it).
  */
 export declare function renderAttrs(attrs: RenderedAttrs): string;
 /**
@@ -30,4 +45,3 @@ export declare function escapeAttrValue(value: string): string;
  * This is the common glue between TreeNode.props and attribute output.
  */
 export declare function splitProps(props: Record<string, unknown> | undefined, excludeKeys?: string[]): RenderedAttrs;
-//# sourceMappingURL=attributes.d.ts.map

package/dist/attributes.js

@@ -9,6 +9,12 @@
  * Render an attribute block.
  * Returns `{ #id .a .b key="value" }` or "" if no attrs.
  * Leading space included so callers can append directly to content.
+ *
+ * Inline form can only carry primitive values. Arrays / objects in
+ * `props` are silently skipped here — the caller is expected to have
+ * already routed those to YAML body form (see `shouldUseYaml` in
+ * directives.ts). If a non-primitive does reach this point, dropping
+ * it is the safest fallback (there's no inline syntax for it).
  */
 export function renderAttrs(attrs) {
     const parts = [];
@@ -29,6 +35,10 @@ export function renderAttrs(attrs) {
                 parts.push(key);
                 continue;
             }
+            // Skip arrays / plain objects — inline form can't represent
+            // them. They survive via the YAML body branch upstream.
+            if (typeof value === "object")
+                continue;
             parts.push(`${key}=${escapeAttrValue(String(value))}`);
         }
     }
@@ -71,8 +81,10 @@ export function splitProps(props, excludeKeys = []) {
         }
         if (value === null || value === undefined)
             continue;
-        if (typeof value === "object")
-            continue; // skip nested structures
+        // Pass arrays / objects through. Inline-form rendering will skip
+        // them (`renderAttrs`); YAML-body rendering preserves them
+        // (`attrsToYaml`). The `shouldUseYaml` heuristic in directives.ts
+        // detects their presence and routes the directive accordingly.
         cleanProps[key] = value;
     }
     if (Object.keys(cleanProps).length > 0) {
@@ -80,4 +92,3 @@ export function splitProps(props, excludeKeys = []) {
     }
     return result;
 }
-//# sourceMappingURL=attributes.js.map

package/dist/browser.d.ts

@@ -0,0 +1,27 @@
+/**
+ * Browser-safe entry point — the pure TreeNode round-trip and text
+ * helpers, with NO `node:fs` in the module graph.
+ *
+ * The main barrel (`.`) re-exports nav / nav-file / mermaid, which
+ * import `node:fs` at module load and so break browser/extension
+ * bundling. Consumers that only need parse/serialize (the editing
+ * engine, extension contexts) import from `@dogsbay/format-dogsbay-md/browser`
+ * instead. `parse.ts` and `serialize.ts` transit only browser-safe deps
+ * (markdown-it, js-yaml). Frontmatter is split by the local `frontmatter.ts`
+ * (js-yaml only) rather than gray-matter, whose entry `require('fs')`s at
+ * module load and would drag `node:fs` back into this graph.
+ */
+export { dogsbayMdToTree, parseInline, containerOpenBefore, type ParseResult, type ParseOptions } from "./parse.js";
+export { KNOWN_INLINE_DIRECTIVES, type ParseDiagnostic } from "./diagnostics.js";
+export { KNOWN_BLOCK_DIRECTIVES, LEAF_ONLY_DIRECTIVES, BLOCK_LEAF_DIRECTIVES } from "./plugin-containers.js";
+export { treeToDogsbayMd, nodeToDogsbayMd } from "./serialize.js";
+export type { SerializeOptions } from "./types.js";
+export { inlineToDogsbayMd } from "./inline.js";
+export { transformCodeRegions, transformProseLines, transformProseSegments, fenceOpenBefore, createFenceTracker, } from "./code-regions.js";
+export { maskMinjaInCode, unmaskMinjaInCode, maskAllMinjaOpeners, isMinjaProcessedFence, stripInlineMinjaMarkers, stripFenceMinjaMarkers } from "./minja-mask.js";
+export { extractHeadings, slugifyHeadingText, type HeadingInfo } from "./headings.js";
+export { splitFrontmatter, type Frontmatter } from "./frontmatter.js";
+export { DataFiles, DataCache, DataFileError, parseDataFile, parseDelimited, DEFAULT_DATA_LIMITS, UNTRUSTED_DATA_LIMITS, DATA_EXTENSIONS, type DataLimits, type DataFilesOptions, type DataExtension, } from "./data-files.js";
+export { resolveDataDirectives, hasDataDirectives, DATA_DIRECTIVES, NO_PROJECT_MESSAGE, type DataProblem, type DataDirectivesResult, } from "./data-directives.js";
+export { TemplatePages, TemplatePageError, declaresParams, ATTRIBUTE_BLOCK_OPEN, type TemplatePagesOptions } from "./template-pages.js";
+export { dogsbayMdPageFiles, dogsbayMdPagePath, mountCopies, carriedFrontmatter, MEDIA_EXTS, type AssetMount } from "./project.js";

package/dist/browser.js

@@ -0,0 +1,27 @@
+/**
+ * Browser-safe entry point — the pure TreeNode round-trip and text
+ * helpers, with NO `node:fs` in the module graph.
+ *
+ * The main barrel (`.`) re-exports nav / nav-file / mermaid, which
+ * import `node:fs` at module load and so break browser/extension
+ * bundling. Consumers that only need parse/serialize (the editing
+ * engine, extension contexts) import from `@dogsbay/format-dogsbay-md/browser`
+ * instead. `parse.ts` and `serialize.ts` transit only browser-safe deps
+ * (markdown-it, js-yaml). Frontmatter is split by the local `frontmatter.ts`
+ * (js-yaml only) rather than gray-matter, whose entry `require('fs')`s at
+ * module load and would drag `node:fs` back into this graph.
+ */
+export { dogsbayMdToTree, parseInline, containerOpenBefore } from "./parse.js";
+export { KNOWN_INLINE_DIRECTIVES } from "./diagnostics.js";
+// The `:::name` blocks the parser knows (an editor completes names from it)
+export { KNOWN_BLOCK_DIRECTIVES, LEAF_ONLY_DIRECTIVES, BLOCK_LEAF_DIRECTIVES } from "./plugin-containers.js";
+export { treeToDogsbayMd, nodeToDogsbayMd } from "./serialize.js";
+export { inlineToDogsbayMd } from "./inline.js";
+export { transformCodeRegions, transformProseLines, transformProseSegments, fenceOpenBefore, createFenceTracker, } from "./code-regions.js";
+export { maskMinjaInCode, unmaskMinjaInCode, maskAllMinjaOpeners, isMinjaProcessedFence, stripInlineMinjaMarkers, stripFenceMinjaMarkers } from "./minja-mask.js";
+export { extractHeadings, slugifyHeadingText } from "./headings.js";
+export { splitFrontmatter } from "./frontmatter.js";
+export { DataFiles, DataCache, DataFileError, parseDataFile, parseDelimited, DEFAULT_DATA_LIMITS, UNTRUSTED_DATA_LIMITS, DATA_EXTENSIONS, } from "./data-files.js";
+export { resolveDataDirectives, hasDataDirectives, DATA_DIRECTIVES, NO_PROJECT_MESSAGE, } from "./data-directives.js";
+export { TemplatePages, TemplatePageError, declaresParams, ATTRIBUTE_BLOCK_OPEN } from "./template-pages.js";
+export { dogsbayMdPageFiles, dogsbayMdPagePath, mountCopies, carriedFrontmatter, MEDIA_EXTS } from "./project.js";

package/dist/capabilities.d.ts

@@ -0,0 +1,25 @@
+/**
+ * What the Dogsbay MD exporter can and cannot represent — a CONTRACT (the
+ * format-docusaurus pattern): one cell per `MATRIX_ROWS` type of the
+ * component × format matrix, checked by `validateCapabilities` and by
+ * tests/capabilities.test.ts.
+ *
+ * Dogsbay MD is the CANONICAL source format, so the bar for `full` is a
+ * round trip: `treeToDogsbayMd` → `dogsbayMdToTree` gives back the same tree
+ * (modulo canonical spelling — `:::tab[One]` comes back as the deflist tab
+ * form, a trailing newline on raw HTML). Each `full` below was measured that
+ * way, not assumed.
+ *
+ * Support levels: full — round-trips · partial — survives with reduced
+ * fidelity (the note says how) · none — dropped or flattened (the note says
+ * what is lost).
+ *
+ * Types with no `case` in `renderNode` fall to `renderUnknown`: with the
+ * default `unknownNodes: "html"` it writes `node.html` if present, else the
+ * children (the wrapper and its props are lost), else
+ * `<!-- unsupported: <type> -->`. Nothing is recorded — there is no export
+ * ledger in this package yet — so every partial/none here is a loss the
+ * exporter does not report.
+ */
+import type { CapabilityDeclaration } from "@dogsbay/serialize-core";
+export declare const DOGSBAY_MD_CAPABILITIES: CapabilityDeclaration[];

package/dist/capabilities.js

@@ -0,0 +1,91 @@
+export const DOGSBAY_MD_CAPABILITIES = [
+    // ── Blocks ───────────────────────────────────────────────
+    { feature: "heading", support: "full", rendersAs: "`#`–`######` with `{#id .class}` attrs" },
+    { feature: "paragraph", support: "full" },
+    { feature: "blockquote", support: "full", rendersAs: "`> …`" },
+    { feature: "unordered-list", support: "full", rendersAs: "`- item`" },
+    { feature: "ordered-list", support: "full", rendersAs: "`1. item`" },
+    { feature: "hr", support: "full", rendersAs: "`---`" },
+    {
+        feature: "table",
+        support: "partial",
+        rendersAs: "GFM pipe table + `{caption=\"…\"}`; an HTML `<table>` when a cell holds blocks, a row has `th` cells, or the table is headerless",
+        note: "A simple table round-trips. The HTML fallback re-parses as a raw `html` node, not a `table`; inside it blocks other than paragraph/list/code/callout/table collapse to their content and kbd/icon/math/footnote-ref degrade to text.",
+    },
+    { feature: "code", support: "full", rendersAs: "fenced block with language, `title=\"…\"` and line-highlight meta" },
+    { feature: "math-block", support: "full", rendersAs: "`$$ … $$`" },
+    { feature: "deflist", support: "full", rendersAs: "`Term` / `: definition`" },
+    { feature: "figure", support: "full", rendersAs: "`:::figure{caption=\"…\"}`; a captionless figure is written as its content" },
+    { feature: "footnote-list", support: "full", rendersAs: "`[^label]: …` definitions" },
+    { feature: "html", support: "full", rendersAs: "the raw HTML, verbatim" },
+    {
+        feature: "html-container",
+        support: "partial",
+        rendersAs: "`node.html` verbatim, or the container's children as blocks",
+        note: "Content is kept; a children-only container (the shape the mkdocs md_in_html, asciidoc and mdx importers produce) loses its wrapper tag and attributes.",
+    },
+    {
+        feature: "diagram",
+        support: "partial",
+        rendersAs: "a ```mermaid fence with the diagram source",
+        note: "The source round-trips (it re-parses as a code fence, which the build turns back into a diagram); a pre-rendered SVG is not kept.",
+    },
+    { feature: "youtube", support: "full", rendersAs: "`::youtube{#id title=\"…\"}`" },
+    // ── Components ───────────────────────────────────────────
+    { feature: "callout", support: "full", rendersAs: "GitHub alert `> [!NOTE]`; `:::type[Title]{…}` for a custom title or a non-GitHub type" },
+    { feature: "details", support: "full", rendersAs: "`:::details{title=\"…\"}`" },
+    { feature: "details-sheet", support: "full", rendersAs: "`:::details{title=\"…\" sheet}`" },
+    { feature: "theme", support: "full", rendersAs: "`:::theme{name=\"dark\"}` around the content" },
+    { feature: "tabs-variant", support: "full", rendersAs: "`:::tabs{variant=\"pills\"}`" },
+    { feature: "tone", support: "full", rendersAs: "`tone=\"…\"` on `:::cards` or `:::card`" },
+    { feature: "tabs", support: "full", rendersAs: "`:::tabs` with the deflist tab form (`Label` / `:   body`)" },
+    { feature: "steps", support: "full", rendersAs: "`:::steps` around an ordered list" },
+    { feature: "accordion", support: "full", rendersAs: "`:::accordion` with deflist items" },
+    { feature: "cards", support: "full", rendersAs: "`:::cards` — compact YAML list when every card body is paragraphs, `:::card` directives otherwise" },
+    { feature: "card", support: "full", rendersAs: "`:::card{title href …}`" },
+    { feature: "link-card", support: "full", rendersAs: "`:::link-card{title href}` with the description as body" },
+    { feature: "files", support: "full", rendersAs: "`:::files` around the nested list" },
+    { feature: "grid", support: "full", rendersAs: "`::::grid` / `:::grid-item`" },
+    { feature: "link-button", support: "full", rendersAs: "`:::button{href}`" },
+    { feature: "related", support: "full", rendersAs: "bold caption + `{._additional-resources}` + the link list (the shape the parser folds back)" },
+    {
+        feature: "example",
+        support: "partial",
+        rendersAs: "its children, unwrapped",
+        note: "No case: `renderUnknown` writes the children only. The `:::example` wrapper (live preview + shown source) is lost and the content re-parses as ordinary blocks; unrecorded.",
+    },
+    {
+        feature: "container",
+        support: "partial",
+        rendersAs: "`:::name` for this format's own generic containers; the children otherwise",
+        note: "A container parsed from Dogsbay MD (`meta.container` + `meta.name`) round-trips. A `container` from another importer has no name to write: its wrapper and props (class, id) are dropped and only the children survive; unrecorded.",
+    },
+    {
+        feature: "annotation-list",
+        support: "partial",
+        rendersAs: "each item's content as a separate paragraph",
+        note: "No case: `renderUnknown` writes the children, and the list items render without list markers — numbering and the link to the code block's `(n)` markers are lost; unrecorded.",
+    },
+    // ── API reference ────────────────────────────────────────
+    {
+        feature: "endpoint",
+        support: "partial",
+        rendersAs: "`## METHOD /path` + summary/description + Parameters table + request-body/response lists + code-sample fences",
+        note: "Readable Markdown, but not a structure: it re-parses as headings/tables/lists, never an `endpoint`. Schemas beyond name/type/required/description, and spec raw HTML (escaped as `&lt;`), are not carried.",
+    },
+    { feature: "api-doc", support: "full", rendersAs: "`:::api-doc{…}`" },
+    { feature: "api-class", support: "full", rendersAs: "`:::api-class{…}`" },
+    { feature: "api-member", support: "full", rendersAs: "`:::api-member{…}`" },
+    { feature: "api-params", support: "full", rendersAs: "`:::api-params` with a YAML `params:` body" },
+    { feature: "api-source", support: "full", rendersAs: "`:::api-source{…}`" },
+    // ── Inline ───────────────────────────────────────────────
+    { feature: "link", support: "full", rendersAs: "`[text](href \"title\")`" },
+    { feature: "image", support: "full", rendersAs: "`![alt](src \"title\"){attrs}`" },
+    { feature: "kbd", support: "full", rendersAs: "`:kbd[Ctrl+S]`" },
+    { feature: "math", support: "full", rendersAs: "`$…$`" },
+    { feature: "highlight", support: "full", rendersAs: "`==…==`" },
+    { feature: "badge", support: "full", rendersAs: "`:badge[Text]{variant=…}`" },
+    { feature: "icon", support: "full", rendersAs: "`:icon[name]`" },
+    { feature: "footnote-ref", support: "full", rendersAs: "`[^label]`" },
+    { feature: "html-inline", support: "full", rendersAs: "the raw HTML, verbatim" },
+];

package/dist/cli.d.ts

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

package/dist/cli.js

@@ -4,11 +4,17 @@
  * Reads a directory of .md files, parses each via dogsbayMdToTree, builds nav
  * from directory structure + frontmatter, returns ExportPage[] + NavItem[].
  */
-import { existsSync, readdirSync, readFileSync, statSync } from "node:fs";
-import { join, relative, basename } from "node:path";
+import { copyFileSync, existsSync, mkdirSync, readdirSync, readFileSync, statSync, writeFileSync } from "node:fs";
+import { join, relative, basename, dirname } from "node:path";
+import { extractHeadings } from "./headings.js";
 import { parseMeta } from "@dogsbay/types";
 import { dogsbayMdToTree } from "./parse.js";
 import { buildNavFromDirectory } from "./nav.js";
+import { renderDiagrams } from "./renderers/diagrams.js";
+import { DOGSBAY_MD_CAPABILITIES } from "./capabilities.js";
+import { dogsbayMdPageFiles, mountCopies } from "./project.js";
+import { readFolder } from "@dogsbay/corpus/folder";
+export { carriedFrontmatter } from "./project.js";
 /**
  * Detect whether a directory contains a Dogsbay MD source tree.
  *
@@ -30,16 +36,76 @@ function detectDogsbayMdSource(path) {
         return false;
     }
 }
+/**
+ * Conventional content-asset roots, in probe order. Mounted under their own
+ * name so an author's `/images/logo.png` resolves, and excluded from the page
+ * walk so their contents are assets rather than also being pages.
+ */
+const ASSET_ROOTS = ["images", "assets", "_assets"];
+/**
+ * Does this directory hold any markdown, at any depth?
+ *
+ * Distinguishes a media-only asset root (skip it: its files are assets, and a
+ * stray .md would become both a page and a raw copy in public/) from a docs
+ * SECTION that merely shares the name (walk it: those are pages).
+ */
+function containsMarkdown(dir) {
+    let entries;
+    try {
+        entries = readdirSync(dir, { withFileTypes: true });
+    }
+    catch {
+        return false;
+    }
+    for (const e of entries) {
+        if (e.isDirectory()) {
+            if (containsMarkdown(join(dir, e.name)))
+                return true;
+        }
+        else if (e.name.endsWith(".md")) {
+            return true;
+        }
+    }
+    return false;
+}
 function walkMdFiles(dir, root, out = []) {
     for (const entry of readdirSync(dir, { withFileTypes: true })) {
+        // `_`-prefixed files/dirs are include targets (fragments), not routable
+        // pages — the standard Jekyll/Docusaurus convention. The build-time Minja
+        // preprocessor `{% include %}`s them into pages; they get no route of their
+        // own. (e.g. structural Docusaurus import writes `_includes/**` fragments.)
+        if (entry.name.startsWith("_"))
+            continue;
+        // A conventional asset root carrying only media is not a page tree, and
+        // leaving it in the walk would make a stray .md there BOTH a routable
+        // page and a file copied verbatim into public/.
+        //
+        // But `images/` is also a perfectly ordinary section name. Skipping it
+        // unconditionally silently dropped every page under it — "Imported 1
+        // pages" where there were 2, no warning. So skip only a root that
+        // carries NO markdown at all, and only at the content root.
+        if (dir === root &&
+            ASSET_ROOTS.includes(entry.name) &&
+            !containsMarkdown(join(dir, entry.name))) {
+            continue;
+        }
         const full = join(dir, entry.name);
         if (entry.isDirectory()) {
             walkMdFiles(full, root, out);
         }
         else if (entry.name.endsWith(".md")) {
             const rel = relative(root, full).replace(/\\/g, "/");
-            const slug = rel.replace(/\.md$/, "");
-            out.push({ filePath: full, slug });
+            let slug = rel.replace(/\.md$/, "");
+            // A `<dir>/index.md` page is the directory's landing page: its slug
+            // is the directory, not `<dir>/index`. This MUST match how the nav
+            // layer normalizes the same file (nav-file.ts `fileToHref` strips
+            // `/index`), or `routablesFrom: nav`'s `filterPagesToNav` drops the
+            // page and the section landing 404s. The bare root `index.md` keeps
+            // slug `index` — format-astro's root-home + `.md`-mirror special-case
+            // keys off `slug === "index"`. See plans/dir-index-slug-nav-drop.md.
+            if (slug.endsWith("/index"))
+                slug = slug.slice(0, -"/index".length);
+            out.push({ filePath: full, slug, sourcePath: rel });
         }
     }
     return out;
@@ -61,30 +127,38 @@ async function importDogsbayMd(source, opts) {
     const taxonomyNames = Array.isArray(opts.taxonomyNames)
         ? opts.taxonomyNames
         : undefined;
-    for (const { filePath, slug } of files) {
+    // Pre-parse pass — opt-out via `diagrams: false`. When enabled
+    // (default), `code` fences with `lang: mermaid` get transformed
+    // to `diagram` nodes with pre-rendered SVG. Fail-open: if mmdc
+    // (mermaid-cli) isn't installed the code block is left as-is and
+    // a one-line warning is printed. See plans/mermaid-dogsbay-md.md.
+    const diagramsOn = opts.diagrams !== false;
+    // `content.diagrams: pele` draws them with Pele; `true` (the default) with mmdc
+    const diagramEngine = opts.diagrams === "pele" ? "pele" : "mermaid-cli";
+    for (const { filePath, slug, sourcePath } of files) {
         const content = readFileSync(filePath, "utf-8");
         const { tree, frontmatter } = dogsbayMdToTree(content);
+        if (diagramsOn) {
+            await renderDiagrams(tree, { engine: diagramEngine });
+        }
         const title = String(frontmatter.title
             ?? prettifyName(basename(slug)));
-        // Extract heading metadata for TOC
-        const headings = [];
-        for (const node of tree) {
-            if (node.type === "heading" && node.inline) {
-                const text = node.inline
-                    .map((n) => (n.type === "text" ? n.text : ""))
-                    .join("")
-                    .trim();
-                headings.push({
-                    depth: node.props?.level ?? 1,
-                    slug: node.props?.slug ?? slugify(text),
-                    text,
-                });
-            }
-        }
+        // Extract heading metadata for TOC AND backfill `node.props.slug`
+        // so format-astro's headingToAstro emits a matching `id` on the
+        // rendered `<h2>` / `<h3>`. Without this, the TOC's
+        // `<a href="#quick-start">` had nothing to scroll to — the
+        // heading was emitted without an id because the tree didn't
+        // carry the slug. Mirrors format-mkdocs/src/loader.ts:312.
+        //
+        // Duplicate slugs get `-1`, `-2` suffixes so two `## Foo`
+        // headings on the same page produce distinct anchors. Same
+        // collision-handling shape as MkDocs.
+        const headings = extractHeadings(tree);
         const redirect = frontmatter.redirect;
         const meta = parseMeta(frontmatter, { slug, taxonomyNames });
         pages.push({
             slug,
+            sourcePath,
             title,
             tree,
             headings,
@@ -95,8 +169,42 @@ async function importDogsbayMd(source, opts) {
     }
     const navFilePath = opts.nav || undefined;
     const hrefPrefix = typeof opts.hrefPrefix === "string" ? opts.hrefPrefix : undefined;
-    const nav = buildNavFromDirectory(source, { navFilePath, hrefPrefix });
-    return { pages, nav };
+    // `--strict` at the CLI layer maps to "fail" here. `loadNavFile`
+    // already throws on the first miss in fail mode; the build
+    // surfaces the throw as a fatal error and exits non-zero.
+    // See plans/site-build-strict.md.
+    const missingNavTargets = opts.missingNavTargets === "fail"
+        ? "fail"
+        : undefined;
+    const nav = buildNavFromDirectory(source, {
+        navFilePath,
+        hrefPrefix,
+        missingFile: missingNavTargets,
+    });
+    // Declare where this corpus's media lives, so an exporter copies the FILES
+    // that the `_assets/…` references in the pages point at.
+    //
+    // Without this the reference survives the conversion and the file does not,
+    // which looks exactly like success: the page count, the retention score and
+    // a clean exit are all unaffected while every image 404s. `dogsbay site
+    // build` has its own asset pass, so this was invisible there and only bit
+    // `convert` — an OpenShift vault shipped with 294 dead image references.
+    // Conventional asset roots, in probe order. `_assets` is what every
+    // importer rewrites its refs to and stays the documented convention
+    // (docs/images.md). Hand-authored content is not written by an
+    // importer, though: someone starting a site types `/images/logo.png`,
+    // which silently resolved nowhere because only `_assets` was probed.
+    //
+    // Each root that exists mounts under its OWN name, so the reference the
+    // author wrote is the path the file lands at. Recognising several costs
+    // nothing: an absent directory is simply not mounted.
+    const assetMounts = [];
+    for (const root of ASSET_ROOTS) {
+        const dir = join(source, root);
+        if (existsSync(dir))
+            assetMounts.push({ dir, root });
+    }
+    return assetMounts.length ? { pages, nav, assetMounts } : { pages, nav };
 }
 function prettifyName(slug) {
     return slug
@@ -104,17 +212,53 @@ function prettifyName(slug) {
         .map((w) => w.charAt(0).toUpperCase() + w.slice(1))
         .join(" ");
 }
-function slugify(text) {
-    return text
-        .toLowerCase()
-        .replace(/[^\w\s-]/g, "")
-        .trim()
-        .replace(/\s+/g, "-");
+/**
+ * Export ExportPage[] + nav to a directory of Dogsbay-MD files.
+ *
+ * Each page's tree is serialized via `treeToDogsbayMd` (which preserves any
+ * Minja directives via `escapePreservingMinja`) and written to `<output>/<slug>.md`.
+ *
+ * Fragment pages (`page.fragment`) are include targets, not routable pages:
+ * written with NO frontmatter, NO title, and excluded from nav — their identity
+ * is the include path. Mirrors migrate-asciidoc's fragment convention so the
+ * build-time Minja preprocessor can `{% include %}` them.
+ */
+async function exportDogsbayMd(pages, nav, output, opts) {
+    mkdirSync(output, { recursive: true });
+    // Copy mounted asset dirs (e.g. Docusaurus `static/`) into `content/_assets/`,
+    // the Dogsbay standard (docs/images.md). Preserves internal structure
+    // (static/img/x → <output>/_assets/img/x) so the parser's rewritten
+    // `/_assets/img/x` refs resolve, and a later `site build`'s asset pass copies
+    // `content/_assets/**` through to `/_assets/**`. A mount may target an
+    // `_assets` subdir (`into`) and restrict itself to media files (`mediaOnly`) —
+    // used for docs-co-located images where the mount dir IS the docs tree.
+    // The copy is `mountCopies` over the mount read as a corpus — the list the browser import
+    // copies from its map, so both hosts copy the same files. A mount is someone else's repo:
+    // a symlink out of it (`public/leak.png -> ~/.ssh/id_rsa`) was copied as a link to that
+    // file, and `node_modules` / `.git` inside it were copied whole (2026-10-21).
+    if (Array.isArray(opts.assetMounts)) {
+        for (const mount of opts.assetMounts) {
+            if (!existsSync(mount.dir))
+                continue;
+            const folder = readFolder(mount.dir);
+            for (const { from, to } of mountCopies(folder.paths, [{ ...mount, dir: "" }])) {
+                const dst = join(output, to);
+                mkdirSync(dirname(dst), { recursive: true });
+                copyFileSync(folder.absolute(from), dst);
+            }
+        }
+    }
+    for (const [path, text] of dogsbayMdPageFiles(pages, nav)) {
+        const outPath = join(output, path);
+        mkdirSync(dirname(outPath), { recursive: true });
+        writeFileSync(outPath, text, "utf-8");
+    }
 }
 export const plugin = {
     name: "dogsbay-md",
     canImport: true,
-    canExport: false,
+    canExport: true,
+    capabilities: DOGSBAY_MD_CAPABILITIES,
     detectSource: detectDogsbayMdSource,
     importOptions: [
         {
@@ -125,5 +269,7 @@ export const plugin = {
     async import(source, opts) {
         return importDogsbayMd(source, opts);
     },
+    async export(pages, nav, output, opts) {
+        return exportDogsbayMd(pages, nav, output, opts);
+    },
 };
-//# sourceMappingURL=cli.js.map

package/dist/code-regions.d.ts

@@ -0,0 +1,88 @@
+/**
+ * Code-region walker — THE fence grammar shared by every tool that must
+ * treat code specially: the build preprocessor masks Minja openers
+ * inside code so template examples never evaluate, the workspace
+ * indexer blanks code so `{% include %}` examples never count as real
+ * includes, and the refactor commands edit only prose so code samples
+ * are never rewritten. One implementation, so none of them can drift.
+ *
+ * Fence rules (CommonMark): a fence opens with ``` or ~~~ (3+ chars,
+ * info string allowed) and closes only on a line of the SAME character
+ * with AT LEAST the opener's length and nothing but whitespace after —
+ * the serializer emits escalated fences (```` around content containing
+ * ```), so honoring the length rule is load-bearing. Fence-looking
+ * lines inside an open fence that don't close it are code content.
+ */
+type LineKind = "prose" | "fence" | "code";
+/** Context passed to a code transform: which fence the line belongs to. */
+export interface CodeRegionContext {
+    /**
+     * Fence info string (e.g. `yaml {minja}`). For inline code spans:
+     * the markdown-it-attrs group immediately following the closing
+     * backticks when present (e.g. `{minja}` for `` `x`{minja} ``),
+     * empty otherwise — so `isMinjaProcessedFence` grades fences and
+     * marked inline spans with the same predicate.
+     */
+    fenceInfo: string;
+}
+/**
+ * Transform CODE content: every line inside a fence, and the inner
+ * content of inline code spans on prose lines (backticks kept). Fence
+ * marker lines themselves are untouched.
+ *
+ * `transformInlineAttrs` (optional) rewrites the attr group of an
+ * inline span at re-emission — return `""` to drop it. Only inline
+ * spans see it; fence info strings are never routed through it.
+ */
+/**
+ * Line-by-line fence tracker on THE shared grammar — for tools that must
+ * walk a document themselves (the remote-include inliner) instead of
+ * transforming regions. A locally re-implemented open/close regex pair
+ * drifted immediately: it missed the deflist-hosted `:   ```` opener the
+ * shared grammar just gained, took the indented closer for an opener,
+ * and re-created the exact phantom-fence inversion it was fixing
+ * (issue #039 review).
+ *
+ * step(line) returns what the line IS: "fence" (an opener or closer),
+ * "code" (content of an open fence), or "prose". open() reports the
+ * state AFTER the last step, so an opener steps "fence" with
+ * open()===true and its closer steps "fence" with open()===false.
+ */
+export declare function createFenceTracker(): {
+    step(line: string): LineKind;
+    open(): boolean;
+};
+/**
+ * Transform only fence OPENING lines' info strings, on the same shared
+ * grammar — a fence-looking line inside an open fence is code content
+ * and is never touched. Used to strip the spent `{minja}` marker after
+ * the terminal Minja render (a fence marker that survives into the
+ * mirror leaks into serializers that round-trip fence info verbatim —
+ * the Obsidian vault showed literal ```` ```yaml {minja} ````).
+ */
+export declare function transformFenceInfo(source: string, transform: (info: string) => string): string;
+export declare function transformCodeRegions(source: string, transform: (codeText: string, ctx: CodeRegionContext) => string, transformInlineAttrs?: (attrs: string) => string): string;
+/**
+ * The inverse walk: transform PROSE lines (outside fences), leaving
+ * fenced content and the fence lines untouched. Used by refactor
+ * commands that rewrite markdown structure line-wise (heading shifts,
+ * section splits) — a `# heading` inside a code example must never be
+ * treated as structure.
+ */
+export declare function transformProseLines(source: string, transform: (line: string, lineIndex: number) => string): string;
+/**
+ * Transform PROSE TEXT SEGMENTS: prose lines with their inline code
+ * spans protected (the transform sees only the non-code stretches of
+ * each prose line). This is the write-side counterpart of
+ * transformCodeRegions — refactor commands rewrite references through
+ * it so `[x](old.md)` or `{{ key }}` inside examples survive verbatim.
+ */
+export declare function transformProseSegments(source: string, transform: (proseText: string) => string): string;
+/**
+ * Fence state BEFORE each line: `openBefore[i]` is true when line i
+ * starts inside an unclosed fence. One extra trailing entry gives the
+ * state after the last line. Lets line-range refactors check "does
+ * this range start or end mid-fence" with the same grammar.
+ */
+export declare function fenceOpenBefore(source: string): boolean[];
+export {};