1. Installation

Add AsciiSpec to your shell profile with the path to the asciispec/bin directory on your system:

export PATH=$PATH:~/path/to/asciispec/bin/

If the AsciiSpec tool is found by your system, running AsciiSpec with the -h flag will print a help page:

asciispec -h

2. Converting Documents

To convert this document with AsciiSpec, cd to the docs directory and run:

asciispec userguide.adoc

This will use the default HTML and create a file called userguide.html.
To convert to HTML using a different CSS stylesheet, document attributes are passed using the -a flag:

asciispec -a stylesheet=mystyle.css userguide.adoc
Passing a document attribute via the command line will override that value if it has already been set in the source document.

2.1. Docbook / XML

To convert to docbook (.xml), use the -b docbook flag:

asciispec -b docbook userguide.adoc

Most built-in CLI parameters are described in the help page by running asciispec -h and in further detail in the CLI Options section of the AsciiDoctor user manual.

2.2. PDF

Apache FOP (Formatting Objects Processor) is required for higher quality PDF generation. A fork with custom PDF styling and syntax highlighting can be found at the following location:

https://github.com/NumberFour/asciidoctor-fopub

  1. Clone the Asciidoctor Fopub repository

    git clone https://github.com/NumberFour/asciidoctor-fopub.git

  2. Add the asciidoctor-fopub/ directory to your shell profile:

    export PATH=$PATH:~/path/to/asciidoctor-fopub/

  3. Confirm successful install using the which fopub command.

    $ which fopub
~/path/to/fopub

  4. Convert XML to PDF using the following:

    fopub myfile.xml

An example command to convert from asciidoc to PDF would then look something like the following:

asciispec -b docbook myfile.adoc && fopub myfile.xml

2.3. Configuration File

AsciiSpec processors with configurable target URLs have to be set up by means of a configuration file. For this case,config.adoc can be copied to the location of the source document and used as a template. The following line of code must be included at the top of your source document:

include::config.adoc[]

To configure a specific processor, see AsciiSpec Processors.