@dogsbay/adoc2md-modular 0.2.0-beta.101

package/dist/index.d.ts

@@ -0,0 +1,209 @@
+/**
+ * @dogsbay/adoc2md-modular
+ *
+ * AsciiDoc → Markdown converter optimised for modular-content
+ * patterns (includes, leveloffset, conditionals, attributes).
+ *
+ * Ported from the `~/dev/md2md` prototype's `src/downdoc.js` — a
+ * modified fork of Dan Allen's downdoc with adjustments for
+ * modular-content workflows (AAP, OpenShift, Antora-style content).
+ * See LINEAGE.md for the upstream fork point and the local
+ * modifications enumerated.
+ *
+ * This is the **per-file** converter. Corpus discovery (which files
+ * to convert, what order, what attribute context to apply) lives in
+ * the loaders in `@dogsbay/format-asciidoc` per
+ * `plans/asciidoc-corpus-loaders.md`. Variable / include
+ * resolution happens downstream in `@dogsbay/minja` per Phase 2 of
+ * `plans/format-asciidoc-import.md`.
+ *
+ * Phase 3 status: stub. The public API is shaped but the body is a
+ * pass-through that returns the input unchanged so the package
+ * loads and the wiring tests pass. Phase 4 ports the actual
+ * converter.
+ */
+/**
+ * Options for `asciidocToMarkdown`. Names and semantics mirror the
+ * md2md CLI flags (`-a name=value`, `-d`, `-A`, `--inline-includes`)
+ * so existing automation can drop in with no translation.
+ */
+export interface AsciidocToMarkdownOptions {
+    /**
+     * AsciiDoc attribute values known at convert time. These do NOT
+     * substitute into `{name}` slots here — the engine always emits
+     * `{{ name }}` Minja variables for attribute refs and lets the
+     * downstream `@dogsbay/minja` pass do the actual substitution
+     * with a runtime context. Same shape for `ifdef::` conditionals:
+     * always preserved as `{% if name %}` for Minja to evaluate.
+     *
+     * What this option DOES do: suppresses any in-document
+     * `:name: value` attribute entry from emitting a corresponding
+     * `{% set name = "value" %}` directive (because the value is
+     * being supplied externally). Equivalent to repeating
+     * `-a name=value` on md2md's CLI.
+     *
+     * The clean two-stage pipeline:
+     *   AsciiDoc → adoc2md-modular  → Markdown with `{{ vars }}` + `{% if %}`
+     *           → @dogsbay/minja(context) → final Markdown
+     */
+    attributes?: Record<string, unknown>;
+    /**
+     * Whether to inline `include::` directives during the AsciiDoc →
+     * Markdown pass.
+     *
+     * - `false` (default) — emit `{% include "path" %}` directives in
+     *   the output markdown. Downstream Minja resolution expands them
+     *   with the correct basePath tracking.
+     * - `true` — read each included file at convert time and splice
+     *   its content directly into the output. Equivalent to md2md's
+     *   `--inline-includes` flag. Loses round-trip fidelity but
+     *   produces a fully self-contained markdown artifact.
+     */
+    inlineIncludes?: boolean;
+    /**
+     * Definition list output format.
+     * - `'markdown'` (default) — `Term\n: Definition` (CommonMark).
+     * - `'html'` — `<dl><dt>Term</dt><dd>Definition</dd></dl>`.
+     * - `'pandoc'` — Pandoc's definition-list extension shape.
+     */
+    dlistFormat?: "markdown" | "html" | "pandoc";
+    /**
+     * Admonition output format. Only `[NOTE]` / `[WARNING]` /
+     * `[TIP]` block-form admonitions respect this option. The
+     * line-form (`NOTE: …`) always emits the html-like
+     * `**📌 NOTE**\` prefix shape regardless.
+     *
+     * - `'html'` (default) — `<dl><dt><strong>📌 NOTE</strong></dt><dd>…</dd></dl>`
+     *   for universal compatibility (Pandoc, GFM, MkDocs).
+     * - `'mkdocs'` — `!!! note` blocks (Material).
+     * - `'docusaurus'` — `:::note` directive blocks.
+     * - `'github'` — `> [!NOTE]` GFM-style alerts.
+     */
+    admonitionFormat?: "html" | "mkdocs" | "docusaurus" | "github";
+    /**
+     * Base path for resolving `include::` directives at convert
+     * time. Used both for inline includes (`inlineIncludes: true`)
+     * AND for the smart-indentation pass that `inlineIncludes: false`
+     * runs against the filesystem — without a basePath the engine
+     * silently drops include lines instead of emitting the
+     * `{% include "./<path>.md" %}` directive.
+     *
+     * Defaults to `process.cwd()` so includes always emit. Pass
+     * the source file's directory when converting a file that uses
+     * relative include paths.
+     */
+    basePath?: string;
+    /**
+     * Emit AsciiDoc block roles (`[role="x"]` / `[.x]`) as markdown-it-attrs
+     * classes (`{.x}`) on the block, instead of dropping them.
+     *
+     * - `false` (default) — drop roles (legacy behavior). Safe for consumers
+     *   that do NOT run markdown-it-attrs at parse time (e.g. the
+     *   `from: asciidoc` direct path), where a `{.x}` trailer would otherwise
+     *   leak as literal text.
+     * - `true` — emit `{.x}`. Use when the downstream parser runs
+     *   markdown-it-attrs (the migrate → `dogsbay-md` flow), so the class
+     *   becomes a real HTML class. Currently applied on section headings
+     *   (`## Title {id="…" .role}`).
+     *
+     * See plans/adoc2md-block-metadata.md (#384).
+     */
+    blockRoles?: boolean;
+    /**
+     * Containment root for include reads at CONVERT time (issue #027).
+     * When set, any file the engine reads to resolve an include —
+     * tag-filtered splices (`include::x[tags=…]`), smart-indentation
+     * probes, and `inlineIncludes` full splices — must resolve (after
+     * symlinks) inside this directory, or conversion fails with a named
+     * `IncludeContainmentError`. Unset = uncontained (trusted input,
+     * backward compatible). The downstream Minja stage enforces its own
+     * containment for the `{% include %}` directives the engine emits.
+     */
+    includeRoot?: string;
+    /**
+     * Docroot-relative slug of the source page (e.g. `"architecture/admission-plug-ins"`).
+     *
+     * When provided, cross-doc xref hrefs are resolved against this slug and
+     * emitted as root-relative paths (`/<resolved>`) rather than file-relative
+     * (`../<path>`). The latter is correct for *file*-style URLs but off by one
+     * under Astro's default `build.format: 'directory'` (trailing-slash URLs),
+     * so multi-depth pages get broken cross-refs without this resolution.
+     *
+     * Internal-anchor xrefs (`xref:my-section[]` -> `#my-section`) and external
+     * URLs are untouched. Absent `sourcePath` falls back to the legacy
+     * file-relative emit so standalone unit-test callers keep working.
+     *
+     * See plans/xref-absolute-hrefs.md.
+     */
+    sourcePath?: string;
+    /**
+     * Antora corpus mode. Activates Antora-specific resolution that would be
+     * wrong (or ambiguous) for other corpus shapes, so it's opt-in:
+     *
+     * - `xref:module:page[…]` / `xref:component:module:page[…]` coordinates
+     *   translate to root-relative hrefs (`/module/page`; `ROOT` collapses;
+     *   a `version@` prefix is dropped). Without this flag a module
+     *   coordinate looks like a URL scheme and leaks verbatim.
+     * - `include::[module:]family$rel[…]` resource IDs (partial$, example$,
+     *   page$, attachment$, image$) resolve to the module's family directory
+     *   (`modules/<mod>/partials/…`). Cross-component targets warn and drop.
+     * - Emitted `{% include %}` paths are relativized against `sourcePath`
+     *   (the document's OUTPUT position) instead of the raw source-relative
+     *   path, because migrated pages live at their slug path while fragments
+     *   mirror the source layout.
+     * - `tag=` / `tags=` include attributes are honoured (tag slices are
+     *   inlined at convert time). This also applies outside Antora mode.
+     *
+     * The module context is derived from the source file's own path (the
+     * nearest `modules/<name>/` ancestor of `basePath`).
+     *
+     * See plans/antora-support-gaps.md.
+     */
+    antora?: boolean;
+    /**
+     * Antora PLAYBOOK mode (#067): the slug prefix under which this file's
+     * component was mounted (`guides/`, `server-admin/server-4.9/`, `` for the
+     * root component). Include output paths target `<prefix>modules/…` so a
+     * page or fragment under the prefix finds fragments mirrored beside it.
+     * Omit for single-component corpora; when omitted the engine infers the
+     * prefix for PAGES from `sourcePath` and uses `''` for fragments.
+     */
+    antoraSlugPrefix?: string;
+    /**
+     * Antora PLAYBOOK mode (#067): every loaded component by name → its
+     * root directory and slug prefix, so an include/xref naming ANOTHER
+     * loaded component (`include::guides:ROOT:partial$x.adoc[]` from inside
+     * `reference`) resolves against that component instead of being warned
+     * as unresolvable. Omit for single-component corpora.
+     */
+    antoraComponents?: Record<string, {
+        dir: string;
+        prefix: string;
+    }>;
+    /**
+     * Attribute names the caller KNOWS are false — e.g. the corpus's other
+     * distro flags in a single-distro migrate. Drives conditional STATE
+     * tracking only (a provably-dropped branch's lists/dlists cannot anchor
+     * later content); never drops output text. Names may be given in either
+     * hyphen or underscore form.
+     */
+    falseAttributes?: string[];
+    /**
+     * Clamp over-declared rowspans (`.6+|` over five sub-rows) to the rows
+     * that actually fit, instead of letting the span swallow the next
+     * row's first cell (issue #031 — upstream openshift-docs bugs;
+     * asciidoctor renders them broken too). OPT-IN: default false keeps
+     * pure garbage-in-garbage-out parity. Set by `migrate-asciidoc`.
+     */
+    clampRowspans?: boolean;
+}
+/**
+ * Convert AsciiDoc source to Markdown.
+ *
+ * Wraps the engine (Phase 4 port of md2md/src/downdoc.js) and
+ * exposes the documented public options shape. Output is Markdown
+ * with embedded Minja directives for unresolved variables and
+ * includes — resolve them downstream with `@dogsbay/minja`.
+ */
+export declare function asciidocToMarkdown(src: string, opts?: AsciidocToMarkdownOptions): string;
+//# sourceMappingURL=index.d.ts.map

