Introduction
There are two kinds of text editors: those in which "what you see is what you get" (WYSIWYG) and those in which plain text is being used. An example for the first one is Microsoft Office and for the second one any text editor which is being used for any of the major programming languages. When the text is expressed in plain text, then there is some tool which compiles the plain text with its formatting instructions into documents targeted at the readers, e.g. websites or PDF documents. Asciidoctor is one of such tools.
Installation
Asciidoctor is a tool which can be used from the commandline. It is installed with the page manager of the programming language Ruby:
sudo gem install asciidoctor (1)
asciidoctor --help (2)| 1 | This is the command which needs to be copied into the terminal to install Asciidoctor. |
| 2 | By calling asciidoctor with the --help flag we can check that it has been installed properly. |
Hello, World
Here is how the simplest possible AsciiDoc file looks like:
= Hello, World (1)
Lorem ipsum dolor sit amet.| 1 | A line starting with an equals sign followed by a whitespace and then some text will be interpreted as a first level headline. |
This file can be compiled like this into an HTML document:
asciidoctor hello-world.adocAfterwards there will be an HTML file called hello-world.html residing next to it in its directory.
<!DOCTYPE html>
<html lang="en">
<head>
<meta charset="UTF-8">
<meta http-equiv="X-UA-Compatible" content="IE=edge">
<meta name="viewport" content="width=device-width, initial-scale=1.0">
<meta name="generator" content="Asciidoctor 2.0.10">
<title>Hello, World</title>
<link rel="stylesheet" href="https://fonts.googleapis.com/css?family=Open+Sans:300,300italic,400,400italic,600,600italic%7CNoto+Serif:400,400italic,700,700italic%7CDroid+Sans+Mono:400,700">
<style>
(1)
</style>
</head>
<body class="article">
<div id="header">
<h1>Hello, World</h1> (2)
</div>
<div id="content">
<div class="paragraph">
<p>Lorem ipsum dolor sit amet.</p> (3)
</div>
</div>
<div id="footer">
<div id="footer-text">
Last updated 2020-02-14 17:12:11 +0100
</div>
</div>
</body>
</html>| 1 | The generated CSS code has been left out for the sake of brevety |
| 2 | Here is the example headline |
| 3 | Here is the example text |
Editor plugin
For most text editors there are plugins available which display the AsciiDoc files with syntax highlighting. Further they may provide additional functionality like a live preview of the final document.
Here is for example how the AsciiDoc plugin can be enabled for the text editor VS Code:
(1) Go to the menu item "View > Extensions"
(2) Type in "AsciiDoc" in the search field and submit the search by hitting the return key
(3) Click on the install button
Basics
Headlines
Headlines are indicated with an equal sign, followed by a whitespace and then the text of the headline. The nesting level of the headline can be controlled with the number of subsequent equal signs.
= Document Title
== First section
Lorem ipsum dolor sit amet, consectetur adipiscing elit, sed do eiusmod tempor incididunt ut labore et dolore magna aliqua.
=== First sub-section
Ut enim ad minim veniam, quis nostrud exercitation ullamco laboris nisi ut aliquip ex ea commodo consequat.
=== Second sub-section
Duis aute irure dolor in reprehenderit in voluptate velit esse cillum dolore eu fugiat nulla pariatur.
==== First sub-sub-section
Excepteur sint occaecat cupidatat non proident, sunt in culpa qui officia deserunt mollit anim id est laborum.
== Second section
Feugiat in ante metus dictum at tempor commodo. Quis viverra nibh cras pulvinar mattis nunc sed.
=== First sub-section
Eu volutpat odio facilisis mauris.| Except for the first one, there needs to be an empty line before the headline. |
Formatting
| Click here for the description of this topic in the Asciidoctor User Manual. |
Here is an example how you can make text bold and italic:
Egestas **erat** imperdiet _sed_ euismod nisi porta lorem mollis.The rendered result will look like this:
Egestas erat imperdiet sed euismod nisi porta lorem mollis.
Links
| Click here for the description of this topic in the AsciiDoc Syntax Quick Reference. |
Intermediary
Table of contents
| Click here for the description of this topic in the AsciiDoc Syntax Quick Reference. |
Tables
| Click here for the description of this topic in the AsciiDoc Syntax Quick Reference. |
Images
| Click here for the description of this topic in the AsciiDoc Syntax Quick Reference. |
Source code
| Click here for the description of this topic in the AsciiDoc Syntax Quick Reference. |
Sections in the document formatted as source code can be added like this:
[source]
----
print("Hello, World!")
----This will then look like this in the rendered document:
print("Hello, World!")Advanced
Source code with syntax highlighting
| Click here for the description of this topic in the Asciidoctor User Manual. |
Before we can render HTML documents with syntax highlighting for source code snippets, we need to install a plugin via the terminal:
sudo gem install rougeAnother pre-condition before this is working is that we set the attribute :source-highlighter: with this plugin as value. This has to be somewhere before the source code snippet, e.g. right after the document title:
= Hello, World
:source-highlighter: rougeWith some additional information around the source code snippet we can enable syntax highlighting in the rendered document:
.hello-world.py (1)
[source, python] (2)
----
print("Hello, World!")
----| 1 | This will create a caption above the source code block |
| 2 | Separated with a comma from the source keyword, we can mark the snippet e.g. as Python program |
This will then look like this in the rendered document:
print("Hello, World!")However, there are two pre-conditions before this works. (1)
Callouts
| Click here for the description of this topic in the Asciidoctor User Manual. |
Include AsciiDoc snippets
| Click here for the description of this topic in the Asciidoctor User Manual. |
When AsciiDoc documents start to become very long it may make sense to save some sections in separate files. This is the same idea which is also used for programming: from the point of view of the computer, the complete program could be written in a single text file, but in order to make it understandible for the human mind it is split into a number of separate file which are then aggregated when the program gets compiled.
Here is how another AsciiDoc file can be embedded into another:
include::example-section.adoc[]Like in HTML pages, the reference to the embedded file is relative to the current file. Assuming that next to the current file there is a directory called "chapter_01" and therein is a file called "example-section.adoc", then this file can be embedded like this:
include::chapter_01/example-section.adoc[]Include source code snippets
| Click here for the description of this topic in the Asciidoctor User Manual. |
Let’s say we have the following Python script:
def greet_world():
print("Hello, World!")
def greet_person(name):
print("Hello, {}!".format(name))
if __name__ == '__main__':
greet_world()
greet_person("Carl")But in the documentation we only want to include the greet_person function, maybe because we are writing a tutorial about the usage of formatted strings with Python.
Then we can create a tagged region in the script like this:
def greet_world():
print("Hello, World!")
# tag::greet_person[]
def greet_person(name):
print("Hello, {}!".format(name))
# end::greet_person[]
if __name__ == '__main__':
greet_world()
greet_person("Carl")To include only this tagged region, we have to use the parameter tag:
[source, python]
----
include::greetings.py[tag=greet_person, indent=0]
----The embedded tagged region will then look like this in the final document:
def greet_person(name):
print("Hello, {}!".format(name))