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)
  1. Optional document title

  2. Optional author line

  3. Optional revision info (version, date, remark - each optional); can only be used if there is an author line. See revision Information

  4. An alternative way to set the optional author name; see author info docs

  5. An alternative way to set the optional author email

  6. An alternative way to set the optional revision number (no 'v' prefix)

  7. An alternative way to set the optional revision date

  8. An alternative way to set the optional revision remark

  9. 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
  1. 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

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

====; expandable1: [%collapsible], closable: [%collapsible%open]

quote

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

quote, alternative

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

open1

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

passthrough

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

  1. The expandable example block and open block may contain other blocks

  2. 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[]

Lists

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.

        1. Nested level 1 ordered list item

          1. 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

          2. but a literal paragraph does not require a list continuation:

            $ echo "it works"
          3. end

  1. 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

  1. Question

    Answer

  2. Another question

    Its answer

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 (1 applies only to block images):

  • Positioning: align1=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

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. (<, >, & → &lt; etc.), quotes, attribute {references}, replacements (e.g. (R), &euro;, &#x2020; ⇒ ®, €, †; Unicode escape sequence yet unsupported), macros, post-replacements (the line break char. +)

Notes

Open cheat sheet source