AsciiDoc vs Markdown: Syntax, Tooling and Conversion

November 11, 2026 · 11 min read

AsciiDoc vs Markdown: Which Markup Should You Write Docs In?

The AsciiDoc vs Markdown choice comes down to scope. Markdown is a small core, extended by flavors like GFM, and it renders almost everywhere. AsciiDoc is one larger language with includes, variables, conditionals and admonitions built in. Pick Markdown for READMEs, wikis and anything contributors edit casually, and AsciiDoc for manuals that reuse content or ship as PDF.

What Are the Key Differences Between ADOC and MD?

An .adoc file targets a single language with a reference processor, Asciidoctor. A formal AsciiDoc specification is in progress under the AsciiDoc Working Group at the Eclipse Foundation. An .md file is CommonMark plus whatever flavor your platform adds, usually GFM. If those layers are new to you, our CommonMark and GFM explainer covers them.

Many AsciiDoc vs Markdown comparisons, including the Asciidoctor project's own, measure AsciiDoc against plain Markdown and leave flavor features out. That's unfair to Markdown. Today's GFM has tables, task lists, strikethrough and autolinks, and GitHub adds heading anchors on top. The gap that's left is real, though, and it sits in a few specific features.

FeatureMarkdown (GFM)AsciiDoc (Asciidoctor)
StandardCommonMark spec plus GFMOne language, spec in progress
Headings# to ######= to ======
TablesPipe tables, inline cells onlySpans, widths, captions, block cells
AdmonitionsFlavor extensions (GitHub alerts)Five built in
IncludesNone in coreinclude:: with tags and line ranges
VariablesNone in coreDocument attributes
ConditionalsNoneifdef, ifndef, ifeval
OutputHTML via your renderer, more via pandocHTML5, DocBook 5, man pages; PDF and EPUB3 via add-ons
Where it rendersNearly everywhereGitHub, GitLab, Antora, Asciidoctor

Both are lightweight markup languages. For how they relate to HTML and other markup, see Markdown vs markup.

Headings, Emphasis and Links Side by Side

Here's the same short page in both formats. First, AsciiDoc:

= Install Guide

== Requirements

You need *Node 20* and _a terminal_.
See https://nodejs.org[the Node.js site] or jump to <<configure>>.

