Fork Me On GitLab
Text based document generation using Python 3

»Home  »User Guide  »Blog  »Quickstart  »Download  »Install  »PyPI  »Docker  »Windows  »Cheatsheet  »Release Notes  »Contact / Donate  »Imprint / Impressum / Datenschutz / Privacy

1. Start with AsciiDoc3

  • You don’t need admin/root-access to try AsciiDoc3: install local and/or via venv or via pip.
    This is the recommended way.

  • Some users want to install system wide: download the tarball / deb- / rpm-package / zip-file of the current AsciiDoc3 distribution, see here.

  • After installation you see a new directory '~/asciidoc3, see here.

  • Details are given here; info about uninstalling, too.

Dependencies and other Packages

AsciiDoc3 comes with NO dependencies to keep it as simple as possible. Installing assumes that Python3 is available: if not, it fails.
If you want more than producing html-output (PDF, filter like Lilypond, Highlight, Pygments, Graphviz, w3m/lynx …) you’ll need the following packages:

The packages are given in order of (assumed) priority. You’ll need most likely the first five: I confess to have never heard before about the w3m text-browser.

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

1 a lot of data to download (> 300 MB)!
2 barely the same (FOP needs a Java-runtime)!

2. Testing your installation

In your new directory, e.g. asciidoc3, you’ll find the following input files:
- ./doc/test.txt: a small document to see everything’s ok (→ works …),
- ./doc/userguide.txt: this is nothing else than the AsciiDoc3-User Guide.

2.1. First Test

Open a terminal, go to your directory and start

$ cd ~/asciidoc3/doc

$ python3 ../ -n -a icons -a toc -o test.html test.txt
Tip Windows users replace python3 with python.

or, when you have installed AsciiDoc3 system wide or via venv

$ asciidoc3 -n -a icons -a toc -o test.html test.txt

You’ll find a new file test.html. It shows only a few features of AsciiDoc3.

2.2. UserGuide

Open a terminal, go to your directory and start

$ cd ~/asciidoc3/doc

$ python3 ../ -a toc -n -a icons -o userguide.html userguide.txt


$ asciidoc3 -a toc -n -a icons -o userguide.html userguide.txt

The new file userguide.html contains the current version of the user guide. Processing userguide.txt makes use of many AsciiDoc3-features.

To make a "good-looking" pdf out of userguide.txt, try

$ a2x3 -f pdf userguide.txt


$ python3 ../ -f pdf userguide.txt

To produce an alternative slightly different PDF you may use option fop - this requires that you have installed fop.

$ a2x3 -f pdf --fop userguide.txt


$ python3 ../ -f pdf --fop userguide.txt

2.3. Verbose Option

To see what is going on when or works, add the option verbose:

$ asciidoc3 -v -n -a icons -o test.html test.txt

$ a2x3 -f pdf -v --fop userguide.txt

2.4. More Examples and Further Information

In the directory ~/asciidoc3/doc you find some more files you may use as examples to study the features of AsciiDoc3.

Tip Even if you don’t want to test your own version of AsciiDoc3, it’s a good idea to study the huge amount of files produced by
$ cd ./tests
$ python3 --force update

You’ll see a lot of files written to ./tests/data - they cover all the features of AsciiDoc3. Explore yourself!