package/dist/index.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;;GAuBG;AAEH;;;;GAIG;AACH,MAAM,WAAW,yBAAyB;IACxC;;;;;;;;;;;;;;;;;OAiBG;IACH,UAAU,CAAC,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,CAAC;IAErC;;;;;;;;;;;OAWG;IACH,cAAc,CAAC,EAAE,OAAO,CAAC;IAEzB;;;;;OAKG;IACH,WAAW,CAAC,EAAE,UAAU,GAAG,MAAM,GAAG,QAAQ,CAAC;IAE7C;;;;;;;;;;;OAWG;IACH,gBAAgB,CAAC,EAAE,MAAM,GAAG,QAAQ,GAAG,YAAY,GAAG,QAAQ,CAAC;IAE/D;;;;;;;;;;;OAWG;IACH,QAAQ,CAAC,EAAE,MAAM,CAAC;IAElB;;;;;;;;;;;;;;OAcG;IACH,UAAU,CAAC,EAAE,OAAO,CAAC;IAErB;;;;;;;;;OASG;IACH,WAAW,CAAC,EAAE,MAAM,CAAC;IAErB;;;;;;;;;;;;;;OAcG;IACH,UAAU,CAAC,EAAE,MAAM,CAAC;IAEpB;;;;;;;;;;;;;;;;;;;;;;OAsBG;IACH,MAAM,CAAC,EAAE,OAAO,CAAC;IACjB;;;;;;;OAOG;IACH,gBAAgB,CAAC,EAAE,MAAM,CAAC;IAC1B;;;;;;OAMG;IACH,gBAAgB,CAAC,EAAE,MAAM,CAAC,MAAM,EAAE;QAAE,GAAG,EAAE,MAAM,CAAC;QAAC,MAAM,EAAE,MAAM,CAAA;KAAE,CAAC,CAAC;IAEnE;;;;;;OAMG;IACH,eAAe,CAAC,EAAE,MAAM,EAAE,CAAC;IAC3B;;;;;;OAMG;IACH,aAAa,CAAC,EAAE,OAAO,CAAC;CACzB;AAQD;;;;;;;GAOG;AACH,wBAAgB,kBAAkB,CAChC,GAAG,EAAE,MAAM,EACX,IAAI,GAAE,yBAA8B,GACnC,MAAM,CAqBR"}

