___ _ _ ____ / | __________(_|_) __ \____ _ ____ __ / /| | / ___/ ___/ / / / / / __ \| |/_/ / / / / ___ |(__ ) /__/ / / /_/ / /_/ /> </ /_/ / /_/ |_/____/\___/_/_/_____/\____/_/|_|\__, / /____/
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
= 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:
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
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:
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
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
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.