Skip to main content

Converting Markdown to AsciiDoc: A Practical Migration Guide

Learn how to convert Markdown to AsciiDoc, why AsciiDoc headings use equals signs, and how to migrate your docs into an Asciidoctor or Antora toolchain.

Published By Li Lei
#markdown #asciidoc #documentation #converters #asciidoctor

Converting Markdown to AsciiDoc: A Practical Migration Guide

Markdown is the default for README files, GitHub issues, and quick notes. It is simple, it is everywhere, and most people can read the raw text without rendering it. But once a project grows into a real documentation site or a printed book, Markdown starts to run out of room. That is where AsciiDoc takes over, and that is when you suddenly need to turn a pile of .md files into .adoc without retyping every heading by hand.

This guide walks through what AsciiDoc actually is, the specific syntax differences that trip people up, and how to migrate an existing Markdown documentation set onto an AsciiDoc toolchain.

What AsciiDoc is and why teams choose it

AsciiDoc is a plain-text markup language read by Asciidoctor, the Antora documentation framework, and a long list of technical book pipelines. O'Reilly publishes whole books from it. On the surface it looks a lot like Markdown: you write in a normal text editor, headings and code blocks are visible in the source, and there is no XML to wrestle with.

The difference is depth. Markdown gives you headings, lists, links, emphasis, and code fences, and that is roughly the whole vocabulary. AsciiDoc adds the machinery that long-form technical writing actually needs:

  • Admonitions like NOTE:, TIP:, and WARNING: that render as callout boxes
  • Includes so one master document can pull in dozens of files
  • Attributes for reusable variables like a product version or a download URL
  • Cross-references that link to a section anywhere in the book and survive renumbering
  • Conditional content that shows or hides blocks depending on the build target

None of those exist in standard Markdown. If your docs have outgrown a single page, AsciiDoc is usually the next stop, and the conversion is mechanical enough that a tool can do the heavy lifting.

The syntax differences that actually bite

Most of AsciiDoc reads close enough to Markdown that you can guess your way through. A handful of differences are not guessable, and those are the ones that produce broken output when you paste raw Markdown into a .adoc file.

The first and biggest one is headings. AsciiDoc marks heading level by the count of leading equals signs, the mirror image of Markdown's hash counts. A Markdown # H1 becomes a single = (the document title level), ## becomes ==, ### becomes ===, and so on down to ====== for an H6. Get the count wrong and Asciidoctor nests your sections in the wrong place, which is the classic off-by-one that breaks a table of contents.

The other reversals worth memorizing:

  • Links flip order. Markdown writes [text](url); AsciiDoc writes url[text], with the address first and the label in trailing square brackets.
  • Images use a macro: ![alt](pic.png) becomes image:pic.png[alt] inline, or image::pic.png[alt] as a standalone block.
  • Code fences are not just backticks. AsciiDoc wants a [source,lang] attribute line over a ---- delimited listing block.
  • Bold drops from **x** to a single *x*, and italic settles on _x_.

A worked example, input to output

Here is a small Markdown snippet of the kind you would lift straight from a README.

Input (Markdown):

# Install guide

Run the setup script below.

## Quick start

npm install toolora


See [the docs](https://toolora.com) for more.

Output (AsciiDoc):

= Install guide

Run the setup script below.

== Quick start

[source,bash]
----
npm install toolora
----

See https://toolora.com[the docs] for more.

Notice every transform at once: # Heading became = Heading, ## Quick start became == Quick start, the fenced block grew a [source,bash] attribute over a ---- listing, and the link reversed into https://toolora.com[the docs]. The Markdown to AsciiDoc converter does all of this in the browser as you type, and it leaves anything inside a code block byte-for-byte untouched, so a # comment or a * glob in a sample is never mistaken for a heading or bold.

Migrating a documentation set onto an AsciiDoc toolchain

I went through this myself when our team's runbooks lived in a Markdown editor but the operations portal was built on Antora, which only reads AsciiDoc. My first instinct was to fix the headings by hand, then I hit the second file and realized I would spend an afternoon swapping hashes for equals signs and reversing every link. Running each draft through the converter turned that afternoon into about ten minutes of paste, copy, and commit.

If you are doing the same migration, a sane order of operations is:

  1. Inventory the .md files that need to move. A repo that already mixes .md and .adoc and only builds AsciiDoc is the common case.
  2. Convert each file and drop the output into a matching .adoc name. The headings become equals-sign sections, fenced blocks become source listings, and image:: macros land intact.
  3. Spot-check the heading levels in the rendered output. This is where a mismatch shows up, and it is the one thing worth eyeballing.
  4. Wire up the AsciiDoc-only extras afterward. Once the bulk content is converted, you can layer in admonitions, includes, and attributes that Markdown never offered.

A few pitfalls to avoid. Do not expect Markdown hashes to keep working; Asciidoctor renders a stray # as literal text, not a heading. Do not leave links in [text](url) order, or they show up as plain text with visible brackets. And remember that a bare set of backticks does not delimit code in AsciiDoc the way it does in Markdown; you need the [source,lang] plus ---- form.

Where this fits with your other format conversions

Markdown is the hub that everything passes through. The same draft you push into AsciiDoc today might need to become a rendered web page tomorrow, or arrive from HTML someone pasted out of a wiki. If you are moving in the other direction or need a browser preview, the Markdown to HTML converter covers that hop, and the broader family of format converters means a single Markdown source can fan out to whatever your publishing pipeline expects.

The point of keeping Markdown as your authoring format and converting at publish time is that you never lock yourself into one renderer. Write once in the simple syntax everyone knows, then let the toolchain decide whether the final artifact is an Antora site, an Asciidoctor book, or a plain HTML page. AsciiDoc is simply the most capable target in that chain, and getting your content there should not cost you an afternoon of manual edits.

Made by Toolora · Updated 2026-06-13