AsciiDoc Examples and Asciidoctor Basics: Cheat Sheet
November 11, 2026 · 11 min read
AsciiDoc Examples: Cheat Sheet, Asciidoctor and Markdown Conversion
These AsciiDoc examples cover the syntax you'll write every day, from document headers and attributes to tables, admonitions and includes, and each one says what it renders as. After the syntax, you'll install Asciidoctor, build HTML and PDF, pick an editor, and convert AsciiDoc to Markdown for platforms that won't take .adoc files.
What Is the Difference Between AsciiDoc and Asciidoctor?
AsciiDoc is the markup language. Asciidoctor is the processor that turns it into HTML, DocBook, PDF and other formats. According to the official AsciiDoc site, a language specification is in development, governed by the AsciiDoc Language project and, above it, the AsciiDoc Working Group at the Eclipse Foundation.
The reference processor is written in Ruby. AsciidoctorJ runs it on the JVM through JRuby, and Asciidoctor.js transpiles it to JavaScript for Node.js and the browser. The original Python tool, now called asciidoc-py, still exists, but current docs, editors and GitHub all follow the Asciidoctor dialect. AsciiDoc files use the .adoc extension. If you're new to the whole family of plain-text formats, Markdown vs markup explains where lightweight markup languages fit.
AsciiDoc Examples for Headers, Sections and Attributes
Every AsciiDoc document can start with a header: a title, an optional author and revision line, and attribute entries. The header can't contain blank lines, and a blank line must follow it.
= Acme CLI User Guide
Dana Reyes <dana@example.com>
v1.2, 2026-11-01
:toc:
:icons: font
:product: Acme CLI
[#setup]
== Getting started
{product} installs in under a minute.
=== Requirements
You need Ruby 2.7 or later.
This renders a document title, a byline with the author, version and date, and an automatic table of contents built from the sections. The {product} reference is replaced with "Acme CLI". :icons: font swaps text labels on admonitions for font icons.
Section levels run from = (the document title) through ====== (level 5). In Asciidoctor's HTML output, == becomes an h2, === an h3, and so on. The [#setup] line gives the section an explicit ID you can link to.
Without an explicit ID, Asciidoctor generates one from the title, such as _getting_started by default. GitHub changes the ID prefix and separator, so it produces getting-started instead. We prefer explicit IDs on any section you link to, because they survive a renamed heading and don't depend on each renderer's ID settings.
Define your own attributes with :name: value and reference them with the name in braces. An attribute can only be referenced after it's defined.
Inline Formatting, Links and Images in AsciiDoc
Inline formatting uses single marks for whole words and doubled marks inside words. The docs call these constrained and unconstrained pairs.
*bold*, _italic_ and `monospace`
**C**reate and fan__freakin__tastic
#highlighted text#
H~2~O and E=mc^2^
The first line renders bold, italic and code text. The second bolds only the "C" and italicises "freakin" mid-word, which single marks can't do. #text# renders as highlighted (an HTML mark element), and the last line produces a subscript 2 and a superscript 2.
A few more inline and line-level marks round out the set:
Roses are red, +
violets are blue.
This claim needs a source.footnote:[Per the project README.]
<<<
A space and a plus sign at the end of a line force a hard line break, so the two lines stay separate. The footnote: macro places a numbered marker in the text and collects the note at the bottom of the document. <<< on its own line is a page break, which matters in PDF and print output.
Links and images use macros: a target, then square brackets.
https://asciidoctor.org[Asciidoctor website]
link:install.html[Install guide]
See <<setup>> or <<setup,the setup section>>.
See xref:reference.adoc#cli-options[CLI options].
image::pipeline.png[Build pipeline,600]
Click image:play.png[Play,16] to start.
A bare URL followed by brackets becomes a link with that text. Use link: for relative paths. Double angle brackets point to an ID in the same document, while xref: crosses into another file. image:: with two colons is a block image (here 600 pixels wide), and image: with one colon sits inline in the sentence.
Lists, Tables and Source Code Blocks
Lists nest by repeating the marker rather than by indenting. That's the single biggest habit to unlearn if you come from other formats.
* Install Ruby
** Check the version
* Install the gem
//
. Write the file
. Build it
.. Open the HTML
//
* [x] Draft written
* [ ] Reviewed
//
CLI:: The command-line interface.
API:: The Ruby interface.
This renders a bulleted list with one nested item and a numbered list with a nested a. step. Then come a checklist with one checked box and a description list of terms. The lone // lines are comments. Without them, adjacent lists can fuse, because a different list marker after a blank line reads as a nested list.
Tables sit between |=== lines, and the attribute line above sets the columns.
[cols="1,3",options="header"]
|===
|Flag |What it does
|-o |Writes to a specific output file
|-D |Writes into a destination directory
|===
You get a two-column table with a header row, and the second column is three times as wide as the first. The Asciidoctor syntax quick reference links to the full table options, including CSV data and cell spans.
Source blocks take a language and can carry callouts:
[source,python]
----
import sys # <1>
print(sys.version) # <2>
----
<1> Loads the standard library module.
<2> Prints the interpreter version.
The code renders in a listing block with numbered markers, each tied to the explanation below it. Putting each callout behind a #, // or ;; line comment keeps the raw source valid code, and readers who copy from the HTML don't pick up the numbers.
Admonitions, Includes and Delimited Blocks
AsciiDoc has five admonition types: NOTE, TIP, IMPORTANT, CAUTION and WARNING. Use the short form for one paragraph and the block form for more.
NOTE: Asciidoctor needs Ruby to run.
[WARNING]
====
Don't install gems as root outside a container.
You can corrupt the system Ruby.
====
Each renders as a labelled callout box, or with an icon when :icons: font is set.
Includes pull other files into the document at build time. Tags let you pull just part of a file:
include::chapters/install.adoc[]
include::example.py[tag=setup]
In example.py, the region sits between # tag::setup[] and # end::setup[] comment lines. Asciidoctor resolves includes when you build locally. GitHub doesn't: it renders AsciiDoc in secure mode, so include directives aren't processed in the repository view. GitLab does resolve them, up to 32 per document by default.
Other delimited blocks wrap content in matching fences:
.Before you start
****
A sidebar for asides and background.
****
====
An example block for worked examples.
====
[quote,Project style guide]
____
Write one sentence per line.
____
// A single-line comment
////
A block comment that never renders.
////
The .Before you start line is a block title, shown above the sidebar. Comments never reach the output. GitHub also sets an env-github attribute, so content inside ifdef::env-github[] and endif::[] lines appears only there.
How Do I Install and Run Asciidoctor?
Install the Ruby gem, then check the version. The Asciidoctor install docs warn against running gem install as root unless you're in a container; use Bundler or a user-level Ruby manager instead.
gem install asciidoctor
asciidoctor --version
asciidoctor guide.adoc
asciidoctor -o site/index.html guide.adoc
asciidoctor -D build guide.adoc
asciidoctor -a toc=left guide.adoc
asciidoctor -b docbook5 guide.adoc
The plain asciidoctor guide.adoc writes guide.html next to the source, because HTML5 is the default backend. -o names the output file, and -D picks an output directory. -b docbook5 writes DocBook XML as guide.xml.
-a sets an attribute for that build only, and a command-line value overrides the one in the file. End the value with @, as in -a toc=left@, and the file's own setting wins instead. If you'd rather not install Ruby, Asciidoctor.js offers the same processor for Node.js projects.
How Do I Convert AsciiDoc to PDF?
PDF output comes from a separate gem, asciidoctor-pdf. It needs Ruby 2.7 or later (or JRuby 9.2 or later) and draws the PDF itself, so you don't need LaTeX or a browser.
gem install asciidoctor-pdf
asciidoctor-pdf guide.adoc
asciidoctor -r asciidoctor-pdf -b pdf guide.adoc
asciidoctor-pdf -a pdf-theme=basic -a pdf-themesdir=themes guide.adoc
The first two commands do the same thing and write guide.pdf next to the source. The last one applies a custom theme. The value basic resolves to themes/basic-theme.yml, and the file must end in .yml, not .yaml. The Asciidoctor PDF docs cover theme keys, fonts and page layout.
How Do I Convert AsciiDoc to Markdown?
Use pandoc 3.8.3 or newer. That release, dated 1 December 2025 in the pandoc changelog, added asciidoc as an input format. Before it, pandoc could only write AsciiDoc, so older answers saying it can't read .adoc files are out of date.
pandoc --version
pandoc -f asciidoc -t gfm guide.adoc -o guide.md
The gfm target produces GitHub Flavored Markdown, and the reader expects modern, Asciidoctor-style syntax. Conditional directives such as ifdef aren't handled yet, according to the README of the parser pandoc uses. On an older pandoc, take the DocBook detour: run asciidoctor -b docbook5 guide.adoc, then pandoc -f docbook -t gfm guide.xml -o guide.md. Our pandoc Markdown guide goes deeper on flags and extensions.
For README files, there's downdoc, a small Node.js converter from OpenDevise that never loads Asciidoctor. Running npx downdoc README.adoc produces README.md beside it. Expect gaps: it ignores include directives, supports only a subset of the syntax and wants LF line endings.
Proofread the output whichever tool you pick. Look first at the constructs from this AsciiDoc cheat sheet that plain Markdown can't express: admonition blocks, callout numbers and text that came from attributes. Our AsciiDoc vs Markdown comparison lists what gets lost in each direction.
Got a short snippet and no pandoc install? Paste it into our markup converter, which turns AsciiDoc into Markdown, and back, in your browser. It's a pragmatic line scanner rather than a full parser, so includes and other complex constructs aren't fully supported. Paste the result into the editor to proofread it in the live preview, keeping in mind that our editor renders Markdown, not AsciiDoc. From there, the Markdown cheat sheet is your syntax reference for the target format.
Which AsciiDoc Editor Should You Use?
For writing, a code editor with an AsciiDoc extension beats any dedicated app you'd have to learn. Two well-maintained options:
- VS Code: the AsciiDoc extension from the asciidoctor publisher adds a live preview, syntax highlighting and snippets, rendered with Asciidoctor.
- JetBrains IDEs: the AsciiDoc plugin for IntelliJ IDEA, RubyMine and other IntelliJ-platform IDEs gives a two-pane live preview based on Asciidoctor, plus a toolbar for basic formatting and tables.
For reading, GitHub renders .adoc, .asciidoc and .asc files in the repository view, and GitLab renders .adoc and .asciidoc. Keep the include limits above in mind: a document that relies on includes looks complete on GitLab but not on GitHub.
AsciiDoc File and Tooling Questions
Keep these AsciiDoc examples close while you write: set attributes in the header, give linked sections explicit IDs, and separate adjacent lists with a comment. Build HTML with Asciidoctor and PDF with its PDF converter. When a platform wants Markdown, use pandoc 3.8.3 or later. For short snippets, paste them into the markup converter and tidy the result by hand.