AsciiDoc → Markdown
Convert basic AsciiDoc into Markdown.
Overview
The AsciiDoc-to-Markdown converter rewrites common AsciiDoc markup into the Markdown flavour GitHub and most static site generators understand. Section titles, lists, inline emphasis, links, code blocks, and admonition notes all get translated so you can migrate documentation from Asciidoctor to MkDocs, Docusaurus, or plain GitHub READMEs.
It's useful when a team is consolidating docs onto a Markdown-based platform but still has years of .adoc source to bring along. Technical writers and developers use an asciidoc converter to bulk-port pages without rewriting every heading and code fence by hand.
How it works
AsciiDoc and Markdown overlap heavily but diverge in syntax for headings, emphasis, and blocks. The converter maps = Title and == through ===== to #–#####, *bold* to **bold**, _italic_ to *italic*, and +monospace+ to `monospace`. Source blocks fenced with [source,language] followed by ---- become fenced code blocks with the language hint preserved.
Unordered list markers */**/*** collapse to - at the appropriate indent, and ordered lists with . markers become 1.. Admonitions like NOTE: and WARNING: are turned into blockquotes with a bold label.
Examples
Input:
= Getting Started
== Install
[source,bash]
----
brew install foo
----
Output:
# Getting Started
## Install
```bash
brew install foo
Input: See the docs for details.
Output: See the docs for details.
Input: NOTE: Restart the service.
Output: > Note: Restart the service.
## FAQ
**Does it support AsciiDoc tables?**
Basic `|===` tables with header rows are converted to GitHub-flavoured pipe tables. Complex layouts with cell spans or formatting attributes fall back to a plain pipe table without spans.
**What about include directives and attributes?**
Includes (`include::file.adoc[]`) are left as-is with a comment marker so you can resolve them after conversion. Document attributes like `:toc:` are dropped since Markdown has no direct equivalent.
**Will inline cross-references survive?**
Anchors written as `<<id,label>>` become `[label](#id)`. Implicit IDs derived from heading text are not regenerated, so check anchor names if your site uses them in URLs.