dogsbay 0.2.0-beta.76 → 0.2.0-beta.78

package/dist/commands/convert.js

@@ -5,7 +5,9 @@ import { plugin as astroPlugin } from "@dogsbay/format-astro/cli";
 import { plugin as obsidianPlugin } from "@dogsbay/format-obsidian/cli";
 import { plugin as mdxPlugin } from "@dogsbay/format-mdx/cli";
 import { plugin as starlightPlugin } from "@dogsbay/format-starlight/cli";
+import { plugin as docusaurusPlugin } from "@dogsbay/format-docusaurus/cli";
 import { plugin as dogsbayMdPlugin } from "@dogsbay/format-dogsbay-md/cli";
+import { tigeraAdapter } from "@dogsbay/docusaurus-adapter-tigera";
 // All registered format plugins
 const formats = [
     mkdocsPlugin,
@@ -13,8 +15,14 @@ const formats = [
     obsidianPlugin,
     mdxPlugin,
     starlightPlugin,
+    docusaurusPlugin,
     dogsbayMdPlugin,
 ];
+// Docusaurus site adapters live in their own packages (the generic importer
+// holds none). Resolve `--adapter <name>` here and pass the instance through.
+const docusaurusAdapters = {
+    tigera: tigeraAdapter,
+};
 /**
  * Auto-detect source format by checking each plugin's detectSource.
  */
@@ -77,6 +85,17 @@ export async function convert(source, options) {
         console.log(pc.red(`Error: ${exporter.name} export is not yet implemented.`));
         process.exit(1);
     }
+    // Resolve a Docusaurus site adapter (e.g. tigera) into an adapter object the
+    // generic importer can consume, keeping format-docusaurus free of site code.
+    if (importer.name === "docusaurus" && typeof options.adapter === "string") {
+        const adapter = docusaurusAdapters[options.adapter];
+        if (!adapter) {
+            console.log(pc.red(`Error: Unknown Docusaurus adapter "${options.adapter}"`));
+            console.log(`Available adapters: ${Object.keys(docusaurusAdapters).join(", ")}`);
+            process.exit(1);
+        }
+        options.adapterInstance = adapter;
+    }
     // Run the pipeline: import → export
     // The importer may attach metadata (siteName, repoUrl, etc.) to options
     // for the exporter to consume.

package/dist/commands/migrate-asciidoc.js

@@ -539,6 +539,7 @@ export async function migrateAsciidoc(source, options) {
     const { pages: importedPages, nav } = await asciidocPlugin.import(sourceDir, {
         attributes: engineAttributes,
         loader: options.loader,
+        distro: options.distro,
     });
     if (importedPages.length === 0) {
         console.log(pc.red(`Error: no .adoc files found under ${sourceDir}`));

package/dist/commands/site-build.js

@@ -329,6 +329,12 @@ export async function siteBuild(cwd, options) {
     // generalize this to copy assets per-source.
     const astroOpts = configToAstroOptions(config);
     astroOpts.sourceDir = resolvedSources[0];
+    // Asset mounts surfaced by importers (e.g. a Docusaurus `static/` dir) → copied
+    // into public/_assets by the astro emitter, matching the importer's rewritten
+    // `/_assets/...` refs.
+    if (importResult.assetMounts.length > 0) {
+        astroOpts.assetMounts = importResult.assetMounts;
+    }
     // siteRoot = repo root (where dogsbay.config.yml lives). Used by
     // emitDeployArtifacts to drop GH Actions workflows at
     // <siteRoot>/.github/ rather than inside the Astro subdir, where

package/dist/commands/site-init.js

@@ -523,6 +523,15 @@ function buildConfig(opts) {
         ...(opts.from && opts.from !== "auto"
             ? { from: opts.from }
             : { from: "auto" }),
+        // Docusaurus instance/adapter selection, nested under its format name.
+        ...(opts.from === "docusaurus" && (opts.instance?.trim() || opts.adapter?.trim())
+            ? {
+                docusaurus: {
+                    ...(opts.instance?.trim() ? { instance: opts.instance.trim() } : {}),
+                    ...(opts.adapter?.trim() ? { adapter: opts.adapter.trim() } : {}),
+                },
+            }
+            : {}),
         ...(opts.nav?.trim() ? { nav: opts.nav.trim() } : {}),
     };
     const content = {

package/dist/config/load.js

@@ -356,6 +356,7 @@ const VALID_FROM = [
     "obsidian",
     "starlight",
     "mdx",
+    "docusaurus",
     "openapi",
     "asciidoc",
 ];
@@ -644,6 +645,18 @@ function validateSource(raw, index, sourcePath) {
             throw new Error(`${at}.mkdocs must be an object in ${sourcePath}`);
         }
     }
+    if (s.docusaurus !== undefined) {
+        if (typeof s.docusaurus !== "object" || s.docusaurus === null || Array.isArray(s.docusaurus)) {
+            throw new Error(`${at}.docusaurus must be an object in ${sourcePath}`);
+        }
+        const d = s.docusaurus;
+        if (d.instance !== undefined && typeof d.instance !== "string") {
+            throw new Error(`${at}.docusaurus.instance must be a string in ${sourcePath}`);
+        }
+        if (d.adapter !== undefined && typeof d.adapter !== "string") {
+            throw new Error(`${at}.docusaurus.adapter must be a string in ${sourcePath}`);
+        }
+    }
     if (s.primary !== undefined && typeof s.primary !== "boolean") {
         throw new Error(`${at}.primary must be a boolean in ${sourcePath}; got ${describe(s.primary)}`);
     }
@@ -677,6 +690,7 @@ function validateSource(raw, index, sourcePath) {
         nav: s.nav,
         subdir: s.subdir,
         mkdocs: s.mkdocs,
+        docusaurus: s.docusaurus,
         primary: s.primary,
         attributes,
     };

package/dist/import-content.js

@@ -4,19 +4,27 @@ import { plugin as astroPlugin } from "@dogsbay/format-astro/cli";
 import { plugin as obsidianPlugin } from "@dogsbay/format-obsidian/cli";
 import { plugin as mdxPlugin } from "@dogsbay/format-mdx/cli";
 import { plugin as starlightPlugin } from "@dogsbay/format-starlight/cli";
+import { plugin as docusaurusPlugin } from "@dogsbay/format-docusaurus/cli";
 import { plugin as dogsbayMdPlugin } from "@dogsbay/format-dogsbay-md/cli";
 import { plugin as openApiPlugin } from "@dogsbay/format-openapi/cli";
 import { plugin as asciidocPlugin } from "@dogsbay/format-asciidoc/cli";
+import { tigeraAdapter } from "@dogsbay/docusaurus-adapter-tigera";
 const FORMATS = [
     mkdocsPlugin,
     astroPlugin,
     obsidianPlugin,
     mdxPlugin,
     starlightPlugin,
+    docusaurusPlugin,
     dogsbayMdPlugin,
     openApiPlugin,
     asciidocPlugin,
 ];
+// Docusaurus site adapters live in their own packages (the generic importer
+// holds none). Resolved by name from the source's `docusaurus.adapter`.
+const DOCUSAURUS_ADAPTERS = {
+    tigera: tigeraAdapter,
+};
 /**
  * Effective namespace key for a source. Returns `undefined` when
  * the source has no explicit `name:` — the source's URLs stay
@@ -202,6 +210,7 @@ export async function importContent(resolvedSources, config, options = {}) {
     const basePath = normalizeBasePath(config.site.basePath);
     const allPages = [];
     const allNav = [];
+    const allAssetMounts = [];
     let firstImporter;
     for (let i = 0; i < sources.length; i++) {
         const sourceCfg = sources[i];
@@ -214,6 +223,11 @@ export async function importContent(resolvedSources, config, options = {}) {
             firstImporter = importer;
         const opts = buildImportOptions(config, sourceCfg, options);
         const { pages, nav } = await importer.import(resolved, opts);
+        // Importers may attach asset mounts (e.g. Docusaurus signals its `static/`
+        // dir) for the exporter to copy into `_assets`.
+        if (Array.isArray(opts.assetMounts)) {
+            allAssetMounts.push(...opts.assetMounts);
+        }
         const anyAxisActive = axes.version || axes.namespace || axes.locale;
         const prefixSegs = getPrefixSegments(sourceCfg, axes, defaults);
         // Per-page axis metadata is stamped whenever ANY axis is
@@ -279,7 +293,7 @@ export async function importContent(resolvedSources, config, options = {}) {
             allNav.push(...nav);
         }
     }
-    return { pages: allPages, nav: allNav, importer: firstImporter };
+    return { pages: allPages, nav: allNav, importer: firstImporter, assetMounts: allAssetMounts };
 }
 function prefixSlugWithSegments(prefix, slug) {
     if (prefix.length === 0)
@@ -380,6 +394,18 @@ function buildImportOptions(config, source, extra = {}) {
     if (source.mkdocs?.docusaurusAdmonitions) {
         opts.docusaurusAdmonitions = true;
     }
+    // Docusaurus-specific: instance selection + adapter resolution.
+    if (source.docusaurus?.instance) {
+        opts.instance = source.docusaurus.instance;
+    }
+    if (source.docusaurus?.adapter) {
+        const adapter = DOCUSAURUS_ADAPTERS[source.docusaurus.adapter];
+        if (!adapter) {
+            throw new Error(`Unknown Docusaurus adapter "${source.docusaurus.adapter}". ` +
+                `Available: ${Object.keys(DOCUSAURUS_ADAPTERS).join(", ")}`);
+        }
+        opts.adapterInstance = adapter;
+    }
     // Custom taxonomy names — importers pass these to parseMeta so
     // user-declared taxonomy keys in frontmatter get lifted into
     // meta.taxonomies. See plans/metadata-and-taxonomies.md Step 3.

package/dist/index.js

@@ -67,7 +67,9 @@ site
     .option("--theme <name>", "Theme preset (default | material)")
     .option("--deploy <target>", "Deploy target (cloudflare-workers | github-pages)")
     .option("--content <path>", "Path to source markdown (relative to config)")
-    .option("--from <format>", "Source format (auto | dogsbay-md | mkdocs | obsidian | starlight | mdx)")
+    .option("--from <format>", "Source format (auto | dogsbay-md | mkdocs | obsidian | starlight | mdx | docusaurus)")
+    .option("--instance <id>", "Docusaurus instance id (with --from docusaurus), e.g. calico")
+    .option("--adapter <name>", "Docusaurus site adapter (with --from docusaurus), e.g. tigera")
     .option("--nav <path>", "Path to explicit nav file (.json/.yml)")
     .option("--plausible-domain <domain>", "Plausible analytics domain")
     .option("--plausible-script-url <url>", "Override Plausible script URL")
@@ -225,6 +227,9 @@ program
     "baked into the migrated Dogsbay-MD; unresolved ones survive as " +
     "{{ var }} / {% if %} for a downstream Minja pass.", (val, prev = []) => [...prev, val])
     .option("--loader <name>", "Force a corpus loader (plain, master-adoc). Auto-detected when omitted.")
+    .option("--distro <name>", "AsciiBinder distro filter (e.g. 'openshift-enterprise'). Topic-map " +
+    "entries whose Distros: list excludes this value are dropped from " +
+    "the page set and nav. Entries without Distros: are kept as universal.")
     .option("--local", "Use file: references to local monorepo packages (for development)")
     .option("--quiet", "Suppress the 'Next steps' trailer")
     .action((source, options) => migrateAsciidoc(source, options));
@@ -265,7 +270,9 @@ program
     .option("--plugin <mode>", "Obsidian plugin: bundled (copy into vault), registry (list only), none", "bundled")
     .option("--optimize-images", "Enable Astro image optimization (WebP, width/height, lazy loading)")
     .option("--code-titles <mode>", "Code block title bar: always, auto (only with explicit title), never", "always")
-    .option("--adapter <name>", "Site adapter for custom components (e.g. cloudflare)")
+    .option("--adapter <name>", "Site adapter for custom components (e.g. cloudflare, tigera)")
+    .option("--instance <id>", "Docusaurus plugin-content-docs instance id to import (e.g. calico)")
+    .option("--partial-mode <mode>", "Docusaurus partial handling: inline (splice in) or include (emit {% include %} + fragments; requires --to dogsbay-md)", "inline")
     .option("--section <name>", "Section name — pages go under this subfolder, nav gets a top-level entry")
     .option("--partials-dir <path>", "Directory containing partial MDX files for <Render> resolution")
     .option("--nav <path>", "Path to an explicit nav file (.json/.yml/.yaml). Overrides heuristic auto-detection in the content root.")

package/dist/site-build/preprocess.js

@@ -40,6 +40,61 @@ import { copyFileSync, linkSync, lstatSync, mkdirSync, readFileSync, readdirSync
 import { dirname, join } from "node:path";
 import matter from "gray-matter";
 import { render as minjaRender, FileSystemLoader, } from "@dogsbay/minja";
+/**
+ * Sentinels that mask Minja openers before parsing, restored verbatim after
+ * rendering. Module-scoped so the page renderer AND the fragment loader share
+ * them, and so all masks are undone in one place.
+ *
+ * - HASH: `{#id}` heading anchors (markdown-it-attrs) — masked GLOBALLY, since
+ *   Minja reads `{#` as a comment opener and aborts on the missing `#}`.
+ * - INTERP / BLOCK: `{{ … }}` / `{% … %}` that appear INSIDE code (fenced blocks
+ *   and inline spans) — literal template examples (Go/kubectl/Helm:
+ *   `{{range .Items}}`, `{% … %}`) that must never be evaluated. Masked only in
+ *   code regions; outside code these still process (that's the point).
+ *
+ * This is the single, format-agnostic guard: every importer's output funnels
+ * through this build pass, so code examples are protected regardless of source.
+ */
+const HASH_SENTINEL = " DBMINJA_HASH_OPEN ";
+const INTERP_SENTINEL = " DBMINJA_INTERP_OPEN ";
+const BLOCK_SENTINEL = " DBMINJA_BLOCK_OPEN ";
+/** Mask `{{`/`{%` openers inside fenced code blocks and inline code spans. */
+function maskCodeRegions(text) {
+    const maskOpeners = (s) => s.replace(/\{\{/g, INTERP_SENTINEL).replace(/\{%/g, BLOCK_SENTINEL);
+    const lines = text.split("\n");
+    let inFence = false;
+    let fenceMarker = "";
+    return lines
+        .map((line) => {
+        const fence = line.match(/^\s*(```+|~~~+)/);
+        if (fence) {
+            const marker = fence[1][0];
+            if (!inFence) {
+                inFence = true;
+                fenceMarker = marker;
+            }
+            else if (marker === fenceMarker) {
+                inFence = false;
+            }
+            return line; // the fence line itself (info string) — leave as-is
+        }
+        if (inFence)
+            return maskOpeners(line);
+        // Outside a fence: mask only within inline code spans (balanced backticks).
+        return line.replace(/(`+)([^`]*?)\1/g, (_m, ticks, inner) => ticks + maskOpeners(inner) + ticks);
+    })
+        .join("\n");
+}
+/** Restore every Minja-opener sentinel. */
+function unmaskMinja(text) {
+    return text
+        .split(HASH_SENTINEL)
+        .join("#")
+        .split(INTERP_SENTINEL)
+        .join("{{")
+        .split(BLOCK_SENTINEL)
+        .join("{%");
+}
 /**
  * Merge the three attribute layers into the effective per-source
  * context. Right-hand wins for duplicate keys (per-source overrides
@@ -102,7 +157,13 @@ class FragmentStrippingLoader {
     inner = new FileSystemLoader();
     async load(path, basePath) {
         const raw = await this.inner.load(path, basePath);
-        return path.toLowerCase().endsWith(".md") ? stripFrontmatter(raw) : raw;
+        if (!path.toLowerCase().endsWith(".md"))
+            return raw;
+        // Apply the same masks to included fragments — code-region `{{`/`{%` and
+        // `{#id}` heading anchors — so Minja doesn't evaluate template examples or
+        // read anchors as comment openers and abort the include. All sentinels are
+        // restored together with the parent's after rendering (unmaskMinja).
+        return maskCodeRegions(stripFrontmatter(raw)).replace(/\{#/g, `{${HASH_SENTINEL}`);
     }
 }
 /**
@@ -165,8 +226,8 @@ async function renderMdToMirror(sourcePath, mirrorPath, attrs, result) {
     // when it doesn't find a `#}`. Mask the opener before parse, restore
     // after. Side effect: genuine Minja `{# comment #}` blocks pass
     // through as literal text (rare in our pipeline).
-    const SENTINEL = " DBMINJA_HASH_OPEN ";
-    const masked = raw.replace(/\{#/g, `{${SENTINEL}`);
+    // Protect literal template syntax in code examples, then mask heading anchors.
+    const masked = maskCodeRegions(raw).replace(/\{#/g, `{${HASH_SENTINEL}`);
     let resolved;
     try {
         const rendered = await minjaRender(masked, {
@@ -183,7 +244,7 @@ async function renderMdToMirror(sourcePath, mirrorPath, attrs, result) {
             basePath: dirname(sourcePath),
             loader: new FragmentStrippingLoader(),
         });
-        resolved = rendered.split(SENTINEL).join("#");
+        resolved = unmaskMinja(rendered);
     }
     catch (err) {
         const msg = err instanceof Error ? err.message : String(err);

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "dogsbay",
-  "version": "0.2.0-beta.76",
+  "version": "0.2.0-beta.78",
   "description": "CLI for Dogsbay — scaffold, build, and serve documentation sites with markdown / MkDocs / Obsidian / OpenAPI sources",
   "type": "module",
   "bin": {
@@ -33,18 +33,20 @@
     "picocolors": "^1.1.0",
     "prompts": "^2.4.2",
     "yaml": "^2.8.3",
-    "@dogsbay/autodoc-python": "0.2.0-beta.76",
-    "@dogsbay/format-mkdocs": "0.2.0-beta.76",
-    "@dogsbay/format-astro": "0.2.0-beta.76",
-    "@dogsbay/format-mdx": "0.2.0-beta.76",
-    "@dogsbay/format-obsidian": "0.2.0-beta.76",
-    "@dogsbay/format-starlight": "0.2.0-beta.76",
-    "@dogsbay/format-dogsbay-md": "0.2.0-beta.76",
-    "@dogsbay/format-openapi": "0.2.0-beta.76",
-    "@dogsbay/adoc2md-modular": "0.2.0-beta.76",
-    "@dogsbay/format-asciidoc": "0.2.0-beta.76",
-    "@dogsbay/minja": "0.2.0-beta.76",
-    "@dogsbay/types": "0.2.0-beta.76"
+    "@dogsbay/autodoc-python": "0.2.0-beta.78",
+    "@dogsbay/format-mkdocs": "0.2.0-beta.78",
+    "@dogsbay/format-astro": "0.2.0-beta.78",
+    "@dogsbay/format-obsidian": "0.2.0-beta.78",
+    "@dogsbay/format-starlight": "0.2.0-beta.78",
+    "@dogsbay/format-mdx": "0.2.0-beta.78",
+    "@dogsbay/format-docusaurus": "0.2.0-beta.78",
+    "@dogsbay/docusaurus-adapter-tigera": "0.2.0-beta.78",
+    "@dogsbay/format-dogsbay-md": "0.2.0-beta.78",
+    "@dogsbay/format-openapi": "0.2.0-beta.78",
+    "@dogsbay/adoc2md-modular": "0.2.0-beta.78",
+    "@dogsbay/format-asciidoc": "0.2.0-beta.78",
+    "@dogsbay/minja": "0.2.0-beta.78",
+    "@dogsbay/types": "0.2.0-beta.78"
   },
   "devDependencies": {
     "@types/markdown-it": "^14.1.0",