package/dist/index.js

@@ -0,0 +1,60 @@
+/**
+ * @dogsbay/adoc2md-modular
+ *
+ * AsciiDoc → Markdown converter optimised for modular-content
+ * patterns (includes, leveloffset, conditionals, attributes).
+ *
+ * Ported from the `~/dev/md2md` prototype's `src/downdoc.js` — a
+ * modified fork of Dan Allen's downdoc with adjustments for
+ * modular-content workflows (AAP, OpenShift, Antora-style content).
+ * See LINEAGE.md for the upstream fork point and the local
+ * modifications enumerated.
+ *
+ * This is the **per-file** converter. Corpus discovery (which files
+ * to convert, what order, what attribute context to apply) lives in
+ * the loaders in `@dogsbay/format-asciidoc` per
+ * `plans/asciidoc-corpus-loaders.md`. Variable / include
+ * resolution happens downstream in `@dogsbay/minja` per Phase 2 of
+ * `plans/format-asciidoc-import.md`.
+ *
+ * Phase 3 status: stub. The public API is shaped but the body is a
+ * pass-through that returns the input unchanged so the package
+ * loads and the wiring tests pass. Phase 4 ports the actual
+ * converter.
+ */
+// Engine ported from md2md/src/downdoc.js — see engine.js,
+// engine.d.ts, and LINEAGE.md. Imported here as the only call
+// site; everything in this file translates the public options
+// shape into the engine's raw shape.
+import engine from "./engine.js";
+/**
+ * Convert AsciiDoc source to Markdown.
+ *
+ * Wraps the engine (Phase 4 port of md2md/src/downdoc.js) and
+ * exposes the documented public options shape. Output is Markdown
+ * with embedded Minja directives for unresolved variables and
+ * includes — resolve them downstream with `@dogsbay/minja`.
+ */
+export function asciidocToMarkdown(src, opts = {}) {
+    // Translate the public options to engine option names. The only
+    // delta is `inlineIncludes` (public) → `nunjucksIncludes` (engine),
+    // which is the inverse boolean: inlineIncludes=true means inline
+    // at convert time, which the engine expresses as
+    // nunjucksIncludes=false.
+    return engine(src, {
+        attributes: opts.attributes ?? {},
+        basePath: opts.basePath ?? process.cwd(),
+        nunjucksIncludes: opts.inlineIncludes === true ? false : true,
+        dlistFormat: opts.dlistFormat ?? "markdown",
+        clampRowspans: opts.clampRowspans ?? false,
+        admonitionFormat: opts.admonitionFormat ?? "html",
+        blockRoles: opts.blockRoles ?? false,
+        sourcePath: opts.sourcePath ?? null,
+        antora: opts.antora ?? false,
+        antoraSlugPrefix: opts.antoraSlugPrefix ?? null,
+        antoraComponents: opts.antoraComponents ?? null,
+        falseAttributes: opts.falseAttributes ?? [],
+        includeRoot: opts.includeRoot ?? null,
+    });
+}
+//# sourceMappingURL=index.js.map

