AsciiDoc Writing Guide

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.

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 or monospace:

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

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

The formatting above will create following text:

This is bullet list:

This is a numbered list:

This is how a short document looks in AsciiDoc:

Have a look, this is how the result looks like.

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

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:

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

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.

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

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

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

Which renders a table:

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.

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:

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.