@dogsbay/adoc2md-modular 0.2.0-beta.101

package/LINEAGE.md

@@ -0,0 +1,68 @@
+# LINEAGE
+
+`packages/adoc2md-modular/src/engine.js` is a fork of [downdoc](https://gitlab.com/antora/downdoc) by Dan Allen (Apache-2.0), substantially modified by the `~/dev/md2md` prototype, then carried into Dogsbay verbatim during Phase 4 of [`plans/format-asciidoc-import.md`](../../plans/format-asciidoc-import.md).
+
+**Date copied into Dogsbay:** 2026-05-13.
+**Source file:** `~/dev/md2md/src/downdoc.js` (the md2md prototype's modified fork — not the upstream downdoc).
+**Upstream fork commit:** `e2ea8d9` (2026-02-13) — the last md2md commit to touch `downdoc.js`.
+**Size:** 2069 lines.
+**License:** Apache-2.0 (inherited from downdoc upstream).
+
+## Why we forked
+
+Upstream downdoc handles single-file AsciiDoc → Markdown conversion well. The md2md prototype's fork extends it for **modular-content** workflows — the patterns Red Hat (AAP, OpenShift) and Antora-style doc sites use heavily:
+
+- `include::` directives in a multi-file corpus (with `leveloffset` adjustment)
+- `ifdef::`/`ifndef::` conditionals where the attribute context is supplied at convert time (or preserved for later resolution)
+- Document-level `:attr: value` declarations interleaved with prose
+- Attribute references `{name}` resolved against a layered attribute context
+
+The fork's strategy is to **emit Minja directives** for the constructs that depend on a runtime context — `{{ name }}` for attribute refs, `{% if name %}…{% endif %}` for conditionals, `{% include "./<path>.md" %}` for includes, `{% set name = "value" %}` for in-doc attribute entries. Downstream [`@dogsbay/minja`](../minja/) then evaluates those directives with the actual context. This two-stage pipeline keeps the AsciiDoc-syntax converter free of I/O and runtime-state concerns.
+
+## Changes from upstream downdoc
+
+The engine's design docs were migrated from md2md into [`docs-dev/`](./docs-dev/) on 2026-05-21 — `DESIGN-DECISIONS.md` (the DD-### log; **DD-009** governs Pandoc dlist placement, **DD-010** the admonition formats), `GOTCHAS.md`, and `ARCHITECTURE.md`. They enumerate the modifications below; their inline code line numbers are from the upstream fork point and may have drifted. Key surface-level deltas the test suite locked in:
+
+| Change | Where (rough) | Why |
+|---|---|---|
+| Attribute refs `{name}` always emit `{{ name }}` Minja vars (never inline-substitute) | `applySubs` / `attributes()` path | Two-stage pipeline — Minja resolves at render time. |
+| `:name: value` entries emit `{%- set name = "value" %}` | Top-level attribute-entry handler | Preserves attribute scope through includes. |
+| `ifdef::name[]` / `ifndef::name[]` / `endif::[]` emit `{% if … %}…{% endif %}` (never evaluated inline) | Preprocessor-directive path | Minja evaluates with runtime context. |
+| `include::path.adoc[]` emits `{% include "./path.md" %}` (extension auto-converted) when `nunjucksIncludes=true` | `resolveIncludes` | Pipeline emits Markdown; included sibling will also be Markdown. |
+| Smart indentation for includes (top-level list items get special handling) | `resolveIncludes` | Avoids breaking list semantics across include boundaries. |
+| Custom ID format `{id="..."}` on sub-headings | Heading emitter | Markdown-it-compatible; supports stable anchors. |
+| 4-space list indentation | Constant `markdown-list-indent=4` | Mirrors mkdocs-material's canonical form. |
+| Permissive empty-line handling | Various block parsers | Real-world AAP / OpenShift docs are quirky. |
+| UI macros (`btn`, `kbd`, `menu`) converted to HTML | Inline macro path | Cross-renderer compatibility. |
+| `:!aws:` AsciiDoc unset → `{% set aws = false %}` | Attribute-entry handler | Minja-friendly representation of unset. |
+| List numbering uses uniform `1.` (not incremented) | List emitter | Cleaner version-control diffs. |
+| Admonitions: line-form (`NOTE: …`) always HTML-ish (`**📌 NOTE**\`); only block-form (`[NOTE]\n====\n…\n====`) respects `admonitionFormat` | Admonition emitter | Line-form is a single-line construct; block-form is the configurable surface. |
+
+## What we changed during the Dogsbay port
+
+Minimal — kept the engine as plain JS to minimise regression risk:
+
+1. **CommonJS → ESM**: 4 lines at the top of the file.
+   - `'use strict'` → removed (ESM is strict)
+   - `const fs = require('fs')` → `import fs from 'node:fs'`
+   - `const path = require('path')` → `import path from 'node:path'`
+   - `module.exports = function downdoc (…)` → `export default function downdoc (…)`
+2. **`engine.d.ts`** hand-written for the public surface (`EngineOptions` + default export).
+3. **No other code edits.** The 2069 lines of converter logic are byte-identical to the md2md prototype.
+
+## How to update from md2md upstream
+
+`md2md` is treated as a read-only reference per `plans/format-asciidoc-import.md`. There's no auto-sync. To pull a new revision:
+
+1. Diff `~/dev/md2md/src/downdoc.js` against `packages/adoc2md-modular/src/engine.js`.
+2. Apply the substantive changes (skipping the 4-line ESM patch above — those stay).
+3. Re-run `pnpm --filter @dogsbay/adoc2md-modular test`.
+4. Update this LINEAGE.md with the new source date + change summary.
+
+## Attribution
+
+- Upstream: [Dan Allen / downdoc](https://gitlab.com/antora/downdoc) — Apache-2.0.
+- Prototype: `~/dev/md2md/src/downdoc.js` (the modified fork). md2md authors carried the upstream license.
+- Phase 4 Dogsbay port: Gabriel McGoldrick (the same prototype author), 2026-05-13.
+
+License is preserved as Apache-2.0 for `engine.js`; the rest of the package (`index.ts`, `engine.d.ts`, tests, docs) is MIT (the dogsbay default).

package/README.md

@@ -0,0 +1,69 @@
+# @dogsbay/adoc2md-modular
+
+AsciiDoc → Markdown converter optimised for **modular-content** patterns: `include::` resolution, `:leveloffset:` adjustment, `ifdef::` conditionals, attribute substitution. Ported from the [`md2md`](https://github.com/dogsbay/md2md) prototype's `downdoc.js`; the per-file engine that `@dogsbay/format-asciidoc` builds on.
+
+**Status:** live. The full converter (`src/engine.js`) is in production for the OpenShift migration; `index.ts` wraps it and exposes the public options. Zero runtime dependencies, ESM-only, published to npm.
+
+## API
+
+```ts
+import { asciidocToMarkdown } from "@dogsbay/adoc2md-modular";
+
+const md = asciidocToMarkdown(adocSource, {
+  attributes: { product: "AAP", version: "2.5" },
+  inlineIncludes: false,                  // default — emit {% include %}
+  dlistFormat: "markdown",                // markdown | html | pandoc
+  admonitionFormat: "html",               // html | mkdocs | docusaurus | github
+});
+```
+
+Output is Markdown with Minja directives embedded for unresolved variables and includes. Resolve them downstream with `@dogsbay/minja` (see `plans/format-asciidoc-import.md` Phase 2 for the `undefinedBehavior` modes that let unresolved attributes survive into the final artifact).
+
+## CLI
+
+A standalone `adoc2md` bin ships for converting **one file** without the full `dogsbay` CLI:
+
+```bash
+npx @dogsbay/adoc2md-modular path/to/file.adoc > file.md   # or: adoc2md file.adoc
+cat file.adoc | adoc2md - --admonition-format docusaurus   # stdin → stdout
+adoc2md https://github.com/openshift/openshift-docs/blob/main/modules/about-crio.adoc
+#        ^ a URL works too; GitHub "blob" URLs are auto-rewritten to raw
+```
+
+Input can be a file, `-`/stdin, or an `http(s)` URL — handy for demoing against real GitHub content. A remote file's *relative* `include::` directives stay as `{% include %}` (they can't be read off disk).
+
+It is **translate-only** — the output keeps `{{ vars }}` / `{% if %}` / `{% include %}` directives. Attribute values and distro selection are a no-op at translate time, so the CLI intentionally doesn't accept them; supply them at the resolve step with [`@dogsbay/minja`](../minja) (a Jinja2/Nunjucks subset built for this):
+
+```bash
+# 1. translate (this package)
+adoc2md page.adoc -o page.md
+#    → Welcome to {{ product_title }} {{ product_version }}.
+#    → {% if openshift_enterprise %} … {% endif %}
+
+# 2. resolve (minja) — values live here, not in step 1
+npx @dogsbay/minja page.md -v '{"product_title":"OpenShift","product_version":"4.22","openshift_enterprise":true}'
+#    → Welcome to OpenShift 4.22.
+#    → (enterprise branch kept)
+```
+
+`minja` also accepts `-c <context.json|yaml>` and `-o <out.md>`. Any other Jinja2/Nunjucks-compatible engine works too, given the same variable names (hyphens become underscores: `{product-title}` → `{{ product_title }}`).
+
+Flags mirror the API options that affect output: `-A/--admonition-format`, `-d/--dlist-format`, `--inline-includes`, `--base-path`, `--block-roles`, `--source-path`, `-o/--output`. Run `adoc2md --help` for details. For a whole corpus (topic-map nav, distro filtering, scaffolded site) use `dogsbay migrate-asciidoc` instead.
+
+## Why a separate package?
+
+Three concerns are intertwined in AsciiDoc import and each deserves its own surface:
+
+1. **Per-file converter** (this package): AsciiDoc syntax → Markdown text. Pure function, no I/O, no corpus topology.
+2. **Preprocessor** (`@dogsbay/minja`): variable + include resolution against an attribute context.
+3. **Corpus loader** (`@dogsbay/format-asciidoc`): discovery + topology — which files exist, what variants apply, how nav is built. See `plans/asciidoc-corpus-loaders.md`.
+
+Keeping the converter free of I/O and topology means it round-trips deterministically and stays easy to test against the md2md fixtures.
+
+## Lineage
+
+Forked from Dan Allen's [downdoc](https://gitlab.com/antora/downdoc) via the `md2md` prototype. See [`LINEAGE.md`](./LINEAGE.md) for the upstream fork point and enumerated local modifications.
+
+## Roadmap
+
+See [`plans/format-asciidoc-import.md`](../../plans/format-asciidoc-import.md) for the 8-phase rollout. This package owns Phases 3–5.

package/bin/adoc2md.js

@@ -0,0 +1,157 @@
+#!/usr/bin/env node
+/**
+ * `adoc2md` — standalone single-file AsciiDoc → Markdown converter.
+ *
+ * A thin I/O wrapper around the pure `asciidocToMarkdown` engine so the
+ * package can be demoed without the full `dogsbay` CLI. Reads one `.adoc`
+ * file (or stdin), writes Markdown (or `-o <file>`).
+ *
+ * TRANSLATE-ONLY by design: the output keeps Minja/Jinja directives
+ * (`{{ vars }}`, `{% if %}`, `{% include %}`). Attribute VALUES and distro
+ * selection are deliberately NOT accepted here — the engine never
+ * substitutes them at translate time (they're a no-op on the output).
+ * Supply them at the resolve step instead, with `@dogsbay/minja`,
+ * Nunjucks, or Jinja2. This CLI only exposes knobs that change the
+ * translated Markdown.
+ *
+ * Zero runtime dependencies — only Node builtins.
+ */
+import { readFileSync, writeFileSync } from "node:fs";
+import { dirname } from "node:path";
+import { parseArgs } from "node:util";
+import { asciidocToMarkdown } from "../dist/index.js";
+import { isHttpUrl, normalizeGitHubUrl } from "./url.js";
+
+const HELP = `adoc2md — convert one AsciiDoc file to Markdown (with Minja directives)
+
+USAGE
+  adoc2md <file.adoc> [options]
+  adoc2md <https://…/file.adoc> [options]   fetch a URL (GitHub blob URLs
+                                            are auto-rewritten to raw)
+  adoc2md - [options]                 read AsciiDoc from stdin
+  cat file.adoc | adoc2md [options]
+
+OPTIONS
+  -A, --admonition-format <fmt> html | mkdocs | docusaurus | github  (default html)
+  -d, --dlist-format <fmt>      markdown | html | pandoc              (default markdown)
+      --inline-includes         Splice include:: files in now instead of
+                                emitting {% include %} directives.
+      --base-path <dir>         Root for resolving include:: (default: the
+                                input file's directory, or CWD for stdin).
+      --block-roles             Emit [role]/[.role] as {.role} classes.
+      --source-path <slug>      Docroot-relative slug → root-relative xrefs.
+  -o, --output <file>           Write Markdown here instead of stdout.
+  -h, --help                    Show this help.
+  -v, --version                 Print version.
+
+NOTES
+  Output is TRANSLATE-ONLY: {{ vars }} / {% if %} / {% include %} are
+  preserved. Attribute values and distro selection are a no-op at this
+  stage, so they aren't accepted here — resolve them downstream with
+  @dogsbay/minja (or another Jinja engine) and a context, e.g.
+
+      adoc2md page.adoc -o page.md
+      npx @dogsbay/minja page.md -v '{"product_title":"OpenShift","openshift_enterprise":true}'
+      # minja also takes -c <context.json|yaml> and -o <out.md>
+
+  A remote file's relative include:: directives can't be read from disk,
+  so they stay as {% include %} in the output (not spliced).
+`;
+
+function fail(msg) {
+  process.stderr.write(`adoc2md: ${msg}\n`);
+  process.exit(1);
+}
+
+let parsed;
+try {
+  parsed = parseArgs({
+    allowPositionals: true,
+    options: {
+      "admonition-format": { type: "string", short: "A" },
+      "dlist-format": { type: "string", short: "d" },
+      "inline-includes": { type: "boolean" },
+      "base-path": { type: "string" },
+      "block-roles": { type: "boolean" },
+      "source-path": { type: "string" },
+      output: { type: "string", short: "o" },
+      help: { type: "boolean", short: "h" },
+      version: { type: "boolean", short: "v" },
+    },
+  });
+} catch (err) {
+  fail(err.message);
+}
+
+const { values, positionals } = parsed;
+
+if (values.help) {
+  process.stdout.write(HELP);
+  process.exit(0);
+}
+if (values.version) {
+  const pkg = JSON.parse(
+    readFileSync(new URL("../package.json", import.meta.url), "utf8"),
+  );
+  process.stdout.write(`${pkg.version}\n`);
+  process.exit(0);
+}
+
+// Resolve input: a URL, a positional file, or stdin ("-" or nothing).
+const input = positionals[0];
+let src;
+let basePath;
+if (isHttpUrl(input)) {
+  const url = normalizeGitHubUrl(input); // github blob → raw
+  let res;
+  try {
+    res = await fetch(url);
+  } catch (err) {
+    fail(`cannot fetch ${url}: ${err.message}`);
+  }
+  if (!res.ok) {
+    fail(`cannot fetch ${url}: HTTP ${res.status} ${res.statusText}`);
+  }
+  const contentType = res.headers.get("content-type") ?? "";
+  if (/\btext\/html\b/i.test(contentType)) {
+    fail(
+      `${url} returned HTML, not AsciiDoc — if this is a GitHub "blob" page, use the raw URL (raw.githubusercontent.com/…).`,
+    );
+  }
+  src = await res.text();
+  // A remote file's relative include:: can't be read from disk, so they
+  // stay as {% include %} directives. --base-path is honoured if given.
+  basePath = values["base-path"] ?? process.cwd();
+} else {
+  try {
+    if (input && input !== "-") {
+      src = readFileSync(input, "utf8");
+      basePath = values["base-path"] ?? dirname(input);
+    } else {
+      src = readFileSync(0, "utf8"); // fd 0 = stdin
+      basePath = values["base-path"] ?? process.cwd();
+    }
+  } catch (err) {
+    fail(`cannot read input: ${err.message}`);
+  }
+}
+
+let md;
+try {
+  md = asciidocToMarkdown(src, {
+    basePath,
+    inlineIncludes: values["inline-includes"] ?? false,
+    dlistFormat: values["dlist-format"] ?? "markdown",
+    admonitionFormat: values["admonition-format"] ?? "html",
+    blockRoles: values["block-roles"] ?? false,
+    sourcePath: values["source-path"],
+  });
+} catch (err) {
+  fail(`conversion failed: ${err.message}`);
+}
+
+if (values.output) {
+  writeFileSync(values.output, md);
+} else {
+  process.stdout.write(md);
+}

package/bin/url.js

@@ -0,0 +1,29 @@
+/**
+ * URL helpers for the `adoc2md` CLI. Kept separate from the bin so the
+ * rewrite is unit-testable without spawning the process. Pure functions,
+ * zero dependencies.
+ */
+
+/** True for an `http://` / `https://` string. */
+export function isHttpUrl(s) {
+  return typeof s === "string" && /^https?:\/\//i.test(s);
+}
+
+/**
+ * Rewrite a GitHub "blob" web URL to its raw.githubusercontent.com
+ * equivalent, so `adoc2md <url-pasted-from-the-browser>` fetches the
+ * AsciiDoc source instead of the HTML page. Non-blob / non-GitHub URLs
+ * pass through unchanged.
+ *
+ *   https://github.com/OWNER/REPO/blob/REF/path/to/file.adoc
+ *   → https://raw.githubusercontent.com/OWNER/REPO/REF/path/to/file.adoc
+ *
+ * REF may itself contain slashes (e.g. a `feature/x` branch); everything
+ * after `blob/` is preserved verbatim, matching GitHub's own mapping.
+ */
+export function normalizeGitHubUrl(url) {
+  const m = /^https?:\/\/github\.com\/([^/]+)\/([^/]+)\/blob\/(.+)$/i.exec(url);
+  if (!m) return url;
+  const [, owner, repo, rest] = m;
+  return `https://raw.githubusercontent.com/${owner}/${repo}/${rest}`;
+}

package/dist/engine.d.ts

@@ -0,0 +1,17 @@
+export default function downdoc(asciidoc: any, { attributes: initialAttrs, basePath, cleanupContinuation, nunjucksIncludes, dlistFormat, admonitionFormat, blockRoles, sourcePath, antora, antoraSlugPrefix, antoraComponents, falseAttributes, clampRowspans, includeRoot }?: {
+    attributes?: {} | undefined;
+    basePath?: null | undefined;
+    cleanupContinuation?: boolean | undefined;
+    nunjucksIncludes?: boolean | undefined;
+    dlistFormat?: string | undefined;
+    admonitionFormat?: string | undefined;
+    blockRoles?: boolean | undefined;
+    sourcePath?: null | undefined;
+    antora?: boolean | undefined;
+    antoraSlugPrefix?: null | undefined;
+    antoraComponents?: null | undefined;
+    falseAttributes?: never[] | undefined;
+    clampRowspans?: boolean | undefined;
+    includeRoot?: null | undefined;
+}): any;
+//# sourceMappingURL=engine.d.ts.map

package/dist/engine.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"engine.d.ts","sourceRoot":"","sources":["../src/engine.js"],"names":[],"mappings":"AAmjHA;;;;;;;;;;;;;;;QAy3CC"}