package/dist/index.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.js","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;;GAuBG;AAwLH,2DAA2D;AAC3D,8DAA8D;AAC9D,8DAA8D;AAC9D,qCAAqC;AACrC,OAAO,MAAM,MAAM,aAAa,CAAC;AAEjC;;;;;;;GAOG;AACH,MAAM,UAAU,kBAAkB,CAChC,GAAW,EACX,OAAkC,EAAE;IAEpC,gEAAgE;IAChE,oEAAoE;IACpE,iEAAiE;IACjE,iDAAiD;IACjD,0BAA0B;IAC1B,OAAO,MAAM,CAAC,GAAG,EAAE;QACjB,UAAU,EAAE,IAAI,CAAC,UAAU,IAAI,EAAE;QACjC,QAAQ,EAAE,IAAI,CAAC,QAAQ,IAAI,OAAO,CAAC,GAAG,EAAE;QACxC,gBAAgB,EAAE,IAAI,CAAC,cAAc,KAAK,IAAI,CAAC,CAAC,CAAC,KAAK,CAAC,CAAC,CAAC,IAAI;QAC7D,WAAW,EAAE,IAAI,CAAC,WAAW,IAAI,UAAU;QAC3C,aAAa,EAAE,IAAI,CAAC,aAAa,IAAI,KAAK;QAC1C,gBAAgB,EAAE,IAAI,CAAC,gBAAgB,IAAI,MAAM;QACjD,UAAU,EAAE,IAAI,CAAC,UAAU,IAAI,KAAK;QACpC,UAAU,EAAE,IAAI,CAAC,UAAU,IAAI,IAAI;QACnC,MAAM,EAAE,IAAI,CAAC,MAAM,IAAI,KAAK;QAC5B,gBAAgB,EAAE,IAAI,CAAC,gBAAgB,IAAI,IAAI;QAC/C,gBAAgB,EAAE,IAAI,CAAC,gBAAgB,IAAI,IAAI;QAC/C,eAAe,EAAE,IAAI,CAAC,eAAe,IAAI,EAAE;QAC3C,WAAW,EAAE,IAAI,CAAC,WAAW,IAAI,IAAI;KACtC,CAAC,CAAC;AACL,CAAC"}

