Quickstart AsciiDoc3

You want to use the power of the AsciiDoc(3)-Markup-Language?
There are many ways to take advantage of it:

  1. You want only HTML output?
    GNU/Linux goes here, Windows there

  2. You need HTML and/or PDF output?
    GNU/Linux goes here, Windows there [PENDING]

  3. You want everything - HTML + PDF + PDF (alternative route) + plain text + music notation + complex mathematical formulas + …?
    GNU/Linux goes here, Windows there [PENDING]

HTML output only (GNU/Linux)

  • Prerequisites: you need Python3.10 (or higher) installed on your machine. Probably all systems have this feature since they were installed.

  • Download the tarball asciidoc3_linux_latest, say into folder Downloads.

  • Create a new folder in your home directory, say ad3.

  • Deflate the tarball into directory ad3: tar xvfz ~/<your_username>/Downloads/asciidoc3-linux-latest.tar.gz -C ~/ad3

  • Change to the new directory: cd ~ad3.

  • In ~/ad3 you see some files and two subdirectories src and misc. The src again has a few subdirs like images, conf, doc …

  • src contains the files asciidoc3.py, and a2x3.py.

  • [PENDINIG] src contains the asciidoc3.bin, and a2x3.bin

  • Be sure that these files are executable. If not, set the permissions like so for all users: chmod +x asciidoc3.py.

  • Check installation: ./asciidoc3.py --version or python3 asciidoc3.py --version.

  • You’ll see this output: asciidoc3 4.0.2

  • Yes, that’s it, go to the section First Steps below!

Note Of course you can install in one of the other ways.

Via the »small« or »full« Docker image, or the other versions described below. For Docker see chapter docker installation of AsciiDoc3.

HTML output only (Windows)

  • Prerequisites: you need Python3.10 (or higher) installed on your machine. If not yet present, look at Python for Windows

  • Download the tarball asciidoc3_linux_latest, say into folder Downloads. Yes, that is the same file as for the GNU/Linux installation.

  • Create a new folder in your home directory, say ad3.

  • Deflate the tarball with admin-rights into directory ad3: tar xvfz C:\<your_username>\Downloads\asciidoc3-linux-latest.tar.gz -C C:\<your_username>\ad3

  • If you miss to work as admin you’ll see five lines Can’t create … Invalid argument. That’s no problem, we’ll handle it eight lines below …

  • Change to the new directory: cd ~ad3.

  • In ~/ad3 you see some files and two subdirectories src and misc. The src again has a few subdirs like images, conf, doc …

  • src contains the files asciidoc3.py, and a2x3.py

  • [PENDINIG] src contains the asciidoc3.bin, and a2x3.bin

  • Check installation: python asciidoc3.py --version.

  • You’ll see this output: asciidoc3 4.0.2

  • Yes, that’s it, go to the section First Steps below!

  • What about these lines Can’t create … Invalid argument? This are symlinks which are not resolved by Windows tar when using it without admin rights. You can do the following to get things right: delete the wrong links and add symlinks manually.

1) Erase the files that are not the expected symlinks, if they exist.
del .\asciidoc3.conf
del .\conf\text.conf
del .\filters\music\images
del .\filters\graphviz\images
del .\doc\images
2) Create the symlinks (with Admin-rights in cmd.exe only! mklink is not implemented in PowerShell - nobody knows why!) .
mklink .\asciidoc3.conf .\conf\asciidoc3.conf
mklink .\conf\text.conf .\conf\backends\text.conf
mklink /J .\filters\music\images .\images
mklink /J .\filters\graphviz\images .\images
mklink /J .\doc\images .\images
Symlinks are not mandatory! You can simply copy the .\images-folder to the mentioned locations; everything will run as expected.

Note Of course you can install in one of the other ways.

Via the »small« or »full« Docker image, or the other versions described below. For Docker see chapter docker installation of AsciiDoc3.

First Steps

If everything went well, you may try some examples to see AsciiDoc3 working. To do so, open a terminal, go to directory ad3/src and start

python3 ./asciidoc3.py -n -a icons -a toc doc/test.txt

Tip Windows users might have to replace python3 with python.

./asciidoc3.py -n -a icons -a toc doc/test.txt
(if asciidoc3.py is executable)

You’ll find a new file doc/test.html. It shows only a few features of AsciiDoc3. Another way to see AsciiDoc3 working is ./asciidoc3.bin -a toc -n -a icons userguide.txt
This produces the UserGuide as a HTML-file. If you have the programs (FOP or dblatex) installed, try to make a "good-looking" pdf out of userguide.txt:
a2x3 -f pdf doc/userguide.txt or asciidoc3.bin --pdf=fop doc/userguide.txt

Verbose Option / More Examples

If you encounter any issue (like no images: probably you have to adjust asciidoc3.conf imagesdir) or just to see what is going on when asciidoc3 / a2x3 are working, add the option verbose:
./asciidoc3.py -v -n -a icons doc/test.txt
In the directory doc you find more files you may use as examples to study the power of AsciiDoc3.

Write Your Own Text!

Now it’s time to write your own AsciiDoc3-Text and compute it!
Write your text, say mytext.txt with your favorite editor (Vim, Emacs, VSCode, … or whatever you prefer) and save it as a plain text file in directory ./src/doc. Save the images to ./images. And then:
python3 ./asciidoc3.py -n -a icons -a toc doc/mytext.txt or ./asciidoc3.py -n -a icons -a toc doc/mytext.txt The HTML output mytext.html lives in ./src/doc.
You can use other directories as well, but you have to edit asciidoc3.conf in a proper way to see the images (if any). Or you use asccidoc3api.py - see the doctext.

Prerequisites (this section needs an update, follows asap)

The packages are given in order of (assumed) priority. You’ll need most likely the first six.

To install, try apt/yum/rpm install dblatex or visit the corresponding homepage of the above mentioned software to learn more about the package and how to install.

installation Forward

© 2018 - 2026 by Berthold Gehrke • last update April 15, 2026

powered by hugo v0.157.0 extended • Theme Hugo Book, smooth changes by datenbahn