AsciiDoc Home Page

Table of Contents

JavaScript must be enabled in your browser to display the table of contents.

9 November 2013: AsciiDoc 8.6.9 Released

Read the CHANGELOG for release highlights and a
full list of all additions, changes and bug fixes. Changes are
documented in the updated User Guide. See the
Installation page for downloads and and
installation instructions.

AsciiDoc is highly configurable: both the AsciiDoc source file syntax
and the backend output markups (which can be almost any type of
SGML/XML markup) can be customized and extended by the user.

AsciiDoc is free software and is licenced under the terms of the GNU
General Public License version 2 (GPLv2).

The pages you are reading were written using AsciiDoc, to view
the corresponding AsciiDoc source click on the Page Source menu item
in the left hand margin.

Overview and Examples

You write an AsciiDoc document the same way you would write a
normal text document, there are no markup tags or weird format
notations. AsciiDoc files are designed to be viewed, edited and
printed directly or translated to other presentation formats using
the asciidoc(1) command.

The asciidoc(1) command translates AsciiDoc files to HTML, XHTML and
DocBook markups. DocBook can be post-processed to presentation
formats such as HTML, PDF, EPUB, DVI, LaTeX, roff, and Postscript
using readily available Open Source tools.

David Hajage has written an AsciiDoc package for the
R Project (R is a free software
environment for statistical computing). ascii is available on
CRAN (just run install.package("ascii") from R). Briefly,
ascii replaces R results in AsciiDoc document with AsciiDoc
markup. More information and examples here:
http://eusebe.github.com/ascii/.

Jared Henley has written
AsciiDoc
Website Builder. AsciiDoc Website Builder (awb) is a python
program that automates the building of of a website written in
AsciiDoc. All you need to write is the AsciiDoc source plus a few
simple configuration files.

Brad Adkins has written
AsciiDocGen, a
web site generation and deployment tool that allows you write your
web site content in AsciiDoc. The
AsciiDocGen web
site is managed using AsciiDocGen.

Filippo Negroni has developed a set of tools to facilitate literate
programming using AsciiDoc. The set of tools is called
eWEB.

DocBook 5.0 Backend

LaTeX Backend

An experimental LaTeX backend was written for AsciiDoc in 2006 by
Benjamin Klum. Benjamin did a superhuman job (I admit it, I didn’t
think this was doable due to AsciiDoc’s SGML/XML bias). Owning to to
other commitments, Benjamin was unable to maintain this backend.
Here’s Benjamin’s original documentation.
Incompatibilities introduced after AsciiDoc 8.2.7 broke the LaTeX
backend.

In 2009 Geoff Eddy stepped up and updated the LaTeX backend, thanks to
Geoff’s efforts it now works with AsciiDoc 8.4.3. Geoff’s updated
latex.conf file shipped with AsciiDoc version 8.4.4. The backend
still has limitations and remains experimental (see
Geoff’s notes).

It’s probably also worth pointing out that LaTeX output can be
generated by passing AsciiDoc generated DocBook through dblatex(1).

Patches and bug reports

Patches and bug reports are are encouraged, but please try to follow
these guidelines:

Post bug reports and patches to the
asciidoc discussion list,
this keeps things transparent and gives everyone a chance to
comment.

The email subject line should be a specific and concise topic
summary. Commonly accepted subject line prefixes such as [ANN],
[PATCH] and [SOLVED] are good.

Bug reports

When reporting problems please illustrate the problem with the
smallest possible example that replicates the issue (and please test
your example before posting). This technique will also help to
eliminate red herrings prior to posting.

Paste the commands that you executed along with any relevant
outputs.

Include the version of AsciiDoc and the platform you’re running it
on.

If you can program please consider writing a patch to fix the
problem.

Patches

Keep patches small and atomic (one issue per patch) — no patch
bombs.

If possible test your patch against the current trunk.

If your patch adds or modifies functionality include a short example
that illustrates the changes.

Send patches in diff -u format, inline inside the mail message is
usually best; if it is a very long patch then send it as an
attachment.

Include documentation updates if you’re up to it; otherwise insert
TODO comments at relevant places in the documentation.