@dogsbay/format-dogsbay-md 0.2.0-beta.13 → 0.2.0-beta.130

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,24 @@
+/**
+ * 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 { TemplatePages, TemplatePageError, declaresParams, ATTRIBUTE_BLOCK_OPEN, type TemplatePagesOptions } from "./template-pages.js";

package/dist/browser.js

@@ -0,0 +1,24 @@
+/**
+ * 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 { TemplatePages, TemplatePageError, declaresParams, ATTRIBUTE_BLOCK_OPEN } from "./template-pages.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,20 @@
 import type { FormatPlugin } from "@dogsbay/types";
+/**
+ * The source page's front matter, carried into the Dogsbay MD it becomes.
+ * It used to be DROPPED (only title and redirect were written), so a
+ * converted corpus lost `description`, `tags` and custom fields, and a
+ * query listing (`::child-links{match=…}`) over it found nothing.
+ *
+ * Keys Dogsbay MD gives meaning to keep their value only when the value
+ * MEANS that here; otherwise the key moves under `imported:` — kept, never
+ * misread. Starlight's `template: splash` (a page template) must not turn a
+ * page into a Jinja template page. A Dogsbay MD source round-trips unchanged:
+ * its values are valid by construction.
+ *
+ * `title`, `redirect` and the template keys are written by the caller.
+ * `layout` is free-form (a theme layout name) and passes as it is.
+ * `imported:`, not `source:` — Cloudflare pages carry their own `source:`
+ * (an origin URL, 91 pages), which the moved keys would have overwritten.
+ */
+export declare function carriedFrontmatter(fm: Record<string, unknown> | undefined): Record<string, unknown>;
 export declare const plugin: FormatPlugin;
-//# sourceMappingURL=cli.d.ts.map

package/dist/cli.js

@@ -4,11 +4,15 @@
  * 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 { cpSync, 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 { treeToDogsbayMd } from "./serialize.js";
 import { buildNavFromDirectory } from "./nav.js";
+import { renderDiagrams } from "./renderers/diagrams.js";
+import { DOGSBAY_MD_CAPABILITIES } from "./capabilities.js";
 /**
  * Detect whether a directory contains a Dogsbay MD source tree.
  *
@@ -30,16 +34,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 +125,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 +167,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 +210,150 @@ 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.
+ */
+/** Media files worth carrying into `_assets` from a media-only mount. */
+const MEDIA_EXTS = new Set([
+    ".png", ".jpg", ".jpeg", ".gif", ".webp", ".avif",
+    ".svg", ".ico", ".pdf", ".mp4", ".webm",
+]);
+/** Recursively copy only media files, preserving relative structure. */
+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));
+    }
+}
+/**
+ * The source page's front matter, carried into the Dogsbay MD it becomes.
+ * It used to be DROPPED (only title and redirect were written), so a
+ * converted corpus lost `description`, `tags` and custom fields, and a
+ * query listing (`::child-links{match=…}`) over it found nothing.
+ *
+ * Keys Dogsbay MD gives meaning to keep their value only when the value
+ * MEANS that here; otherwise the key moves under `imported:` — kept, never
+ * misread. Starlight's `template: splash` (a page template) must not turn a
+ * page into a Jinja template page. A Dogsbay MD source round-trips unchanged:
+ * its values are valid by construction.
+ *
+ * `title`, `redirect` and the template keys are written by the caller.
+ * `layout` is free-form (a theme layout name) and passes as it is.
+ * `imported:`, not `source:` — Cloudflare pages carry their own `source:`
+ * (an origin URL, 91 pages), which the moved keys would have overwritten.
+ */
+export function carriedFrontmatter(fm) {
+    if (!fm)
+        return {};
+    const out = {};
+    const source = {};
+    const valid = {
+        // `false` is the documented per-page opt-out of a source's `templates: jinja`.
+        template: (v) => v === "jinja" || v === false,
+        weight: (v) => typeof v === "number" && Number.isFinite(v),
+        order: (v) => typeof v === "number" && Number.isFinite(v),
+        draft: (v) => typeof v === "boolean",
+        status: (v) => typeof v === "string" && ["draft", "preview", "stable", "deprecated"].includes(v),
+        // `params:` declares a template PARTIAL's parameters: only with `template: jinja`.
+        params: (v) => Array.isArray(v) && fm.template === "jinja",
+    };
+    for (const [key, value] of Object.entries(fm)) {
+        if (key === "title" || key === "redirect" || value === undefined)
+            continue;
+        // A source that already has `imported:` keeps it: merged if a mapping,
+        // else nested under its own name.
+        if (key === "imported") {
+            if (value && typeof value === "object" && !Array.isArray(value))
+                Object.assign(source, value);
+            else
+                source.imported = value;
+            continue;
+        }
+        if (valid[key] && !valid[key](value))
+            source[key] = value;
+        else
+            out[key] = value;
+    }
+    if (Object.keys(source).length)
+        out.imported = source;
+    return out;
+}
+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.
+    if (Array.isArray(opts.assetMounts)) {
+        for (const mount of opts.assetMounts) {
+            if (!existsSync(mount.dir))
+                continue;
+            // Per-mount root: `_assets` for an imported corpus, `images`/`assets`
+            // for hand-authored content. A hardcoded root would copy the file
+            // where the reference does not point.
+            const assetsRoot = join(output, mount.root ?? "_assets");
+            const dest = mount.into ? join(assetsRoot, mount.into) : assetsRoot;
+            if (mount.mediaOnly) {
+                copyMediaTree(mount.dir, dest);
+                continue;
+            }
+            const skip = new Set(mount.exclude ?? []);
+            cpSync(mount.dir, dest, {
+                recursive: true,
+                ...(skip.size === 0 ? {} : {
+                    // Relative to the mount, so an exclusion cannot be accidentally
+                    // satisfied by a directory name somewhere above it on disk.
+                    filter: (src) => {
+                        const rel = relative(mount.dir, src);
+                        return rel === "" || !rel.split(/[\\/]/).some((seg) => skip.has(seg));
+                    },
+                }),
+            });
+        }
+    }
+    for (const page of pages) {
+        const slug = page.slug || "index";
+        const outPath = join(output, `${slug}.md`);
+        mkdirSync(dirname(outPath), { recursive: true });
+        // A template partial keeps its `params:` and the template flag, so the
+        // build treats it as a partial and checks every include against it.
+        const templateFm = page.template ? { template: "jinja", ...(page.templateParams ? { params: page.templateParams } : {}) } : {};
+        // A title-less template page still needs `template: jinja`, or the build
+        // renders it in content mode and shows the directives as text.
+        const frontmatter = page.fragment || !page.title
+            ? (page.template ? templateFm : undefined)
+            : { title: page.title, ...carriedFrontmatter(page.frontmatter), ...(page.redirect ? { redirect: page.redirect } : {}), ...templateFm };
+        const md = treeToDogsbayMd(page.tree, frontmatter ? { frontmatter } : undefined);
+        writeFileSync(outPath, md.endsWith("\n") ? md : md + "\n", "utf-8");
+    }
+    // Nav as nav.json at the content root (the dogsbay-md importer + runtime
+    // loader both prefer nav.json). Fragments never appear here.
+    writeFileSync(join(output, "nav.json"), JSON.stringify(nav, null, 2) + "\n", "utf-8");
 }
 export const plugin = {
     name: "dogsbay-md",
     canImport: true,
-    canExport: false,
+    canExport: true,
+    capabilities: DOGSBAY_MD_CAPABILITIES,
     detectSource: detectDogsbayMdSource,
     importOptions: [
         {
@@ -125,5 +364,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