Fetching contributors…
Cannot retrieve contributors at this time
228 lines (166 sloc) 7.48 KB
AsciiDoc Installation
NOTE: The current version of AsciiDoc requires *Python 2.4 or newer*
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
See the link:README.html[README] page.
Installing from the Mercurial repository
The AsciiDoc[Mercurial] repository
is hosted by[Google Code].
To browse the repository go to
You can install AsciiDoc from the repository if you don't have an up to
date packaged version or want to get the latest version from the trunk:
- Make sure you have[Mercurial]
installed, you can check with:
$ hg --version
- Go to the directory you want to install AsciiDoc into and download
the repository. This example gets the {revnumber} tagged release:
$ cd ~/bin
$ hg clone -r {revnumber} asciidoc-{revnumber}
You now have two choices: you can run asciidoc locally from your
repository or you can use 'autoconf(1)' and 'make(1)' to perform a
system-wide install.
Running asciidoc from your local copy
Create a symlink to the AsciiDoc script in a search `PATH` directory
so it's easy to execute `asciidoc` from the command-line, for example:
$ ln -s ~/bin/asciidoc-{revnumber}/ ~/bin/asciidoc
$ ln -s ~/bin/asciidoc-{revnumber}/ ~/bin/a2x
Use the Mercurial `pull` command to update your local AsciiDoc repository.
Installing asciidoc for all users
Create `configure` using 'autoconf(1)'; use `configure` to create the
`Makefile`; run 'make(1)'; build the man pages; install:
$ autoconf
$ ./configure
$ make
$ sudo make install
To uninstall:
$ sudo make uninstall
Distribution tarball installation
The distribution source tarballs can be downloaded from the
NOTE: Unless you are <<X3,installing on Microsoft Windows>> you should
use the tarball and not the zip file to install the the distribution
(the tarball contains symlinks).
If your flavor or 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
The `autoconf(1)` generated `configure` script creates a make file
that is tailored for your system. To install:
$ tar -xzf asciidoc-{revnumber}.tar.gz
$ cd asciidoc-{revnumber}
$ ./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 scripts will be install in the global Vim
configuration file directory (`asciidoc.vim` in the `syntax` directory
and `asciidoc_filetype.vim` in the `ftdetect` directory).
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-{revnumber}.zip
This will create the folder +asciidoc-{revnumber}+ containing the
`` and `` 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
Test out asciidoc by changing to the AsciiDoc application directory
and convert the User Guide document (`./doc/asciidoc.txt`) to XHTML
$ python doc/asciidoc.txt
link:testasciidoc.html[testasciidoc] offers a more extensive set of
conformance tests, though you do need to create the test data before
running the tests (this in itself is a good post-install test):
$ python ./tests/ update
Now you can run the tests by executing this command:
$ python ./tests/ run
A full battery of tests can be run from the `main.aap` script in the
distribution root directory:
$ aap test
Building the distribution
The AsciiDoc distribution is built using[A-A-P]
(a software build system written by Bram Moolenaar). The AsciiDoc
A-A-P scripts are:
`./main.aap`:: Builds the distribution tarball and zip files,
documentation and example website.
`./doc/main.aap`:: Builds distribution documentation.
`./examples/website/main.aap`:: Builds AsciiDoc website.
`./common.aap`:: Included in all scripts.
To build the distribution tarball and zip files, documentation and
example website run A-A-P from the distribution root directory:
$ aap
Prepackaged AsciiDoc installation
The following platform specific AsciiDoc packages are available:
*Debian GNU/Linux*::
If you use Debian or a Debian based distribution there's an[AsciiDoc Debian package]
available. Thanks to[Fredrik Steen] who
built and maintains the Debian AsciiDoc package.
*Gentoo Linux*::
If you use Gentoo Linux there's a[Gentoo AsciiDoc
package] available. Thanks to[Brandon
Philips] for writing the ebuild.
*Fedora Linux*::
With help from Terje Røsten, Chris Wright added asciidoc to Fedora
Extras which is available in the default installation. To install
asciidoc execute the following command:
$ yum install asciidoc
*Slackware Linux*::
John Calixto has created a Slackware package for AsciiDoc which can
be downloaded from
*Ark Linux*::[Bernhard Rosenkraenzer] added AsciiDoc to
Ark Linux -- the package is available from the Ark Linux repository
at, so Ark Linux users
should just run `apt-get install asciidoc`.
*T2 Linux*::[Christian Wiese] added AsciiDoc to the[T2 Linux] repository at To
build and install the package on a T2 system, run
`./scripts/Emerge-Pkg asciidoc` from within your T2 source directory
(default: `/usr/src/t2-src`).
*Red Hat Enterprise Linux, Fedora and CentOS packages*::
Dag Wieers has built AsciiDoc RPMs for a number of Red Hat based
distributions, they can be downloaded from
*CSW Package for Sun Solaris*::
Ben Walton has created a CSW package for AsciiDoc, you can find it
See also link:userguide.html#X38[Packager Notes] in the 'AsciiDoc User