package/package.json

@@ -0,0 +1,44 @@
+{
+  "name": "@dogsbay/adoc2md-modular",
+  "version": "0.2.0-beta.101",
+  "description": "AsciiDoc → Markdown converter optimised for modular-content patterns (includes, leveloffset, conditionals, attributes). Ported from the md2md prototype; emits Markdown with embedded Minja directives for downstream variable / include resolution.",
+  "type": "module",
+  "main": "dist/index.js",
+  "types": "dist/index.d.ts",
+  "exports": {
+    ".": {
+      "types": "./dist/index.d.ts",
+      "import": "./dist/index.js"
+    }
+  },
+  "bin": {
+    "adoc2md": "./bin/adoc2md.js",
+    "adoc2md-modular": "./bin/adoc2md.js"
+  },
+  "files": [
+    "dist",
+    "bin",
+    "README.md",
+    "LINEAGE.md"
+  ],
+  "devDependencies": {
+    "@types/node": "^25.9.5",
+    "typescript": "^5.9.3",
+    "vitest": "^4.1.10"
+  },
+  "license": "MIT",
+  "repository": {
+    "type": "git",
+    "url": "https://github.com/dogsbay/dogsbay.git",
+    "directory": "packages/adoc2md-modular"
+  },
+  "homepage": "https://github.com/dogsbay/dogsbay/tree/main/packages/adoc2md-modular",
+  "bugs": {
+    "url": "https://github.com/dogsbay/dogsbay/issues"
+  },
+  "scripts": {
+    "build": "tsc",
+    "test": "vitest run",
+    "test:watch": "vitest"
+  }
+}