Convert AsciiDoc to Markdown

What is AsciiDoc?

AsciiDoc is a text-based document format created by Stuart Rackham in 2002, designed as a lightweight alternative to DocBook XML. It sits in an awkward middle ground between Markdown's plain-text minimalism and LaTeX's full typesetting power — more expressive than MD, simpler than DocBook. For roughly a decade it was the standard format for technical book authors (O'Reilly, Pragmatic Programmers), many Linux distributions used it for package documentation, and projects like Pro Git shipped their source in AsciiDoc.

The format still has steady users today. Asciidoctor, its modern toolchain (Ruby-based, written by Dan Allen in 2012), powers the documentation pipelines for projects like Spring Framework, OpenJDK, Jenkins, and much of the Eclipse Foundation. AsciiDoc is popular in enterprise Java, in API-first companies with long-form reference docs, and in the scientific computing community where fine typography matters more than ecosystem breadth.

Where AsciiDoc shines over Markdown: admonitions (first-class NOTE:, TIP:, WARNING: blocks), table cells with formatting, multi-level content includes (include::), attribute substitution, and rigorous cross-references. Where AsciiDoc struggles: nearly every note-taking, blog, and wiki platform speaks Markdown first. So the migration question comes up whenever a team decides the ecosystem gap is a bigger problem than the formatting power loss.

Why migrate to Markdown?

Three reasons drive most AsciiDoc → Markdown migrations. First, platform reach. GitHub renders AsciiDoc in repositories but the rendering is noticeably slower and less rich than its GFM path; Obsidian doesn't render AsciiDoc natively at all; Jekyll and Hugo both support AsciiDoc via plugins but with caveats. Markdown runs everywhere with zero configuration.

Second, contributor familiarity. If you're running a project that accepts outside contributions, Markdown has a much larger population of writers who already know it. AsciiDoc requires a tutorial. When a pull request for a docs fix arrives, you'd rather get it in a format the contributor wrote correctly in five minutes than spend half an hour explaining why == means header level 2 and not the horizontal rule.

Third, tooling churn. AsciiDoc's toolchain (Asciidoctor plus various extensions) has been stable but specialized. Modern Markdown ecosystems (MDX, remark, unified.js) move faster and integrate with more JavaScript tooling. If you want to build a custom docs pipeline in Next.js or Astro, Markdown paths have ten times the prior art.

Where AsciiDoc wins and migration loses: highly structured technical manuals with tables, admonitions, and cross-references. Before migrating, check whether your destination supports GFM admonition syntax (> [!NOTE]) — GitHub does, Obsidian does with Callouts, most others do not. If you depend heavily on admonitions, either target a GFM-compatible platform or plan for conversion loss.

Manual approach

AsciiDoc is closer to Markdown than LaTeX is, so hand conversion is cheaper. The main translations:

• = Title → # Title, == Section → ## Section, === Subsection → ### Subsection
• * bullet (a single star) → - bullet (a dash) — optional, both render, but dash is canonical GFM
• . numbered → 1. numbered — sequential numbering, GFM auto-increments
• **bold** stays **bold**
• __italic__ → *italic*
• link:url[text] → [text](url)
• ---- fence blocks (with optional [source,language] attribute above) → triple-backtick fences with language hint
• NOTE: Something → > [!NOTE] Something (GFM admonition)
• include::file.adoc[] → has no MD equivalent. Either inline the included file or manually chain content.

A 10-page AsciiDoc document with moderate formatting takes 20–40 minutes to hand-convert. The killers are: admonitions in targets that don't support GFM callouts, tables (AsciiDoc tables are their own dialect — |=== fence, | cell | cell), and include:: directives (you'll need to track down every referenced file and paste it in manually).

The subtle trap is attribute substitution. {product-name} in AsciiDoc source gets replaced at build time with a value from the document attributes or a command-line flag. In Markdown there's no equivalent — you have to resolve attributes to literal values before migration or your output has {product-name} appearing in the rendered page.

Automated approach (our tool)

Our converter handles the core AsciiDoc subset. Paste your source, get Markdown out. The engine covers:

• Headers: = H1 through ==== H4 convert to # through ####
• Bullets: line-leading * becomes -
• Numbered lists: line-leading . becomes 1. (GFM auto-increments the rest)
• Italic: __x__ becomes *x*
• Links: link:url[text] becomes [text](url)
• Code fences: ---- delimiters on their own line become triple backticks (language attribute not preserved — add it yourself if needed)
• Admonitions: NOTE:, TIP:, WARNING:, CAUTION:, IMPORTANT: line prefixes become GFM admonition blocks with the matching type

What we don't cover: AsciiDoc's bespoke table syntax (|=== fences with cell alignment and formatting), include:: macros (you need to pre-inline included files), attribute references ({name} substitutions), block titles (.Figure: foo), and sidebar / example blocks. For highly structured documents that lean on these, use Asciidoctor's reducer + Pandoc path or the Asciidoctor-to-Markdown converter in the Asciidoctor project.

