= 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?
AsciiDoc Writing Guide
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:
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 or monospace
:
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 |
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:
-
First item. We will start with this.
-
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.
Have a look, this is how the result looks like.
Links
There are three ways how to create link from one document to another document:
-
xref
is used to link to other document in the same site. Pointxref
to the source file that you want to link to. E.g. if theother-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 ofother-document.adoc
is published. Jekyll will also check the link is valid, that the target document exists. -
link
may be used to link to anything. Unlikexref
, thelink
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 relativelink:
if the target is part of the docs. -
http
orhttps
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 |
---|---|
|
ToC at the top of the document, right after the main title. |
|
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. |
|
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.