Text based document generation using Python 3.x

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

1. Start with AsciiDoc3

  • You don’t need admin/root-access to try AsciiDoc3: install local or via /venv/pip.

  • Download the tarball / zip-file of the current AsciiDoc3 distribution, see here.

  • Deflate the tarball / zip-file in an appropriate directory, see here.

  • Be sure python3 is in your PATH and starts Python3, see here.

  • To uninstall, see here.

Note A smart way to use AsciiDoc3: pip / pip3 / venv …, see here.

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.

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.0.2/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.0.2/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 … almost complete now. To see the insignificant differences between AsciiDoc3 and AsciiDoc2, take a look here. 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
Note Depending on your directory layout - when your AsciiDoc3-folder is not a subdirectory of your home-directory - you may encounter an error message like this:
Error: [Errno 1] Operation not permitted: <your_asciidoc3-folder_not_under_home>/test.pdf
You can ignore that, the pdf is there and complete. That’s probably a dblatex-issue (or you are using a vfat partition?).
As a workaround you may use sudo python3 -f pdf userguide.txt or the system wide command -f pdf userguide.txt or the following option --fop.

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

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.
Please take a closer look at asciidoc3port.txt: this file contains a detailed report on the porting efforts. Try a2x3 -f pdf -v --fop asciidoc3port.txt to produce a PDF. You can find this information even more complete as part of this website here.