AsciiDoc -> Markdown file converter

[nlopes]

I just needed this and thought it would be nice to build a converter from AsciiDoc to Markdown and have nice diagnostics around what isn't supported, etc.

---

Feature specification

Overview

A highly configurable AsciiDoc-to-Markdown converter for documentation portability, with tunable degradation strategies and multiple Markdown flavor targets.

Use case

Documentation portability - making AsciiDoc docs accessible in Markdown-dominant ecosystems.

Core design principles

• Single-file conversion only - no batch mode, external tooling handles multi-file
• Pre-processed input - includes/conditionals resolved before conversion
• Configuration via document attributes - leverages existing -a CLI override system
• Best-effort with warnings - always produce output, warn on stderr for ambiguous constructs
• Preserve source formatting - match whitespace patterns from original AsciiDoc

---

Configuration system

Presets with overrides:

:markdown-preset: github
:markdown-admonitions: emoji

Built-in presets should include:

• commonmark - strict CommonMark, maximum portability
• github - GFM features (tables, task lists, alerts)
• pandoc - rich extensions (definition lists, footnotes, attributes)
• minimal - lossy but maximally readable

---

Feature-specific behaviors

Feature	Default	Tunable options
Admonitions	Configurable	emoji (blockquote + 🔵), gfm-alerts (> [!NOTE]), html (<div class="note">), bold-prefix (NOTE:)
Tables	Follow HTML tunable	Simple → Markdown pipes; complex → HTML or degraded Markdown with warning
Callouts	Preserve markers	Keep <1> <2> in code with legend below
Source blocks	Language only	Drop line numbers/highlighting, preserve language hint
Attributes	Tunable	expand (resolve values), frontmatter (YAML), preserve (literal), strip
Xrefs	Convert to .md	Rewrite xref:file.adoc → [text](file.md)
Anchors	Conditional HTML	<a id="..."></a> when HTML tunable enabled
Block roles	Tunable	drop, html-wrapper, comment
Sidebars/examples	Conditional	HTML (<aside>, <div>) when enabled, else --- horizontal rules
Passthrough	Emit directly	Raw content passes through unchanged
Extensions/macros	Warn + preserve	Keep syntax literally, warn on stderr
Formatting nesting	Semantics first	Prefer correct meaning, use HTML spans for complex cases with warning
Typography	Tunable	Unicode output vs ASCII preservation
Lists	Best-effort indent	4-space continuation, accept renderer limitations

---

Degradation strategy tunable

:markdown-degradation: controls fallback behavior globally:

• lossy - prioritize readability, accept semantic loss
• html - use HTML blocks for unsupported features
• skip - leave placeholder with warning
• comment - best approximation + HTML comment noting original

Individual feature tunables can override this default.

---

Warning behavior

• Warnings to stderr only (don't pollute output)
• Warn on: unsupported features, complex nesting requiring HTML, unknown extensions, semantic loss
• Clear, actionable messages with line numbers

---

Non-goals (explicit scope boundaries)

• No batch/directory mode
• No extension invocation (diagram rendering, etc.)
• No index/glossary/bibliography support
• No math rendering (just preserve syntax)
• No comment preservation in output

---

Example document attribute configuration

:markdown-preset: github
:markdown-degradation: html
:markdown-admonitions: gfm-alerts
:markdown-typography: unicode
:markdown-roles: html-wrapper