[#configure]
== Configure

And the Markdown version:

# Install Guide

## Requirements

You need **Node 20** and *a terminal*.
See [the Node.js site](https://nodejs.org) or jump to [Configure](#configure).

## Configure

Both render a title, two sections, bold "Node 20", italic "a terminal", an external link and a jump link. GitHub generates the #configure anchor from the Markdown heading automatically. In AsciiDoc, the [#configure] line sets an explicit ID that <<configure>> points to.

The trap for Markdown writers is the asterisk. In AsciiDoc, *text* is bold, while Markdown reads it as italic. AsciiDoc also splits formatting into constrained pairs (*word*, applied at word boundaries) and unconstrained pairs (**, used inside a word). That distinction is the biggest learning cost when you switch. Our AsciiDoc syntax cheat sheet shows both pair types in a working example.

Tables: GFM Pipes vs AsciiDoc Table Blocks

GFM pipe tables cover simple grids well. AsciiDoc tables are delimited blocks with a cols attribute, and they can span cells. Here's a release table with a caption, column widths and a final row that spans all three columns:

.Release support
[%header,cols="2,1,1"]
|===
|Version |Status |Support ends
|3.0 |Active |Not set
|2.4 |Security fixes |June 2027
3+|Versions before 2.0 are end of life.
|===

The .Release support line becomes the table's caption. The cols value makes the first column twice as wide, and 3+| stretches one cell across all three columns.

| Version | Status | Support ends |
|---|---|---|
| 3.0 | Active | Not set |
| 2.4 | Security fixes | June 2027 |

Versions before 2.0 are end of life.

The Markdown table renders the same two version rows, but it has no caption or width control. The spanning row has to leave the table as a paragraph. GFM cells hold inline content only, so a list or code block inside a cell needs raw HTML.

Admonitions, Includes and Attributes: What Markdown Lacks

This is where AsciiDoc earns its keep. A single source file can define variables, pull in shared fragments and switch content per platform:

:product: Acme CLI
:version: 3.0

NOTE: {product} {version} needs Node 20 or later.

include::shared/install.adoc[tag=linux]

ifdef::env-github[]
Browse the full docs site for search and navigation.
endif::[]

Asciidoctor substitutes {product} and {version} everywhere, renders a styled NOTE block, and inserts only the tagged linux region of the shared file. The ifdef block appears only when the env-github attribute is set, which GitHub does when it renders the file. The five built-in admonitions are NOTE, TIP, IMPORTANT, WARNING and CAUTION.

Markdown handles admonitions through flavor extensions. On GitHub you write an alert:

> [!NOTE]
> Acme CLI 3.0 needs Node 20 or later.

GitHub's alert syntax has the same five types. MkDocs Material uses !!! note and Docusaurus uses :::note, so the syntax changes with your tool. Includes and variables don't exist in core Markdown at all. You get them only from site-generator plugins, MDX imports or templating, and each one locks you to that tool.

Here's what portable Markdown gives you instead. The preview on the right renders standard GFM: the blockquote stands in for an admonition, and the task list shows as disabled checkboxes.

Release notes

Note: Plain blockquotes stand in for admonitions in core Markdown.

Feature Markdown AsciiDoc
Tables yes yes
Includes no yes
Attributes no yes
  • Draft in Markdown
  • Decide if you need includes
56 words272 characters12 lines
Markdown

Our editor renders Markdown only. It doesn't run Asciidoctor, and its preview doesn't render GitHub alert syntax, so check alerts on GitHub itself.

AsciiDoc vs Markdown on GitHub, GitLab and Docs Tooling

GitHub renders .adoc, .asciidoc and .asc files with Asciidoctor, but in secure mode, so include directives aren't processed. GitLab renders AsciiDoc and resolves includes, up to 32 per document by default, per the GitLab AsciiDoc docs.

Where you writeAsciiDocMarkdown
GitHub repository filesRenders, includes skippedRenders (GFM)
GitLab repository filesRenders, includes resolvedRenders
Issues, pull requests, commentsNot supportedSupported
Antora sitesNative formatNot supported
MkDocs, DocusaurusNo native supportNative format
HugoVia an installed AsciidoctorNative format

Because issues and pull requests on both platforms take Markdown only, even an AsciiDoc team writes Markdown whenever it files a bug or reviews code. Platform support often settles the markdown vs asciidoc question faster than syntax does.

On the docs side, Antora builds one site from AsciiDoc content stored across several Git repositories. Asciidoctor itself outputs HTML5, DocBook 5 and man pages, with PDF and EPUB3 from the asciidoctor-pdf and asciidoctor-epub3 add-ons. Markdown's strength is breadth: MkDocs, Docusaurus, Jekyll and most site generators take it. Choosing among those is covered in our guide to writing documentation in Markdown.

Who Uses AsciiDoc, and When Is It Worth the Learning Curve?

AsciiDoc shows up in large, long-lived documentation sets. The Spring Framework reference docs are .adoc pages built with Antora, and Git's own Documentation folder is written in AsciiDoc. Asciidoctor and Antora document themselves in it, too.

AsciiDoc pays off when you have:

  • one source that ships as a website, a PDF and an ebook
  • shared fragments reused across many pages or products
  • product variants that need conditional content
  • many repositories aggregated into a single docs site

Markdown wins for READMEs, wikis, blogs, changelogs and docs inside a Markdown site generator. It also wins when contributors already know it, which is nearly always. We prefer Markdown for anything people edit casually, and we switch to AsciiDoc only once we actually need includes or conditionals. If reStructuredText is also on your shortlist, see our Markdown vs reStructuredText comparison.

How Can I Convert an AsciiDoc File to a Markdown File?

Pandoc added AsciiDoc as an input format in version 3.8.3, released on 1 December 2025, per the pandoc changelog. The parser behind it doesn't support ifdef-style conditionals yet. Flatten the file first with Asciidoctor Reducer, which resolves includes and evaluates conditionals:

asciidoctor-reducer -o flat.adoc guide.adoc
pandoc -f asciidoc -t gfm flat.adoc -o guide.md

For a README-style file, downdoc converts without Asciidoctor at all: npx downdoc README.adoc writes README.md. It covers a subset of the syntax and drops include directives.

The reverse direction is older and well tested. Both of these produce AsciiDoc from Markdown:

pandoc -f gfm -t asciidoc guide.md -o guide.adoc
kramdoc -o guide.adoc guide.md

The kramdoc command comes from the kramdown-asciidoc gem. In our test with pandoc 3.8.2.1, a GitHub alert came out as a proper [NOTE] block and a pipe table became a |=== block.

What Gets Lost in Each Direction

No route is lossless, so review the output by hand. Going from AsciiDoc to Markdown:

  • Attributes are substituted, so {version} becomes a fixed value and stops being a variable.
  • Table spans, captions and column widths have no pipe-table equivalent.
  • Admonitions become blockquotes or flavor-specific alerts, depending on the tool.
  • Includes get inlined (pandoc, Asciidoctor Reducer) or dropped (downdoc), so shared fragments become copies.

Going from Markdown to AsciiDoc has its own surprises. In the same pandoc test, a <details> block lost its wrapper and its summary line, leaving the hidden text as a plain paragraph. A # Title heading became a == section rather than a = document title.

Links to headings need checking too. Pandoc turned [Configure](#configure) into link:#configure[Configure], but Asciidoctor's default ID for that heading is _configure. Set the idprefix attribute to empty, or add explicit IDs, and the link resolves.

For short snippets, our markup converter turns AsciiDoc into Markdown and back in your browser. Be clear about its limits: it's a pragmatic line scanner, not pandoc, so includes and complex blocks aren't fully supported. Paste the result into the editor to check it in the live preview.

Mixing the Two With Asciidoctor's Markdown-Compatible Syntax

You don't have to convert everything at once. Asciidoctor accepts some Markdown inside .adoc files: # headings, fenced code blocks, > blockquotes, and --- or *** thematic breaks. The AsciiDoc docs call this an optional part of the language that's currently available only in Asciidoctor.

So a team can rename a file from .md to .adoc and convert it gradually. Watch the parts that don't carry over. Markdown links and images need rewriting as AsciiDoc macros, and Markdown's *italic* comes out bold, as shown above. Pipe tables need rewriting as |=== blocks, too.

ADOC and MD Questions Writers Ask

In the end, AsciiDoc vs Markdown is about the features you'll actually use. If you don't need includes, attributes or conditional content, Markdown's reach across GitHub, chat tools and site generators wins. If you do, AsciiDoc saves real maintenance work. When you move content between them, use pandoc for full files and the markup converter for quick snippets, then check the Markdown in the editor.