AsciiDoctor

On opinionated AsciiDoctor cheat sheet for authoring HTML, by Jakub Holý

Structure

Document header

= Main Header (1)
Jakub Holý <holyjak@example.com> (2)
v1.2.3, 2021-09-29: my optional revision remark (3)
:author: Jakub Holý (4)
:email: <holyjak@example.com> (5)
:revnumber: 1.2.3 (6)
:revdate: 2021-09-29 (7)
:revremark: my optional revision remark (8)
(9)

Optional document title
Optional author line
Optional revision info (version, date, remark - each optional); can only be used if there is an author line. See revision Information
An alternative way to set the optional author name; see author info docs
An alternative way to set the optional author email
An alternative way to set the optional revision number (no 'v' prefix)
An alternative way to set the optional revision date
An alternative way to set the optional revision remark
Blank line that ends the document header

Attributes

Document attributes

Configure and turn on/off built-in features, built-in asset locations, set "variables" for reuse elsewhere in the document. See rules for values.

Most document attributes are set right under the main header / document title, some can be (re)set anywhere (e.g. sectnums):

= Document Title
:sectnums: // turn on a boolean attr
:!sectnums: // turn it off
:imagesdir: ./my/img/subdir/ // built-in attr. with a value
:my-homepage: https://holyjak.cz // a custom attribute

A reference to an attribute such as link:{my-homepage}[my www]
will be replaced with the value automatically.

See Document Attributes Reference for a full list.

Element attributes

Override the built-in settings of blocks, macros, or inline elements and add custom settings (e.g. id, CSS classes) by using attribute lists. Attributes are comma-separated and can be positional (come first) and/or named:

image:path[Image alt text,200,150]
image:path["Image alt text",height=150,width=200]

Values can be enclosed in double " or single ' quotes; only inside '…' do normal substitutions (basic formatting etc.) apply
Document attribute references such as {some-attr} are replaced with their values

For blocks and block elements, put the attributes on the preceding line:

[square]
* one
* two

Section Titles

sectnumlevels

sectnums

discrete

Section Titles

Mark titles with =:

= Document title (h1)
== Level 1 (h2)
...
====== Level 5 (h6)

To auto-number sections, turn on sectnums:

:sectnums:
:sectnumlevels: 2 (1)
== Numbered section
:!sectnums:
== Unnumbered again

Number section headings at levels 1 and 2. Optional, default: levels 1-3

To use a heading where sections are not allowed (e.g. inside a block), set the [discrete] attribute.

Paragraphs

Paragraphs' source

.Optional Title
Just text. Line breaks
ignored. but can be forced +
with a plus.

Another paragraph.

 A literal paragraph is indented

Paragraphs rendered

Optional Title

Just text. Line breaks ignored. but can be forced
with a plus.

Another paragraph.

A literal paragraph is indented

To pass inline text through unchanged to HTML, wrap with three +:

+++<div id=x>+++

Assign id and CSS class(es) (a.k.a. roles) to inline text

Roles = CSS classes can be assigned similarly as ID, see Links and anchors below.
Ex.: [.class.another]#some text#.

Text Formatting

apostrophes

quotes

superscript

line-through

monospace

italic

subscript

highlight

bold

underline

literal

Text Formatting

bold

*bold*

italic

_italic_

both

*_both_*

monospace

`mon**os**pace` - formatting applies

li**t**eral monospace

`+li**t**eral+` - add + to suppress formatting etc.

bold code

double to stop mid-word: **b**ol__d__ c``od``e

highlight

#highlight#

underline

[.underline]#underline#

line-through

[.line-through]#line-through#

txt

assign arbitrary css class: [.my-class]#txt#

^superscript

^super^script

_subscript

~sub~script

“double curved quotes”

"`double curved quotes`"

‘single curved quotes’

'`single curved quotes`'

apostrophes’ vs x'

