dogsbay 0.2.0-beta.52 → 0.2.0-beta.53

package/dist/commands/migrate-asciidoc.js

@@ -25,7 +25,7 @@
  *     astro/                  ← scaffolded by emitSiteScaffold
  *     MIGRATION.md            ← what survived + re-run command
  */
-import { copyFileSync, existsSync, lstatSync, mkdirSync, readFileSync, readdirSync, readlinkSync, statSync, symlinkSync, writeFileSync, } from "node:fs";
+import { copyFileSync, cpSync, existsSync, lstatSync, mkdirSync, readFileSync, readdirSync, readlinkSync, rmSync, statSync, symlinkSync, writeFileSync, } from "node:fs";
 import { basename, dirname, join, relative, resolve } from "node:path";
 import pc from "picocolors";
 import { emitSiteScaffold } from "@dogsbay/format-astro";
@@ -207,7 +207,7 @@ function mirrorSourceFs(sourceRoot, outputContentDir, scopedRootDirs) {
  *
  * Returns counts for the summary.
  */
-function convertFragmentAdocs(sourceRoot, outputContentDir, scopedRootDirs) {
+function convertFragmentAdocs(sourceRoot, outputContentDir, scopedRootDirs, pageWrittenPaths, imagesdir) {
     let converted = 0;
     let failed = 0;
     let skipped = 0;
@@ -245,11 +245,14 @@ function convertFragmentAdocs(sourceRoot, outputContentDir, scopedRootDirs) {
                 continue;
             const mdName = name.replace(/\.adoc$/i, ".md");
             const mdPath = join(dstDir, mdName);
-            // A topic page already wrote this destination — don't
-            // overwrite with the engine-only fragment output (the page
-            // version has frontmatter, headings, and went through
-            // markdown-it + serialize for canonical Dogsbay-MD shape).
-            if (existsSync(mdPath)) {
+            // A topic page wrote this destination THIS run — don't overwrite
+            // it with the engine-only fragment output (the page version has
+            // frontmatter, headings, and went through markdown-it + serialize
+            // for canonical Dogsbay-MD shape). We check the known set of
+            // this-run page writes, NOT existsSync: a stale .md left by a
+            // prior --force run must be re-converted, not mistaken for a page
+            // and skipped (#364).
+            if (pageWrittenPaths.has(mdPath)) {
                 skipped += 1;
                 continue;
             }
@@ -263,6 +266,10 @@ function convertFragmentAdocs(sourceRoot, outputContentDir, scopedRootDirs) {
                     basePath: srcPath,
                     dlistFormat: "pandoc",
                     admonitionFormat: "docusaurus",
+                    // imagesdir = "/_assets/<dir>" makes the engine emit image
+                    // srcs already content-rooted (/_assets/images/foo.png), so
+                    // they resolve regardless of fragment depth. See #363.
+                    attributes: imagesdir ? { imagesdir } : undefined,
                 });
                 mkdirSync(dstDir, { recursive: true });
                 // No frontmatter — fragments are pure content. An earlier
@@ -459,6 +466,22 @@ export async function migrateAsciidoc(source, options) {
         process.exit(1);
     }
     const attributes = parseAttributePairs(options.attribute);
+    // Image handling (#363). AsciiDoc keeps images in an `:imagesdir:`
+    // (OpenShift / AsciiBinder / Antora convention: a top-level `images/`
+    // dir). The engine's image() prepends imagesdir to every src, so
+    // supplying `imagesdir = "/_assets/<dir>"` makes refs emit
+    // already-rooted (`/_assets/images/foo.png`) — matching the Dogsbay
+    // `_assets` convention (docs/images.md). We copy the dir into
+    // content/_assets/<dir>/ below. Detected, NOT persisted to config
+    // (a migrate-time rendering concern, not a content attribute).
+    const srcImagesDir = existsSync(join(sourceDir, "images")) &&
+        statSync(join(sourceDir, "images")).isDirectory()
+        ? "images"
+        : undefined;
+    const engineImagesdir = srcImagesDir ? `/_assets/${srcImagesDir}` : undefined;
+    const engineAttributes = engineImagesdir
+        ? { ...attributes, imagesdir: engineImagesdir }
+        : attributes;
     console.log();
     console.log(pc.bold(`Migrating AsciiDoc corpus to Dogsbay-MD: ${siteName}`));
     console.log(`Source:  ${sourceDir}`);
@@ -467,6 +490,19 @@ export async function migrateAsciidoc(source, options) {
     // 1. Output skeleton.
     const contentDir = join(outputDir, "content");
     const astroDir = join(outputDir, "astro");
+    // Clean slate for the regenerated content tree (#364). We only reach
+    // here on a fresh output or with --force (the existing-site guard
+    // above already exited otherwise), so a pre-existing content/ is a
+    // prior migration's output. Clear it so stale files don't linger
+    // across re-migrations — renamed/removed dirs (e.g. content/images/
+    // after #363 moved images to _assets) and orphaned pages. content/ is
+    // entirely migration-generated; --force is a clean re-import and
+    // discards any hand edits under content/ (see the --force help text).
+    // astro/ is left intact: emitSiteScaffold overwrites its files in
+    // place, and clearing it would drop a warm node_modules.
+    if (existsSync(contentDir)) {
+        rmSync(contentDir, { recursive: true, force: true });
+    }
     mkdirSync(contentDir, { recursive: true });
     mkdirSync(astroDir, { recursive: true });
     // 2. Import via the format-asciidoc plugin. Phase 9a moved corpus
@@ -478,7 +514,7 @@ export async function migrateAsciidoc(source, options) {
         throw new Error("format-asciidoc plugin has no import function");
     }
     const { pages: importedPages, nav } = await asciidocPlugin.import(sourceDir, {
-        attributes,
+        attributes: engineAttributes,
         loader: options.loader,
     });
     if (importedPages.length === 0) {
@@ -503,12 +539,19 @@ export async function migrateAsciidoc(source, options) {
     // Fall back to treeToDogsbayMd for importers that don't produce
     // bodyMarkdown (e.g. mkdocs imports during a future
     // dual-format migration). No behaviour change for those.
+    // Track the .md paths the page step wrote THIS run. The fragment
+    // converter skips these so it can't clobber a topic page with its
+    // headerless engine-only output. Using a known set (not existsSync)
+    // means a stale .md left over from a prior --force run is NOT mistaken
+    // for a this-run page — it gets re-converted. See #364.
+    const pageWrittenPaths = new Set();
     for (const page of importedPages) {
         const body = page.bodyMarkdown ?? treeToDogsbayMd(page.tree);
         const dst = join(contentDir, `${page.slug}.md`);
         mkdirSync(dirname(dst), { recursive: true });
         const frontmatter = `---\ntitle: ${yamlQuote(page.title)}\n---\n\n`;
         writeFileSync(dst, frontmatter + body);
+        pageWrittenPaths.add(dst);
     }
     console.log(pc.green(`Converted`) + ` ${importedPages.length} page(s) to ./content/`);
     // 3b. Compute the scoped set of root-level dirs we'll walk for
@@ -531,7 +574,11 @@ export async function migrateAsciidoc(source, options) {
     // skips routes for them via the generated config's
     // excludeFromRoutes. Adding them to scope just lets the walkers
     // descend; the route skip happens separately.
-    for (const d of ["_attributes", "modules", "snippets", "includes", "images"]) {
+    // Note: the imagesdir (`images`) is intentionally NOT here — it's
+    // copied to content/_assets/<dir>/ below and referenced as
+    // /_assets/<dir>/... (#363), so the generic mirror must not also
+    // copy it to content/images/ (dead weight; refs don't point there).
+    for (const d of ["_attributes", "modules", "snippets", "includes"]) {
         scopedRootDirs.add(d);
     }
     // 3c. Fragment .adoc files (everything not topic-listed but in
@@ -542,7 +589,7 @@ export async function migrateAsciidoc(source, options) {
     //     fragments. Fragment conversion is engine-only (no Minja,
     //     no markdown-it) so directives inside fragments survive
     //     verbatim and resolve in the parent page's context.
-    const frag = convertFragmentAdocs(sourceDir, contentDir, scopedRootDirs);
+    const frag = convertFragmentAdocs(sourceDir, contentDir, scopedRootDirs, pageWrittenPaths, engineImagesdir);
     if (frag.converted > 0) {
         console.log(pc.green(`Converted`) +
             ` ${frag.converted} fragment(s)` +
@@ -563,6 +610,24 @@ export async function migrateAsciidoc(source, options) {
             parts.push(`${mirror.assets} asset(s)`);
         console.log(pc.green(`Mirrored`) + ` ${parts.join(" + ")}`);
     }
+    // 3e. Copy the imagesdir tree into content/_assets/<dir>/ so the
+    //     rooted image refs (/_assets/<dir>/foo.png, emitted by the
+    //     engine via the supplied imagesdir) resolve. format-astro's
+    //     copyAssets serves content/_assets/** at /_assets/** on every
+    //     build. (#363)
+    if (srcImagesDir) {
+        const from = join(sourceDir, srcImagesDir);
+        const to = join(contentDir, "_assets", srcImagesDir);
+        try {
+            mkdirSync(dirname(to), { recursive: true });
+            cpSync(from, to, { recursive: true });
+            console.log(pc.green(`Copied`) + ` images → content/_assets/${srcImagesDir}/`);
+        }
+        catch (err) {
+            const msg = err instanceof Error ? err.message : String(err);
+            console.warn(`images: could not copy ${from} → ${to}: ${msg}`);
+        }
+    }
     // 4. nav.yml — directly from the loader's NavItem[]. The loader
     //    decides the shape (directory-mirror for plain, per-title
     //    grouping for master.adoc, etc.). We just serialize.

package/dist/index.js

@@ -212,7 +212,8 @@ program
     "Antora, and AAP master.adoc loaders are planned for a later release.")
     .argument("<source>", "Path to a directory containing .adoc files")
     .option("-o, --output <dir>", "Output directory (default: {source}-dogsbay)")
-    .option("--force", "Overwrite an existing Dogsbay site at the output dir")
+    .option("--force", "Overwrite an existing Dogsbay site. Clean re-import: clears the " +
+    "content/ tree first, discarding any edits under it (astro/ kept).")
     .option("--site-name <name>", "Site name written into dogsbay.config.yml")
     .option("--site-url <url>", "Canonical URL of the destination site (e.g. " +
     "https://you.github.io/repo). Drives robots.txt, sitemap, " +

package/dist/site-build/preprocess.js

@@ -57,6 +57,21 @@ export function mergeAttributes(siteWide, perSource, cliOverrides) {
         ...(perSource ?? {}),
         ...(cliOverrides ?? {}),
     };
+    // AsciiDoc attribute names are hyphenated by convention (product-title,
+    // openshift-enterprise), but the engine emits underscored Minja vars
+    // ({{ product_title }}) and minja's context lookup is keyed on the
+    // underscored form (hyphenToUnderscore normalizes the *lookup*, not the
+    // stored keys). So a supplied `product-title` would never match. Add an
+    // underscored alias for every hyphenated key so users can pass either
+    // form. The original is kept; explicit underscored keys win over an
+    // alias derived from a hyphenated one.
+    for (const [key, value] of Object.entries({ ...merged })) {
+        if (key.includes("-")) {
+            const underscored = key.replace(/-/g, "_");
+            if (!(underscored in merged))
+                merged[underscored] = value;
+        }
+    }
     return Object.keys(merged).length > 0 ? merged : undefined;
 }
 /**

package/package.json

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