Text based document generation using Python 3.x

»Home  »User Guide  »Blog  »Quickstart  »Download  »Install  »PyPI  »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 or via pip.

  • Most users 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.

  • Be sure python3 is in your PATH and starts Python3, 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, Graphviz …) 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 abovementioned 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, too)!

2. Testing your installation

In your new directory, e.g. asciidoc3, you’ll find the following input files:
- ./doc/test.txt: a small doc 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-3.1.0/doc

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

or, when you have installed AsciiDoc3 system wide (su ./installscript)

$ 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-3.1.0/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. asciidoc3.conf required

Experienced AsciiDoc (Python2) users please note:
The use of a file named asciidoc.conf is not allowed in AsciiDoc3 - a file with this name will be ignored. Use asciidoc3.conf instead.

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