apostrophes`' vs x'

Blocks and admonitions

TIP

WARNING

NOTE

IMPORTANT

CAUTION

Admonitions

Admonitions' source

NOTE: An admonition *paragraph* draws
attention to auxiliary information.

[NOTE]
====
* An admonition *block* may contain
  complex content.
====

Admonitions rendered

Note	An admonition paragraph draws attention to auxiliary information.

Note	An admonition block may contain complex content.

All admonitions: NOTE, TIP, IMPORTANT, WARNING, CAUTION.

passthrough

example

pass

sidebar

open_block

quote

source_code

role

id

opts

options

Blocks

General structure of a block:

.Optional title
[optional attributes]
<separator (2 or 4 characters)>
<content>
<separator>

block type separator, attributes, comments

source code

----; attributes: [source,ruby]

source code (markdown)

```<language> ... ```

sidebar

****

example

====; expandable¹: [%collapsible], closable: [%collapsible%open]

quote

____; attributes: [quote, Author, Source]²

quote, alternative

"Text in quotes", on a new line -- Author, Source

open¹

-- An anonymous container; can masquerade as any other by naming it: [source|...]

passthrough

++++, pass content unchanged; e.g. to include HTML

The expandable example block and open block may contain other blocks
Wrap the quote source in ' to enable basic AsciiDoc such as links

Common block attributes: id (or #), role (or .) = css class, options (or opts for short or the repeatable %<name>). Example of all, using the shorthand forms: [quote#roads.movie.class2%fakeOpt, Dr. Emmett Brown].

Source code listing

[source]
----
clojure, SQL     ;  <1>
C-like           // <2>
Python etc.      #  <3>
XML              <!--4-->
# Include from a file, specific lines only (-1 = until the end):
include::filename.txt[lines=7;14..25;30..-1]

# or include regions between tags; also, un-indent:
include::lib/app.rb[tag=mytag,indent=0]
----
<1> callout
<2> callout
<3> callout
<4> callout

When including regions by tags, mark them using line comments like these:

# tag::mytag[]
...
# end::mytag[]

See include-with-indent, include-tagged-regions and include-lines.

Lists

(Un)ordered lists source

* Level 1 item of an unordered list
** Level 2, ... up to 5
   *** Lists can be indented. Leading whitespace isn't significant.
   . Nested level 1 ordered list item
   .. ordered list item 2nd level
+
====
To include complex content, unindent it and
put the list continuation sign `+` on the line
between it and the list item
====
   .. but a literal paragraph does not require a list
      continuation:

   $ echo "it works"

   .. end

[]
. To split a list into 2, put an empty line and a
block attribute line (possibly empty) before the second list

(Un)ordered lists rendered

Level 1 item of an unordered list
- Level 2, … up to 5
  - Lists can be indented. Leading whitespace isn’t significant.
    
    Nested level 1 ordered list item
    
    ordered list item 2nd level
    
    To include complex content, unindent it and put the list continuation sign + on the line between it and the list item
    
    but a literal paragraph does not require a list continuation:
    
    $ echo "it works"
    
    end

To split a list into 2, put an empty line and a block attribute line (possibly empty) before the second list

Other list types source

.Checklist
* [ ] unchecked
* [x] checked

.Definition list
First term:: the definition
can be inline
Second term::
or on a new line

.Q&A is a def. list with
the `qanda` attribute
[qanda]
Question:: Answer

Another question::
Its answer

Example 1. Other list types rendered

Checklist

❏ unchecked
✓ checked

Definition list

First term: the definition can be inline
Second term: or on a new line

Q&A is a def. list with

the qanda attribute

Question

Answer
Another question

Its answer

Links and anchors

Anchors

Block or a section heading: use a block anchor [[myid]] or the shorthand form [#myid] in the first position of the block attribute list.

Inline, on quoted text using either formatting marks such as * or put # around the text: [#inline_target]#targeted# txt. Or just insert an empty anchor: [[empty-anchor]]not inside.

Anchors can be used anywhere where macro substitution applies.

Links

Link to an anchor via <<myid>>, which will use the target text as the label (only works for headings), or <<myid,custom label>>. You can also link directly to a section heading using its text: <<Links>>.

Links to anchors:

<<heading-anchor>>, <<inline_target>>

Links, [inline_target]

<<heading-anchor,my label>>

my label

<<Links>> - heading text

Links

External links:

http://xy.z

http://xy.z

http://xy.z[label]

label

link:/some/path[path only]

path only

Beware: Some URLs look like formatting and confuse the parser. To fix, wrap like this link:++the-url++ or assign it to an attribute and use that.

Supported attributes: id, role (= CSS class), title, window (or append ^ to the label for _blank), opts.

Images

imagesdir

Images

Block image: image::<path|url>[<attributes>] (prepend a .block title line for a caption)

Inline image: same as block image, but single :

Positional attributes: [alt, width, height]. W/h are numbers in px or %: 150 or 50%.

Named attributes (¹ applies only to block images):

Positioning: align¹=left|center|right, float=left|right (adds CSS style with float), role (built-in classes: left, right, text-left, text-right, text-center; note: .role shorthand not supported)
Add a frame: role="thumb" (as thumbnail)
link

Note: The document attribute imagesdir (default: empty) is automatically prepended to all relative paths.

Tables

autowidth

Tables

Table source

[cols="20,80"]
|===
| Country | City

| Norway  | Oslo
| Czechia | Ostrava

| footer  | after empty line
|===

Example 2. Table rendered

Country

City

Norway

Oslo

Czechia

Ostrava

footer

after empty line

Make first line header by appending an empty line
Options include %autowidth
See sizing, alignment via cols, CSV data etc.

Extra

footnote

appendix

icons

hr

escape

substitutions

comment

macro

Extra

Comments: // comment here
Macros: block (::) or inline (:): <macro name>::<target>[<attrs>]
Escape by prepending \ or wrapping with +++...+++ or use the pass inline macro pass:[whatever]
''' ⇒ <hr>
Footnote: footnote:<optional id>[text]
Appendix: prepend a line with [appendix]
How to enable icons for admonitions, callouts, and the icon macro
Substitutions, where they apply; types: special char. (<, >, & → < etc.), quotes, attribute {references}, replacements (e.g. (R), €, † ⇒ ®, €, †; Unicode escape sequence yet unsupported), macros, post-replacements (the line break char. +)

Notes

Open cheat sheet source