Our tool is aimed at the common path: prose-heavy documentation with occasional admonitions and code examples. Paste a README, a blog post, or a section of a user guide and the output will usually match the source one-to-one. Paste a full API reference with tables and cross-refs and you'll have significant post-processing to do.

Common gotchas

Language hints on code fences dropped. AsciiDoc often pairs ---- with a [source,javascript] attribute on the preceding line: [source,javascript]\n----\ncode\n----. Our engine converts the fence delimiter but drops the language attribute. If you need the language preserved for syntax highlighting, add it manually: ```javascript after the conversion.

Admonitions only in specific GFM targets. > [!NOTE], > [!TIP], etc. are GitHub Flavored Markdown admonitions. They render correctly on GitHub, in Obsidian (with Callouts plugin), and in some docs platforms. They render as plain blockquotes on platforms that don't recognize the admonition syntax. Check your target before relying on the styling.

**bold** stays unchanged, __italic__ converts. This quirk catches people. In AsciiDoc, **bold** is bold and __italic__ is italic — same as MD's bold, but different from MD's italic. Our converter leaves bold alone (it's already MD-compatible) but converts italic. Nothing is lost, but if your source uses double-underscore for other purposes (URLs with underscores), check for false positives.

Admonition content limited to one line. Our engine converts single-line NOTE: text to > [!NOTE] text. Multi-line admonition blocks in AsciiDoc (delimited with ==== around a NOTE: label) do not convert — only the label line triggers the admonition. Re-flow multi-line notes into single lines or hand-wrap them with > line prefixes after conversion.

Cross-references lost. <<section-id>> cross-refs in AsciiDoc become text in the output. If you want to preserve the reference, it needs to become [section label](#section-anchor) manually — Markdown uses URL-fragment anchors rather than named IDs, so the structure is different.

Monospaced inline code with +x+. AsciiDoc has a compact syntax for inline code: +code+ as well as `code`. Our converter preserves the backtick form (already GFM-compatible) but leaves +code+ as literal text. If your source uses the plus-delimited form, run a pre-conversion search-and-replace: +(.+?)+ → `$1`.

When to use Pandoc instead

Pandoc supports AsciiDoc as an input format with full parser coverage. For documents where you need tables, includes, cross-references, and attribute substitution preserved, Pandoc gives you a complete AST → GFM translation. The invocation is pandoc input.adoc -f asciidoc -t gfm -o output.md. Pandoc handles the hard parts our tool skips.

The Asciidoctor project itself also has an official converter, asciidoctor-reducer, that can flatten include:: directives before you hand off to any other tool. Pairing Asciidoctor reducer with Pandoc gives you the highest-fidelity AsciiDoc-to-Markdown path available: asciidoctor-reducer input.adoc -o reduced.adoc && pandoc reduced.adoc -f asciidoc -t gfm -o output.md.

Our browser-based tool exists for the paste-and-copy use case — when you've got a section of AsciiDoc, don't want to install anything, and just need the common patterns translated. For a full book manuscript, go to Pandoc.

Migration workflow

A workflow that covers most AsciiDoc migrations cleanly:

1. Survey your source. Run a count over your .adoc files for include::, |=== (tables), <<>> (cross-refs), and {name} (attribute refs). If any of these appear in more than a handful of places, plan to use Pandoc with Asciidoctor-reducer for structural content.
2. Normalize attribute substitution. For each {attribute} in your source, resolve it to its literal value (look up the definition in your document header or attributes file). Search-and-replace in the source before conversion.
3. Flatten include:: directives. If you have a master .adoc that pulls in sub-documents, either run asciidoctor-reducer (recommended) or manually inline the contents of each included file.
4. Convert the prose via our tool. Paste each document or section in, review the output. Headers, lists, admonitions, and links should come through correctly.
5. Handle tables separately. For each AsciiDoc table in your source, either hand-convert to a GFM pipe table (works if cells are simple) or use Pandoc for the specific document.
6. Restore code-fence languages. Walk through your output and add language hints to triple-backtick fences where the AsciiDoc source had them. Syntax highlighting depends on this.
7. Resolve cross-references. For each <<ref>> in the source, track down the anchor in the output and convert to [label](#anchor) — Markdown doesn't have native cross-references, but URL fragments work on most platforms.
8. Add frontmatter. If your destination is Jekyll or Hugo, prepend the per-file YAML block with title, date, and layout. Our tool doesn't generate frontmatter; that's a target-specific concern.
9. Preview the rendered output. Open the converted MD in your target (GitHub preview, Jekyll local server, Obsidian) and spot-check rendering. Admonitions are the most common thing to get wrong — verify each one displays the way you expect.

For a moderate-size AsciiDoc project (~20 documents, standard prose, a few tables), this workflow takes four to eight hours spread across conversion, table handling, and preview verification. The tool-assisted steps are fast; the value-add is that you can focus your time on structured content rather than line-by-line reformatting.