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

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,10 +1,14 @@
-import { existsSync } from "node:fs";
-import { join } from "node:path";
+import { cpSync, existsSync, lstatSync, mkdirSync, readdirSync, writeFileSync, copyFileSync } from "node:fs";
+import { dirname, extname, join } from "node:path";
 import { importMkdocsProject } from "./importer.js";
+import { exportMkdocsProject } from "./export/to-mkdocs-project.js";
+import { formatLedgerReport } from "@dogsbay/serialize-core";
+import { MKDOCS_CAPABILITIES } from "./export/capabilities.js";
 export const plugin = {
     name: "mkdocs",
     canImport: true,
     canExport: true,
+    capabilities: MKDOCS_CAPABILITIES,
     detectSource: (path) => existsSync(join(path, "mkdocs.yml")),
     importOptions: [
         { flags: "--theme <name>", description: "Theme preset (default, material)", default: "default" },
@@ -12,7 +16,15 @@ export const plugin = {
         { flags: "--custom-css <files>", description: "Custom CSS files to copy (comma-separated)" },
         { flags: "--docusaurus-admonitions", description: "Enable Docusaurus-style ::: admonitions" },
     ],
-    exportOptions: [],
+    // NOT `--theme`: `dogsbay convert` already owns that flag for the Astro
+    // preset, with a default of "default" — which reached this exporter as
+    // `theme: name: default`, a theme MkDocs does not have, and every
+    // `convert --to mkdocs` project failed its first `mkdocs build`.
+    exportOptions: [
+        { flags: "--mkdocs-theme <name>", description: "MkDocs theme for the emitted mkdocs.yml (material | mkdocs | readthedocs)", default: "material" },
+        { flags: "--site-url <url>", description: "site_url for the emitted mkdocs.yml" },
+        { flags: "--repo-url <url>", description: "repo_url for the emitted mkdocs.yml" },
+    ],
     async import(source, opts) {
         const { pages, nav, config } = await importMkdocsProject(source, opts);
         // Attach config metadata for the exporter to consume
@@ -26,7 +38,105 @@ export const plugin = {
         if (extraCss && Array.isArray(extraCss)) {
             opts.extraCss = extraCss;
         }
-        return { pages, nav };
+        // Slugs are relative to `docs_dir`, not to the project root — so an
+        // `{% include %}` in a page means a file under THERE.
+        return { pages, nav, contentRoot: join(source, config.docsDir) };
+    },
+    /**
+     * Export: TreeNode pages + nav → a complete MkDocs project.
+     *
+     * `exportMkdocsProject` is I/O-free and returns a path → content map, so
+     * everything this method does is create directories and write bytes. It was
+     * written and unit-tested long before it was reachable: `cli.ts` declared
+     * `canExport: true` with no `export` method, and `resolveExporter()` filters
+     * on `canExport && f.export`, so `--to mkdocs` reported an unknown target
+     * while the serializer sat in the same package. That predicate exists
+     * BECAUSE of this plugin.
+     */
+    async export(pages, nav, output, opts) {
+        const result = exportMkdocsProject(pages, nav, {
+            siteName: opts.siteName ?? "Documentation",
+            siteUrl: opts.siteUrl,
+            repoUrl: opts.repoUrl,
+            copyright: opts.copyright,
+            poweredBy: opts.poweredBy,
+            theme: mkdocsTheme(opts),
+        });
+        for (const [filePath, content] of result.files) {
+            const fullPath = join(output, filePath);
+            mkdirSync(dirname(fullPath), { recursive: true });
+            writeFileSync(fullPath, content);
+        }
+        console.log(`Generated ${result.files.size} MkDocs files`);
+        // Mounted asset dirs, copied under docs/ at the ROOT their refs were
+        // rewritten to (`_assets` for an imported corpus, `images`/`assets` for
+        // hand-authored content). The serializer emits those refs relative to
+        // each page, so the file has to land exactly there or every image 404s
+        // with a clean exit code.
+        const mounts = opts.assetMounts;
+        for (const mount of mounts ?? []) {
+            if (!existsSync(mount.dir))
+                continue;
+            const root = mount.root ?? "_assets";
+            const dest = mount.into ? join(output, "docs", root, mount.into) : join(output, "docs", root);
+            mkdirSync(dest, { recursive: true });
+            if (mount.mediaOnly) {
+                copyMediaTree(mount.dir, dest);
+                continue;
+            }
+            // Skip symlinks rather than copy them: relative links are rewritten to
+            // ABSOLUTE paths into the source checkout, so the output only works on
+            // the machine that produced it. AsciiBinder corpora are full of them.
+            cpSync(mount.dir, dest, {
+                recursive: true,
+                dereference: false,
+                filter: (src) => !lstatSync(src).isSymbolicLink(),
+            });
+        }
+        // Co-located media next to the markdown (the mkdocs shape itself).
+        const sourceDir = opts.sourceDir;
+        if (sourceDir && existsSync(sourceDir))
+            copyMediaTree(sourceDir, join(output, "docs"));
+        if (!result.ledger.isEmpty) {
+            console.log(formatLedgerReport(result.ledger, "mkdocs"));
+        }
     },
 };
-//# sourceMappingURL=cli.js.map
+const MEDIA_EXT = new Set([".png", ".jpg", ".jpeg", ".gif", ".svg", ".webp", ".avif", ".mp4", ".webm", ".pdf", ".ico"]);
+/**
+ * Copy media files only, preserving the directory shape. Never follows a
+ * symlink: AsciiBinder corpora symlink every section back to one images
+ * tree, and following them copied a 64 MB tree once per link.
+ */
+function copyMediaTree(from, to) {
+    for (const entry of readdirSync(from, { withFileTypes: true })) {
+        if (entry.isSymbolicLink())
+            continue;
+        const src = join(from, entry.name);
+        if (entry.isDirectory()) {
+            if (entry.name === "node_modules" || entry.name.startsWith("."))
+                continue;
+            copyMediaTree(src, join(to, entry.name));
+            continue;
+        }
+        if (!MEDIA_EXT.has(extname(entry.name).toLowerCase()))
+            continue;
+        // Always copy. A same-size skip saved nothing measurable and silently
+        // kept a stale file when a one-character SVG edit left the size unchanged.
+        mkdirSync(to, { recursive: true });
+        copyFileSync(src, join(to, entry.name));
+    }
+}
+const MKDOCS_THEMES = new Set(["material", "mkdocs", "readthedocs"]);
+/**
+ * The MkDocs theme to write. `--mkdocs-theme` wins; a bare `theme` is honoured
+ * only when it names a theme MkDocs actually has, so the Astro preset default
+ * ("default") that `convert` passes through can never reach mkdocs.yml.
+ */
+function mkdocsTheme(opts) {
+    for (const candidate of [opts.mkdocsTheme, opts.theme]) {
+        if (typeof candidate === "string" && MKDOCS_THEMES.has(candidate))
+            return candidate;
+    }
+    return "material";
+}

package/dist/export/capabilities.d.ts

@@ -0,0 +1,22 @@
+/**
+ * What the MkDocs (Material + PyMdown) exporter can and cannot represent.
+ *
+ * This is a CONTRACT, not commentary: `validateCapabilities` rejects any
+ * non-full entry without a note, and `tests/capabilities.test.ts` asserts every
+ * row of the component × format matrix (`MATRIX_ROWS` in
+ * @dogsbay/serialize-core) is declared exactly once. Each cell was set by
+ * reading `to-mkdocs.ts` / `to-mkdocs-project.ts` AND running the serializer
+ * on real parsed dogsbay-md, not from the extension list.
+ *
+ * Support levels:
+ *   full    — round-trips faithfully (given the extensions the project
+ *             emitter enables in mkdocs.yml)
+ *   partial — survives with reduced fidelity (styling/semantics lost)
+ *   none    — no MkDocs construct; the wrapper is dropped and the content
+ *             flattened into plain blocks (recorded as the node type)
+ *
+ * A `partial` here is not necessarily recorded per page — several are known
+ * structural limits the serializer does not ledger (noted where so).
+ */
+import type { CapabilityDeclaration } from "@dogsbay/serialize-core";
+export declare const MKDOCS_CAPABILITIES: CapabilityDeclaration[];

package/dist/export/capabilities.js

@@ -0,0 +1,213 @@
+export const MKDOCS_CAPABILITIES = [
+    // ── Blocks ──────────────────────────────────────────────
+    {
+        feature: "heading",
+        support: "partial",
+        rendersAs: "`#`–`######` with the authored id as `{ #id }` (attr_list)",
+        note: "The id survives; heading classes (`{.cls}`) are dropped, unrecorded.",
+    },
+    { feature: "paragraph", support: "full" },
+    { feature: "blockquote", support: "full", rendersAs: "`> …`" },
+    { feature: "unordered-list", support: "full", rendersAs: "`- item`, four-space continuation; task items via pymdownx.tasklist" },
+    { feature: "ordered-list", support: "full", rendersAs: "`1. item` (start number kept)" },
+    { feature: "hr", support: "full", rendersAs: "`---`" },
+    {
+        feature: "table",
+        support: "partial",
+        rendersAs: "GFM pipe table; `<table markdown>` with `markdown=\"block\"` cells when a cell holds block content or spans",
+        note: "The table's caption, id and classes are dropped, unrecorded.",
+    },
+    {
+        feature: "code",
+        support: "partial",
+        rendersAs: "fence with language, `title=\"…\"` and `hl_lines` (pymdownx.highlight + superfences)",
+        note: "Code annotations are not recreated: the `(N)!` markers come back as literal `(N)` in the code (no `.annotate` class, no `content.code.annotate` feature), unrecorded.",
+    },
+    {
+        feature: "math-block",
+        support: "partial",
+        rendersAs: "`$$ … $$` (pymdownx.arithmatex, generic)",
+        note: "The LaTeX survives, but arithmatex `generic` needs MathJax/KaTeX in `extra_javascript` and the emitted mkdocs.yml adds none, so it is not typeset until one is added.",
+    },
+    { feature: "deflist", support: "full", rendersAs: "`Term` / `:   definition` (def_list)" },
+    { feature: "figure", support: "full", rendersAs: "`<figure markdown>` + `<figcaption>` (md_in_html); the bare image when there is no caption" },
+    { feature: "footnote-list", support: "full", rendersAs: "`[^label]: …` (footnotes)" },
+    { feature: "html", support: "full", rendersAs: "raw HTML passed through, site-rooted asset paths made relative" },
+    { feature: "html-container", support: "full", rendersAs: "`<tag attrs markdown>` (md_in_html); `on*` attributes stripped" },
+    {
+        feature: "diagram",
+        support: "partial",
+        rendersAs: "```mermaid fence (superfences custom fence → Material's Mermaid)",
+        note: "Only Mermaid is rendered. Any other diagram language (plantuml, d2, …) is emitted as a fence no configured extension renders, so it shows as source code — unrecorded.",
+    },
+    { feature: "youtube", support: "full", rendersAs: "`<iframe>` on youtube-nocookie.com" },
+    // ── Components ──────────────────────────────────────────
+    {
+        feature: "callout",
+        support: "partial",
+        rendersAs: "`!!! type \"title\"` (admonition)",
+        note: "Variants Material lacks map to the nearest (`caution`/`important` → warning, keeping the word as the title); a custom per-callout icon is dropped, unrecorded.",
+    },
+    { feature: "details", support: "full", rendersAs: "`??? type \"title\"` / `???+` when open (pymdownx.details)" },
+    { feature: "details-sheet", support: "partial", rendersAs: "a normal collapsible block", note: "MkDocs Material 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: "MkDocs Material 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: "MkDocs Material draws one tab style: a pills or underline variant shows as the default." },
+    { feature: "tone", support: "partial", rendersAs: "untinted cards", note: "MkDocs Material cards take no tone: the colour is lost, the content kept." },
+    { feature: "tabs", support: "full", rendersAs: "`=== \"Label\"` (pymdownx.tabbed, alternate_style)" },
+    {
+        feature: "steps",
+        support: "partial",
+        rendersAs: "ordered list with bold step titles",
+        note: "MkDocs has no steps component; recorded as `steps` degraded.",
+    },
+    {
+        feature: "accordion",
+        support: "partial",
+        rendersAs: "one `??? note \"Label\"` fold per item (pymdownx.details)",
+        note: "Material 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: "`<div class=\"grid cards\" markdown>` list (Material grid cards)",
+        note: "A column count is dropped — Material's grid is responsive. Unrecorded.",
+    },
+    {
+        feature: "card",
+        support: "partial",
+        rendersAs: "grid-card list item: bold title, body, `[:octicons-arrow-right-24: Title](href)`",
+        note: "The card's icon is dropped (unrecorded); an href becomes a trailing link rather than a clickable card.",
+    },
+    {
+        feature: "link-card",
+        support: "partial",
+        rendersAs: "bold title, description, trailing arrow link (a grid card when inside `cards`)",
+        note: "No link-card component; outside a card grid it is plain blocks. Unrecorded.",
+    },
+    {
+        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: "`<div class=\"grid cards\" markdown>` list",
+        note: "Rendered with CARD styling (not Material's plain `grid`); the column count is dropped and each `grid-item` wrapper is recorded as `grid-item`.",
+    },
+    {
+        feature: "link-button",
+        support: "partial",
+        rendersAs: "`[label](href){ .md-button .md-button--primary }`",
+        note: "Always the primary style — a variant is dropped. An unsafe href is dropped and recorded.",
+    },
+    {
+        feature: "related",
+        support: "partial",
+        rendersAs: "bold label + the link list",
+        note: "No related-links component: the semantic block becomes plain markdown.",
+    },
+    {
+        feature: "example",
+        support: "partial",
+        rendersAs: "the rendered children as plain blocks",
+        note: "No MkDocs example container: the wrapper is dropped (recorded) and the example's source listing (`props.source`) is lost; the preview content is kept.",
+    },
+    {
+        feature: "container",
+        support: "partial",
+        rendersAs: "the children as plain blocks",
+        note: "No MkDocs equivalent: the wrapper, its name and classes are dropped (recorded); the content is kept.",
+    },
+    {
+        feature: "annotation-list",
+        support: "partial",
+        rendersAs: "a plain ordered list after the code block",
+        note: "Material code annotations are not recreated (see `code`): the list renders as an ordinary numbered list. Unrecorded.",
+    },
+    // ── API reference ───────────────────────────────────────
+    {
+        feature: "endpoint",
+        support: "none",
+        rendersAs: "children only, or `<!-- unsupported: endpoint -->`",
+        note: "No case: method, path and summary are lost; any children are kept as plain blocks. Recorded as `endpoint` (action `degraded`, even when nothing survives).",
+    },
+    {
+        feature: "api-doc",
+        support: "partial",
+        rendersAs: "the docstring HTML converted to inline markdown",
+        note: "`props.html` is FLATTENED to one line: paragraphs, lists and code blocks run together with no separators (`<p>A.</p><ul><li>one</li>` → `A.one`). Unrecorded. Children-only api-docs are fine.",
+    },
+    {
+        feature: "api-class",
+        support: "partial",
+        rendersAs: "`### kind \\`name\\``, `Bases:` line, signature as a python fence",
+        note: "Plain headings and code, not mkdocstrings' object markup; the signature is always labelled python.",
+    },
+    {
+        feature: "api-member",
+        support: "partial",
+        rendersAs: "`#### kind \\`name\\``, signature as a python fence",
+        note: "As api-class.",
+    },
+    {
+        feature: "api-params",
+        support: "partial",
+        rendersAs: "raw HTML PARAMETER/DESCRIPTION table (mkdocstrings' layout)",
+        note: "Raw HTML without mkdocstrings' classes, so Material styles it as a plain table.",
+    },
+    {
+        feature: "api-source",
+        support: "partial",
+        rendersAs: "`*Source: file:line*` + a python fence",
+        note: "Not a collapsible source block; the code is always labelled python.",
+    },
+    // ── Inline ──────────────────────────────────────────────
+    {
+        feature: "link",
+        support: "partial",
+        rendersAs: "`[text](href \"title\"){ attrs }`; exported pages as relative `.md` links",
+        note: "An inline `:button[…]` link loses its button styling (no `.md-button`), unrecorded. An unsafe href is dropped (text kept) and recorded.",
+    },
+    {
+        feature: "image",
+        support: "full",
+        rendersAs: "`![alt](src \"title\"){ width height }` with a page-relative path (an unsafe src is refused, alt kept, and recorded)",
+    },
+    { feature: "kbd", support: "full", rendersAs: "`++ctrl+s++` (pymdownx.keys); a non-name key as a quoted key" },
+    {
+        feature: "math",
+        support: "partial",
+        rendersAs: "`$…$` (pymdownx.arithmatex, generic)",
+        note: "As math-block: not typeset until MathJax/KaTeX is added to `extra_javascript`.",
+    },
+    { feature: "highlight", support: "full", rendersAs: "`==text==` (pymdownx.mark)" },
+    {
+        feature: "badge",
+        support: "partial",
+        rendersAs: "plain text",
+        note: "No badge construct: the label is kept, the variant dropped. Recorded as `badge` degraded.",
+    },
+    {
+        feature: "icon",
+        support: "partial",
+        rendersAs: "`:name:` (pymdownx.emoji, Material/octicons/fontawesome/simple icon sets)",
+        note: "The library prefix is dropped (`lucide:check` → `:check:`); a name outside the Material emoji index renders as literal `:name:` text. Unrecorded.",
+    },
+    { feature: "footnote-ref", support: "full", rendersAs: "`[^label]` (footnotes)" },
+    { feature: "html-inline", support: "full", rendersAs: "raw inline HTML passed through" },
+    // ── Named concerns the exporter already records ─────────
+    {
+        feature: "include",
+        support: "partial",
+        rendersAs: "`--8<-- \"path\"` (pymdownx.snippets)",
+        note: "Includes are realized before export; one that arrives unresolved is emitted as a snippet reference and recorded.",
+    },
+    {
+        feature: "nav-entry",
+        support: "partial",
+        rendersAs: "mkdocs.yml `nav:` entry",
+        note: "A nav entry pointing at a page not in the export (or a section with no exported pages) is dropped and recorded.",
+    },
+];

package/dist/export/to-astro.d.ts

@@ -23,4 +23,3 @@ export declare function escapeAttr(s: string): string;
 /** Escape text for use directly in an Astro template (not inside an expression). */
 export declare function escapeTemplate(s: string): string;
 export declare function treeToAstro(nodes: TreeNode[], options?: AstroGenOptions): AstroGenResult;
-//# sourceMappingURL=to-astro.d.ts.map

package/dist/export/to-astro.js

@@ -57,7 +57,12 @@ export function escapeExpr(s) {
     // JSON.stringify handles all special characters (quotes, backslashes, newlines, etc.)
     // and produces a valid JS string literal. This avoids template literal edge cases
     // where backtick + brace combinations create false expression boundaries.
-    return JSON.stringify(s);
+    //
+    // `<` becomes \u003c: Astro parses the template as HTML before the expression is
+    // JavaScript, so a `<script>` inside a string (a code block showing one, say) would
+    // be taken for a real script tag and its text compiled as JavaScript. Vite's
+    // dependency scan then fails to parse it and a production build breaks.
+    return JSON.stringify(s).replace(/</g, "\\u003c");
 }
 /** Escape for use in an HTML attribute value (double-quoted). */
 export function escapeAttr(s) {
@@ -244,6 +249,8 @@ function inlineNodeToTemplate(node) {
             return `<sup><a href="#fn-${escapeAttr(node.label)}" id="fnref-${escapeAttr(node.label)}" class="text-primary hover:underline">[${escapeTemplate(node.label)}]</a></sup>`;
         case "kbd":
             return node.keys.map((k) => `<kbd>${escapeTemplate(k)}</kbd>`).join("+");
+        case "badge":
+            return `<span data-badge data-variant="${escapeAttr(node.variant ?? "default")}">${escapeTemplate(node.text)}</span>`;
         case "math":
             return `<code class="math-inline">${escapeTemplate(node.latex)}</code>`;
         case "icon":
@@ -285,6 +292,8 @@ function inlineNodeToHtml(node) {
             return `<sup><a href="#fn-${escapeAttr(node.label)}" id="fnref-${escapeAttr(node.label)}" class="text-primary hover:underline">[${escapeHtml(node.label)}]</a></sup>`;
         case "kbd":
             return node.keys.map((k) => `<kbd>${escapeHtml(k)}</kbd>`).join("+");
+        case "badge":
+            return `<span data-badge data-variant="${escapeAttr(node.variant ?? "default")}">${escapeHtml(node.text)}</span>`;
         case "math":
             return `<code class="math-inline">${escapeHtml(node.latex)}</code>`;
         case "icon":
@@ -548,4 +557,3 @@ function indentStr(text, spaces) {
 function escapeHtml(s) {
     return s.replace(/&/g, "&amp;").replace(/</g, "&lt;").replace(/>/g, "&gt;");
 }
-//# sourceMappingURL=to-astro.js.map

package/dist/export/to-mkdocs-project.d.ts

@@ -1,4 +1,5 @@
 import type { ExportPage, NavItem } from "@dogsbay/types";
+import { ExportLedger } from "@dogsbay/serialize-core";
 /**
  * Options for project export.
  */
@@ -10,6 +11,15 @@ export interface MkdocsProjectOptions {
     extraExtensions?: string[];
     /** Theme name (default: "material") */
     theme?: string;
+    /** Existing footer copyright, if the site declares one. */
+    copyright?: string;
+    /**
+     * Append "Powered by DogsBay" to the footer. Default ON; `poweredBy: false`
+     * in dogsbay.config.yml removes it. MkDocs has no attribution slot, so it
+     * rides along in `copyright:` — the one string Material renders in the
+     * footer. See docs/powered-by.md.
+     */
+    poweredBy?: boolean;
 }
 /**
  * Result of a project export.
@@ -18,10 +28,11 @@ export interface MkdocsProjectOptions {
 export interface MkdocsProjectExport {
     files: Map<string, string>;
     mkdocsYml: string;
+    /** What could not be represented, per page. Empty is the goal, not the assumption. */
+    ledger: ExportLedger;
 }
 /**
  * Export a set of pages + navigation to a complete MkDocs project.
  * Returns file map (path → content) including mkdocs.yml and all .md files.
  */
 export declare function exportMkdocsProject(pages: ExportPage[], nav: NavItem[], options: MkdocsProjectOptions): MkdocsProjectExport;
-//# sourceMappingURL=to-mkdocs-project.d.ts.map