AsciiDoc Installation
=====================
NOTE: 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
-------------
See the link:README.html[README] page.
Installing from the GitHub repository
-------------------------------------
The AsciiDoc repository is hosted by https://github.com[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 https://git-scm.com/[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 {revnumber} tagged release:
[subs="attributes"]
$ cd ~/bin
$ git clone https://github.com/asciidoc/asciidoc-py3 asciidoc-{revnumber}
$ git checkout {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:
[subs="attributes"]
$ ln -s ~/bin/asciidoc-{revnumber}/asciidoc.py ~/bin/asciidoc
$ ln -s ~/bin/asciidoc-{revnumber}/a2x.py ~/bin/a2x
Use the git `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
---------------------------------------------
[[X1]]
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:
[subs="attributes"]
$ 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 are already installed as built into the vim runtime.
[[X3]]
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:
[subs="attributes"]
$ unzip asciidoc-{revnumber}.zip
This will create the folder +asciidoc-{revnumber}+ 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
http://blog.rainwebs.net/2010/02/25/how-to-create-handsome-pdf-documents-without-frustration/[How
to Create Handsome PDF Documents Without Frustration] using
http://www.cygwin.com/[Cygwin],
http://dblatex.sourceforge.net/[dblatex] and AsciiDoc.
Testing your installation
-------------------------
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 link:testasciidoc.html[testasciidoc] tool offers a more extensive set of
conformance tests. You can run the tests by executing this command:
$ python3 ./tests/testasciidoc.py run
A full battery of tests can be run from the `Makefile` script in the
distribution root directory:
$ make test
[[X2]]
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 link:userguide.html#X38[Packager Notes] in the 'AsciiDoc User
Guide'.