Quadhelion Engineering Advanced Asciidoc Cheatsheet. Includes .adoc used to generate this page and PDF formatted version.
= AsciiDoc Advanced Syntax Cheatsheet (C) Elias Griffin <elias@quadhelion.engineering> v1.0.2, 2026-02-16 :homepage: https://www.quadhelion.engineering :url-home: https://www.quadhelion.engineering/articles.html :guides-home: https://www.quadhelion.engineering/guides.html :license: Copyrighted, Elias Christopher Griffin, Quadhelion Engineering, 2024 © :toc: left :sectanchors: :sectlink: :experimental: :imagesdir: images :sourcedir: /home/wravoc/www/quadhelion.engineering/guides :source-highlighter: rouge :icons: font :link-docs: https://asciidoctor.org/docs[documentation] :summary: Quadhelion Engineering Advanced Asciidoc Cheatsheet. Includes .adoc used to generate this page and PDF formatted version.
| All header configs are optional and it may not contain any empty lines and must be separated from the content by at least one empty line. |
- Editors
-
-
Pluma
-
Geany
-
Cosmic Editor
-
Export
ruby --version gem install asciidoctor asciidoctor-pdf rouge // Export to HTML with same file name asciidoctor AsciiDocCheatSheet.adoc // Export to PDF asciidoctor-pdf AsciiDocCheatSheet.adoc
Comments
// A single-line comment //// A multi-line comment. With two lines. ////
Escaping
In /items/\{id}, the id attribute isn't replaced.
\*Stars* isn't displayed as bold text.
\§ appears as an entity reference.
Single and double plus inline passthroughs
A word or phrase between single pluses, such as +/user/{id}+, is not substituted. However, the special characters like +<+ and +>+ are still escaped in the output.
An attribute reference within a word, such as dev++{conf}++, is not replaced.
A plus passthrough will escape standalone formatting marks, like +``+, or formatting marks within a word, like all-natural++*++.
Triple plus inline passthrough and inline pass macro
+++<u>underline me</u>+++ is underlined. pass:[<u>underline me</u>] is also underlined
Text
- Page format
-
-
Horizontal Rule
'''
-
-
Page Break
<<< -
Line break <space>+
Definitions
First term:: The description can be placed on the same line as the term. Second term:: Description of the second term. The description can also start on its own line.
- First term
-
The description can be placed on the same line as the term.
- Second term
-
Description of the second term. The description can also start on its own line.
| Style | Syntax | Style | Syntax |
|---|---|---|---|
bold |
*bold* |
Single arrow |
-> |
italic |
_slanted_ |
Double arrow |
=> |
bold+italic |
*_both_* |
Em dash |
-- |
code |
`ls` |
super |
c^2^ |
inline |
un__real__ |
sub |
H~2~O |
highlight |
#in yellow# |
Copyright |
(C) |
underline |
[.underline]#this# |
Registered |
(R) |
strike |
[.line-through]#that# |
Trademark |
(TM) |
| Any named, numeric or hexadecimal XML character reference is supported. |
Lead paragraph
[.lead] This text will be styled as a lead paragraph (i.e., larger font).
Links, mailto, IRC
link:index.html[Docs] https://asciidoctor.org https://asciidoctor.org[Asciidoctor] devel@discuss.example.org mailto:devel@discuss.example.org[Discuss] irc://irc.freenode.org/#asciidoctor https://chat.asciidoc.org[Discuss AsciiDoc,role=external,window=_blank] https://chat.asciidoc.org[Discuss AsciiDoc^] link:++https://example.org/?q=[a b]++[URL with special characters]
Section titles
When the document type is article (the default), the document can only have one level 0 section title (=), levels cannot be skipped when nesting sections.
= Document Title (Level 0) == Level 1 Section Title === Level 2 Section Title ==== Level 3 Section Title ===== Level 4 Section Title ====== Level 5 Section Title == Another Level 1 Section Title
[discrete] ==== I'm an independent heading! This paragraph is it's sibling, not it's child.
Anchors
Block Anchors
Make the reference
[#anchor1] Anchor 1, a paragraph or a list, or a table.
Use the reference
<<anchor1>>
A link to <<anchor1>> in text.
* List Item 1 * List Item 2 * <<anchor1>>
.Scores [cols=",",options="header",] |=== | Factor | Value | Threats | 9.8 | Vulnerability | 7.75 | Impact | 9.80 | Entrenched | 22.67 | Integration | 10.50 | Exploit Chain | 18.27 | Anchor1 | <<anchor1>> |===
Inline
[[bookmark-a]]Inline anchors#asciidoctor [#bookmark-b]#Inline anchors can be applied to a phrase like this one highlighted in yellow.# anchor:bookmark-c[]Use a cross reference to link to this location. [[bookmark-d,last paragraph]]The xreflabel attribute will be used as link text in the cross-reference link.
Use the inline anchor
Be sure to visit <<bookmark-a>>
Cross references
Section Titles like <<Code>> are automatically recognized
Cross reference in another document
Refer to xref:AsciiDocCheatSheet2.adoc#Code
Include other documents or documents from URLs
include::AsciiDocCheatSheet.md[] include::AsciiDocCheatSheet.md[lines=5..10] include::https://raw.githubusercontent.com/wravoc/authlog-threats/main/docs/SECURITY.md[]
| Content from a URL is potentially dangerous, so it’s disabled if the safe mode is SECURE or greater. Assuming the safe mode is less than SECURE, you must also set the allow-uri-read attribute to permit the AsciiDoc processor to read content from a URL. |
Assign ID (anchor) and role to inline formatted text
[#id-name.role-name]`monospace text` [#free-world.goals]*free the world*
Functions
You must enable :experimental: in the header
|
Menu Simulation
To save the file, select menu:File[Save]. Select menu:View[Zoom > Reset] to reset the zoom level to the default setting.
Button Simulation
Press the btn:[OK] button when you are finished. Select a file in the file navigator and click btn:[Open].
Images
image::sunset.jpg[] image::sunset.jpg[Sunset, align="center"] .A mountain sunset [#img-sunset,caption="Figure 1: ",link=https://www.flickr.com/photos/javh/5448336655] image::macros:sunset.jpg[Sunset,200,100] image::https://asciidoctor.org/images/octocat.jpg[GitHub mascot] Click image:play.png[] to get the party started. Click image:pause.png[title=Pause] when you need a break. image:sunset.jpg[Sunset,150,150,role=right] What a beautiful sunset!
Code
Indent one space to auto format for code
` or use backticks `
``` or use triple backticks for multiple lines ```
Output literal monospace text
Like {backtick} or http://localhost:8080 by enclosing the text in a pair of pluses surrounded by backticks.
Like `++{backtick}++` or ++http://localhost:8080++ by enclosing the text in a pair of pluses surrounded by backticks.Code Block Examples
.Gemfile.lock
----
GEM
remote: https://rubygems.org/
specs:
asciidoctor (2.0.15)
PLATFORMS
ruby
DEPENDENCIES
asciidoctor (~> 2.0.15)
----
.Some Ruby code [source,ruby] ---- require 'sinatra' get '/hi' do "Hello World!" end ----
Code with steps
[source,ruby] ---- require 'sinatra' <1> get '/hi' do <2> "Hello World!" <3> end ---- <1> Library import <2> URL mapping <3> HTTP response body
require 'sinatra' (1)
get '/hi' do (2)
"Hello World!" (3)
end| 1 | Library import |
| 2 | URL mapping |
| 3 | HTTP response body |
Lists
Unordered List
* List item ** Nested list item *** Deeper nested list item * List item ** Another nested list item * List item
An empty line is required before and after a list to separate it from other blocks. You can force two adjacent lists apart by adding an empty attribute list (i.e., []) above the second list or by inserting an empty line followed by a line comment after the first list. If you use a line comment, the convention is to use //- to provide a hint to other authors that it’s serving as a list divider.
Ordered list
. Level 1 list item .. Level 2 list item ... Level 3 list item .... Level 4 list item ..... Level 5 list item . Level 1 list item
Checklist
* [*] checked * [x] also checked * [ ] not checked * normal list item
Question and answer list
[qanda] What is the answer?:: This is the answer. Are cameras allowed?:: Are backpacks allowed?:: No.
-
What is the answer?
This is the answer.
-
Are cameras allowed?
Are backpacks allowed?
No.
Advanced Mixed List
Operating Systems::
Linux:::
. Fedora
* Desktop
. Ubuntu
* Desktop
* Server
BSD:::
. FreeBSD
. NetBSD
Cloud Providers::
PaaS:::
. OpenShift
. CloudBees
IaaS:::
. Amazon EC2
. Rackspace
| Lists can be indented. Leading whitespace is not significant. List continuation operator + (plus) sign |
* AsciiDoc lists may contain any complex content. |=== |Column 1, Header Row |Column 2, Header Row |Column 1, Row 1 |Column 2, Row 1 |===
Audio Video
audio::ocean-waves.wav[] audio::ocean-waves.wav[start=60,opts=autoplay] video::video-file.mp4[] video::video-file.mp4[width=640,start=60,opts=autoplay] video::RvRhUHTV_8k[youtube] video::67480300[vimeo]
Labels
NOTE: An admonition draws the reader's attention to auxiliary information. IMPORTANT: Don't forget the children! TIP: Look for the warp zone under the bridge. CAUTION: Slippery when wet. WARNING: The software you're about to use is untested. IMPORTANT: Sign off before stepping away from your computer.
Label block
[NOTE] ==== An admonition block may contain complex content. .A list - one - two - three Another paragraph. ====
Blockquotes
[quote,Abraham Lincoln,Address delivered at the dedication of the Cemetery at Gettysburg] ____ Four score and seven years ago our fathers brought forth on this continent a new nation... ____ [quote,Albert Einstein] A person who never made a mistake never tried anything new. ____ A person who never made a mistake never tried anything new. ____ [quote,Charles Lutwidge Dodgson,'Mathematician and author, also known as https://en.wikipedia.org/wiki/Lewis_Carroll[Lewis Carroll]'] ____ If you don't know where you are going, any road will get you there. ____ "I hold it that a little rebellion now and then is a good thing, and as necessary in the political world as storms in the physical." -- Thomas Jefferson, Papers of Thomas Jefferson: Volume 11
Tables
Simple Table, ignores spacing, very writeable, readable
.Scores [cols=",",options="header",] |=== | Factor | Value | Threats | 9.8 | Vulnerability | 7.75 | Impact | 9.80 | Entrenched | 22.67 | Integration | 10.50 | Exploit Chain | 18.27 | Potency | 27.11 |===
Table with a title, two columns, a header row, and two rows of content
.Table Title |=== |Column 1, Header Row |Column 2, Header Row |Cell in column 1, row 1 |Cell in column 2, row 1 |Cell in column 1, row 2 |Cell in column 2, row 2 |===
|
Unless the cols attribute is specified, the number of columns is equal to the number of cell separators on the first (non-empty) line. When an empty line immediately follows a non-empty line at the start of the table, the cells in the first line get promoted to the table header. |
Table with two columns, a header row, and two rows of content
[%header,cols=2*] |=== |Name of Column 1 |Name of Column 2 |Cell in column 1, row 1 |Cell in column 2, row 1 |Cell in column 1, row 2 |Cell in column 2, row 2 |===
|
The |
Table with three columns, a header row, and two rows of content
.Applications [cols="1,1,2"] |=== |Name |Category |Description |Firefox |Browser |Mozilla Firefox is an open source web browser. It's designed for standards compliance, performance, portability. |Arquillian |Testing |An innovative and highly extensible testing platform. Empowers developers to easily create real, automated tests. |===
In this example, the cols attribute has two functions. It specifies that this table has three columns, and it sets their relative widths. View result of Example 70
Table with column containing AsciiDoc content
[cols="2,2,5a"] |=== |Firefox |Browser |Mozilla Firefox is an open source web browser. It's designed for: * standards compliance * performance * portability https://getfirefox.com[Get Firefox]! |=== View result of Example 71 Example 72. Table from CSV data using shorthand ,=== Artist,Track,Genre Baauer,Harlem Shake,Hip Hop ,===
Table from CSV data
[%header,format=csv] |=== Artist,Track,Genre Baauer,Harlem Shake,Hip Hop The Lumineers,Ho Hey,Folk Rock |===
Table from CSV data included from file
,=== `include::customers.csv[]` ,===
Table with formatted, aligned and merged cells
[cols="e,m,^,>s",width="25%"] |=== |1 >s|2 |3 |4 ^|5 2.2+^.^|6 .3+<.>m|7 ^|8 |9 2+>|10 |===
1 |
2 |
3 |
4 |
5 |
|
|
|
8 |
|||
9 |
|
||
Shorthand method for assigning block ID (anchor) and role
[#goals.incremental] * Goal 1 * Goal 2
| To specify multiple roles using the shorthand syntax, delimit them by dots. The order of id and role values in the shorthand syntax does not matter. |
Shorthand method for assigning block options
// options can be shorted to opts [opts="header,footer,autowidth"] |=== |Header A |Header B |Footer A |Footer B |===
Bibliography
_The Pragmatic Programmer_ <<pp>> should be required reading for all developers. To learn all about design patterns, refer to the book by the "`Gang of Four`" <<gof>>. [bibliography] == References * [[[pp]]] Andy Hunt & Dave Thomas. The Pragmatic Programmer: From Journeyman to Master. Addison-Wesley. 1999. * [[[gof,gang]]] Erich Gamma, Richard Helm, Ralph Johnson & John Vlissides. Design Patterns: Elements of Reusable Object-Oriented Software. Addison-Wesley. 1994.
Footnotes
A statement.footnote:[Clarification about this statement.] A bold statement!footnote:disclaimer[Opinions are my own.] Another bold statement.footnote:disclaimer[] A statement.[1] A bold statement![2] Another bold statement.[2] 1. Clarification about this statement. 2. Opinions are my own.
Embedded Data
:data-uri: image/gif;base64,R0lGODlhEAAQAMQAAORHHOVSKudfOulrSOp3WOyDZu6QdvCchPGolfO0o/XBs/fNwfjZ0frl3/zy7////ViFIDlTImbKC5Gm2hB0SlBCBMQiB0UjIQA7
| When the data-uri attribute is set, all images in the document—including admonition icons—are embedded into the document as data URIs. You can also pass it as a command line argument using -a data-uri. |