@dogsbay/adoc2md-modular 0.2.0-beta.48

package/LINEAGE.md

@@ -0,0 +1,67 @@
+# 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).
+**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 md2md `docs-dev/DESIGN-DECISIONS.md` + `GOTCHAS.md` documents enumerate the modifications. 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,38 @@
+# @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.
+
+> **Phase 3 status:** scaffold only. Public API is shaped; the body is a stub that returns the input unchanged. Phase 4 will land the real converter ported from `md2md/src/downdoc.js`. Not safe to consume in a pipeline yet.
+
+## 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).
+
+## 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` (to be added in Phase 4) 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/dist/engine.d.ts

@@ -0,0 +1,9 @@
+export default function downdoc(asciidoc: any, { attributes: initialAttrs, basePath, cleanupContinuation, nunjucksIncludes, dlistFormat, admonitionFormat }?: {
+    attributes?: {} | undefined;
+    basePath?: null | undefined;
+    cleanupContinuation?: boolean | undefined;
+    nunjucksIncludes?: boolean | undefined;
+    dlistFormat?: string | undefined;
+    admonitionFormat?: string | 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":"AA+4CA;;;;;;;QAwfC"}