    ___              _ _ ____
   /   |  __________(_|_) __ \____  _  ____  __
  / /| | / ___/ ___/ / / / / / __ \| |/_/ / / /
 / ___ |(__  ) /__/ / / /_/ / /_/ />  </ /_/ /
/_/  |_/____/\___/_/_/_____/\____/_/|_|\__, /
                                      /____/

A basic AsciiDoc file

In essence AsciiDoxy is a preprocessor for AsciiDoc files. It looks for special directives in these files and replaces them with valid AsciiDoc. Then it runs AsciiDoctor to generate HTML or PDF from the AsciiDoc files. To write documentation with AsciiDoxy, you need to know how to write an AsciiDoc file.

Let’s start with writing a basic AsciiDoc file, and using AsciiDoxy to generate an HTML file.

1. The AsciiDoc file

Use your favorite text editor to create a new file named my-first-document.adoc. Enter the following text:

= My first document

This is my first document written for AsciiDoxy.

== The story begins

Today I am so *bold* to write _cursively_ in "`AsciiDoc`".

To learn more about the formatting supported by AsciiDoctor, see:

2. Running AsciiDoxy

Use AsciiDoxy to generate a beautiful HTML document:

asciidoxy my-first-document.adoc

If AsciiDoxy is installed correctly and there are no errors in the file, you should see the AsciiDoxy logo and a couple of progress bars. After the last progress bar hits 100%, AsciiDoxy will exit.

Now there should be a new build directory in the directory where you ran the command. This build directory contains temporary files generated by AsciiDoxy, and an output directory. The build/output directory contains the HTML output: my-first-document.html. If you open it in your browser, it should look like this:

Example 1. Rendered document

My first document

This is my first document written for AsciiDoxy.

The story begins

Today I am so bold to write cursively in “AsciiDoc”.

2.1. Changing the location of the output

You can specify a different directory to store the output in using command-line option --destination-dir (or -D):

asciidoxy my-first-document.adoc --destination-dir my-output

It is also possible to store the temporary build files in a different location by using command-line option --build-dir:

asciidoxy my-first-document.adoc --destination-dir my-output --build-dir /tmp/asciidoxy

If you do not explicitly specify a destination directory, the output will move together with the temporary build files.

All available command-line options can be found in the reference documentation for command-line options.