Text based document generation using Python 3.x

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

New version is out! AsciiDoc3-3.1.0 (2019-04-12)
Unified Installer (Tarball) / Debian-Package / RPM-Package / Windows zip-File …
Download the files here.
PyPI is at the moment one version behind, this inappropriate situation will end within a few days … (Easter weekend ~21. April 2019)

Tip Pelican Plugin for AsciiDoc3 available! See our blog:

In consequence of the MicroSoft/GitHub deal AsciiDoc3 migrated to GitLab. You can find us here:
The repo on GitHub is still open for comments, but all further development will be on GitLab.

AsciiDoc3 is 100% pure Python3 - you need Python 3.x to execute the program. All of the onehundred and seventy testcases defined in the AsciiDoc (Python2) distribution pass without errors and a binary identical result. See the information given on this page for download and installation instructions.
AsciiDoc3 is licensed under the terms of the GNU General Public License version 2 or later (GPLv2+).

On this page, in all related documents, and all the stuff around I make heavy use of the documents given on and the software bundle.
The pages you are reading were written using AsciiDoc3, the corresponding AsciiDoc3 sources can be found here:
The source code of page User Guide is included in the distribution files (../doc/userguide.txt), so you can test this by yourself, see here.
This site undergoes significant updating. Please return regularly to see the new versions of the asciidoc3-executable and the documentation.
I thank all the contributors for their awesome work.

AsciiDoc3 is not asciidoc-py3
The offical community of AsciiDoc makes a point of the following statement: the AsciiDoc3 implementation (which you can find on this website) is a personal project. The only official port of AsciiDoc Py to Python 3 is It was done with support from the AsciiDoc Py leadership and by following a procedure that honored the copyright and license and was in the spirit of open source. (see here)
My comment: AsciiDoc (Python 2) is/was open source under the terms of the GPLv2+. So are both AsciiDoc3 (Python 3) and asciidoc-py3. Every user may choose what he/she/div likes to run. As far as I can see any of the two programs cover all requested features.


AsciiDoc3 is a text document format for writing notes, documentation, articles, books, ebooks, slideshows, web pages, man pages and blogs. AsciiDoc3 files can be translated to many formats including HTML, PDF, EPUB, man page. AsciiDoc3 is written in Python3.

AsciiDoc3 is highly configurable: both the AsciiDoc3 source file syntax and the backend output markups (which can be almost any type of SGML/XML markup) can be customized and extended by the user.

AsciiDoc3 is a free software (GPLv2+).

Overview and Examples

You write an AsciiDoc3 document the same way you would write a normal text document, there are no markup tags or weird format notations. AsciiDoc3 files are designed to be viewed, edited and printed directly or translated to other presentation formats using the asciidoc3 command.

The asciidoc3 command translates AsciiDoc3 files to HTML, XHTML and DocBook markups. DocBook can be post-processed to presentation formats such as HTML, PDF, EPUB, DVI, LaTeX, roff, and Postscript using readily available Open Source tools.

Bug reports

  • When reporting problems please illustrate the problem with the smallest possible example that replicates the issue (and please test your example before posting). This technique will also help to eliminate red herrings prior to posting.

  • Paste the commands that you executed along with any relevant outputs.

  • Include the version of AsciiDoc3 and the platform you’re running it on.

  • If you can program please consider writing a patch to fix the problem.