AsciiDoc Writing Guide

Last modified 21 Mar 2024 18:17 +01:00

AsciiDoc is easy. Essentially, AsciiDoc file is just a simple text file. Special characters are used for formatting. It is perhaps best explained by using examples:

= Example Document

Quick brown fox jumped over lazy dog.
The dog did not like it at all.
Therefore the dog filed a *formal complaint* with animal rights commissioner.

This is a text of a second paragraph.
Do you know how much wood would a woodchuck chuck if woodchuck could chuck wood?

Headings

Headings start with one or more = characters. Document top-level heading starts with =. This top-level heading should be the first line of your document, because it also sets the heading for entire document. Second-level headings start with ==, third-level headings start with === and so on.

Paragraphs

Text paragraphs are written in a very ordinary way. Just write the text. Separate paragraphs with an empty line.

You can use special characters to format text as bold, italic, monospace or use some coloring:

Formatting Special character Asciidoc example Result

Bold text

*

This is really *important*, please pay attention!

This is really important, please pay attention!

Italic

_

This is a _de facto_ standard.

This is a de facto standard.

Monospace

`

Log in to the system as `administrator`.

Log in to the system as administrator.

Color

[color]#

We want some [blue]#color# in our text.

We want some color in our text.

Color and bold

[color]*

This is [red]*critical*.

This is critical.

Using single characters does not work at unexpected places, e.g. inside the word, but there is a trick to go around it - simply use two characters. E.g. half**bold**word produces "halfboldword".

Lists

It is easy to create lists in AsciiDoc. Just start the paragraph with * or .:

This is bullet list:

* This thing is not really improtant.
You can ignore it.

* That this is more important.

* Whatever. I do not care.

This is a numbered list:

. First item.
We will start with this.

. Second item. We will continue with this.

The formatting above will create following text:

This is bullet list:

  • This thing is not really improtant. You can ignore it.

  • That this is more important.

  • Whatever. I do not care.

This is a numbered list:

  1. First item. We will start with this.

  2. Second item. We will continue with this.

Simple Document Example

This is how a short document looks in AsciiDoc:

= AsciiDoc Fairy Tale

This is a nice short fairy tale.

== Introduction

Once upon a time there was a small kingdom.
The king was old and *very wise*.

== Getting to the Point

The king decreed that everybody in the kingdom should use `AsciiDoc`.
`AsciiDoc` looked very strange to the people of the kingdom, because they haven't seen anything but Microsoft _Word_ in their entire life.
That `AsciiDoc` thing looked difficult and ugly.
The people were not happy.
They complained.

But the king was wise and persistent.
He persuaded people to try `AsciiDoc`.
One by one the people started to understand the benefits of long-term maintainability and increased productivity, such as:

* Easy maintenance of the files in a _version control system_ (`gitlab`).

* Easy conversion of the documents to different formats (HTML, PDF, EPUB).

* No need to care about the styling details (font sizes, spacing, text flow) that break *all the time* in office text processors.

== Conclusion

Finally, the people understood.
And they lived happily ever after.

There are three ways how to create link from one document to another document:

  1. xref is used to link to other document in the same site. Point xref to the source file that you want to link to. E.g. if the other-document.adoc file is in the same directory, you can use:

    Please see xref:other-document.adoc[this other document] for the details.

    Jekyll will translate the xref to appropriate web link to point to correct URL where the content of other-document.adoc is published. Jekyll will also check the link is valid, that the target document exists.

  2. link may be used to link to anything. Unlike xref, the link needs URL instead of filename. Jekyll will not translate the URL, it will simply use the URL as you have provided it.

    Please see link:../other-document/[this other document] for the details.

    It is preferable to use xref: instead of relative link: if the target is part of the docs.

  3. http or https may be used in the same way as link is used. This is usually used when linking to other sites:

    Please see https://evolveum.com/[Evolveum website] for details.

When in doubt, use xref links for linking to the documents on the same site, and use http/https links when linking to documents on other sites. There is seldom a need for link links. However, the link was a preferred linking method in the past, therefore such links can be found in existing documents.

The part in the brackets ([…​]) is a link text. This text will be displayed in the document. When using xref link, the text may be left empty:

Please see xref:other-document.adoc[] for the details.

In that case the title of the linked document will be used as link text.

AsciiDoc Writing Conventions

It is nice to keep some conventions when writing AsciiDoc files. If you are writing simple notes or a similar short document you can ignore those conventions. But it would be nice to follow the conventions when writing more complex documents.

  • One sentence per line. Start every sentence on a new line. This has many advantages. It allows you to immediately see long sentences. It avoids text wrapping issues. It avoids text reflow problems. It may look strange, but you will quickly get used to it. And you will like it.

Table Of Contents

Document table of contents (ToC) can be automatically generated. This mechanisms if controlled by page-toc asciidoc variable:

= AsciiDoc Fairy Tale
:page-toc: top

This is a nice short fairy tale ...

The variable may contain several values, changing the stype of ToC:

page-toc value description

top

ToC at the top of the document, right after the main title.

float-right

ToC floating in a "frame" on the right side. The document text is wrapped on the left side. However, if the introduction is too short, the headings may not fit well.

float-left

ToC floating in a "frame" on the left side. Experimental.

Tables

Asiidoc supports formatting of tables, although the actual markup may look scary at first. It looks like this:

[%autowidth]
|====
| English | Slovak | Latin

| One
| Jeden
| Uno

| Two
| Dva
| Duo

| Three
| Tri
| Tres
|====

Which renders a table:

English Slovak Latin

One

Jeden

Uno

Two

Dva

Duo

Three

Tri

Tres

The |==== delimiters mark table boundaries.

First line specifies table header (English, Slovak and Latin). These have to be all on the same line, separated by pipes (|). Having them on the same line means that this is a header, otherwise the asciidoc would render it as a plain content.

Each row of the table is specified by a block of lines, each line starting with a pipe (|). There has to be at last one line for each column. There must be exact number of the lines starting with pipes to fill all the cells of the table.

The [%autowidth] at the beginning means that asciidoc will set column widths (and table width) automatically, based on the content of table cells. It is recommended to use the [%autowidth] for all ordinary tables. If you need a more sophisticated table column layout, there are many options to choose from.

Escaping and passthrouhgs

Sometimes you want to use special characters as if they are not special. What you need is to avoid the processing and substitutions. There is a couple of mechanisms to do that, depending on the scope of your need:

  • You can escape a single character using a backslash \. To escape double character (like **) use a double backslash \\. To escape the macro name use a single backslash. Read the docs for details how to escape more obscure cases.

  • Often easier is to use passthroughs. This comes in a block form for longer content. This is not needed that often as the typical content that needs it has other dedicated blocks like code, which already ignore most of the formatting anyway.

  • More interesting for our technical documentation is inline passthrough. This is done by pass:[left *alone*] which protects anything between [ and ]. If you nest another macro which uses ] inside, you can use \ to escape it so it doesn’t end the pass macro.

  • Pass macro can be used even in the middle of the word, which can be confusing; it is also quite verbose. Alternatively, you can surround the protected text with +, ++ or +++ with increasing "strength". Again, see the docs for more details.

"See Also" Section

It is a good idea to add a dedicated See Also section at the end of your document. Provide links for the reader to dig deeper, to follow up on related topics.

Was this page helpful?
YES NO
Thanks for your feedback