AsciiDoc Installation

The current version of AsciiDoc requires Python 3.5 or later to run. If you don’t already have an up-to-date version of Python installed it can be downloaded from the official Python website http://www.python.org/.

Prerequisites

Python 3.5+
DocBook XSL Stylesheets
xsltproc
w3m
dblatex
FOP
make

Installing from PyPI

Starting from 10.0 release, AsciiDoc.py can be installed from PyPI repository by doing the following:

$ python3 -m pip install asciidoc

Installing from the GitHub repository

The AsciiDoc repository is hosted by GitHub. To browse the repository go to https://github.com/asciidoc/asciidoc-py3. You can install AsciiDoc from the repository if you don’t have an up to date packaged version, or you want to get the latest version from the master branch:

Make sure you have Git installed; you can check with:
```
$ git --version
```
Go to the directory you want to install AsciiDoc into and download the repository. This example gets the 10.2.1 tagged release:
```
$ cd ~/bin
$ git clone https://github.com/asciidoc/asciidoc-py3 asciidoc-10.2.1
$ cd asciidoc-10.2.1
$ git checkout 10.2.1
```

You now have two choices: you can run asciidoc locally from your repository (e.g. python3 -m asciidoc or python3 -m asciidoc.a2x) or you can use autoconf(1) and make(1) to perform a system-wide install. If you wish to update your installation, run git pull and re-run make(1) to re-install the updated version

Uninstalling AsciiDoc.py

To uninstall AsciiDoc.py, if you installed it via PyPI, then simply do the following:

$ python3 -m pip uninstall asciidoc

If you installed it via make(1), please do the following:

$ sudo make uninstall

Distribution tarball installation

The distribution source tarballs can be downloaded from GitHub releases page https://github.com/asciidoc/asciidoc-py3/releases.

If your flavor of UNIX or Linux does not have a packaged AsciiDoc distribution or if you prefer to install the latest AsciiDoc version from source, use the configure shell script in the tarball root directory.

The autoconf(1)-generated configure script creates a Makefile that is tailored for your system. To install:

$ tar -xzf asciidoc-10.2.1.tar.gz
$ cd asciidoc-10.2.1
$ ./configure
$ sudo make install

To install the documentation:

$ sudo make docs

To uninstall AsciiDoc:

$ sudo make uninstall

If Vim is installed on your system the AsciiDoc Vim syntax highlighter and filetype detection are already installed as built into the vim runtime.

Microsoft Windows installation

AsciiDoc is developed and tested on Linux but there seem to be quite a few people using it on Windows. To install AsciiDoc on Windows unzip the distribution zip file contents:

$ unzip asciidoc-10.2.1.zip

This will create the folder asciidoc-10.2.1 containing the asciidoc.py and a2x.py executables along with configuration files and documentation.

To generate DocBook based outputs (e.g. PDFs) you will also need a working DocBook toolchain. Installing and configuring a DocBook toolchain on Windows can be a challenge — this blog post explains How to Create Handsome PDF Documents Without Frustration using Cygwin, dblatex and AsciiDoc.

Testing your installation

To test out AsciiDoc.py, you will need to install pytest and pytest-mock from PyPI.

Test out asciidoc by changing to the AsciiDoc application directory and converting the User Guide document (./doc/asciidoc.txt) to XHTML (./doc/asciidoc.html):

$ python3 asciidoc.py doc/asciidoc.txt

The testasciidoc tool offers a more extensive set of conformance tests. You can run the tests by executing this command:

$ python3 ./tests/testasciidoc.py run

Unit tests can be run by doing:

$ python3 -m pytest

Doctests can be run by doing:

$ python3 -m asciidoc.asciidoc --doctest

Running all three of these can be accomplished through the Makefile:

$ make test

Prepackaged AsciiDoc installation

The following platform-specific AsciiDoc packages are available:

Fedora Linux

AsciiDoc is included in Fedora Extras, which is available in the default Fedora installation. To install asciidoc, execute the following command:

$ yum install asciidoc

Ubuntu / Debian

AsciiDoc is included in Ubuntu / Debian package manager. To install, execute the following command:

$ apt install asciidoc

macOS Homebrew

AsciiDoc has been packaged in homebrew and is installable using the following command:

$ brew install asciidoc

See also Packager Notes in the AsciiDoc User Guide.