---

Introduction

Original: http://asciidoc.org/

AsciiDoc is a plain text human readable/writable document format that can be translated to DocBook or HTML using the asciidoc(1) command. You can then either use asciidoc(1) generated HTML directly or run asciidoc(1) DocBook output through your favorite DocBook toolchain or use the AsciiDoc a2x(1) toolchain wrapper to produce PDF, EPUB, DVI, LaTeX, PostScript, man page, HTML and text formats.

The AsciiDoc format is a useful presentation format in its own right: AsciiDoc markup is simple, intuitive and as such is easily proofed and edited.

AsciiDoc is light weight: it consists of a single Python script and a bunch of configuration files. Apart from asciidoc(1) and a Python interpreter, no other programs are required to convert AsciiDoc text files to DocBook or HTML. See Example AsciiDoc Documents below.

Text markup conventions tend to be a matter of (often strong) personal preference: if the default syntax is not to your liking you can define your own by editing the text based asciidoc(1) configuration files. You can also create configuration files to translate AsciiDoc documents to almost any SGML/XML markup.

asciidoc(1) comes with a set of configuration files to translate AsciiDoc articles, books and man pages to HTML or DocBook backend formats.

My AsciiDoc Itch DocBook has emerged as the de facto standard Open Source documentation format. But DocBook is a complex language, the markup is difficult to read and even more difficult to write directly — I found I was spending more time typing markup tags, consulting reference manuals and fixing syntax errors, than I was writing the documentation.

---

Getting Started

Installing AsciiDoc

See the README and INSTALL files for install prerequisites and procedures. Packagers take a look at Packager Notes.

Example AsciiDoc Documents

The best way to quickly get a feel for AsciiDoc is to view the AsciiDoc web site and/or distributed examples:

• Take a look at the linked examples on the AsciiDoc web site home corresponding AsciiDoc source.

• Read the *.txt source files in the distribution ./doc directory along with the corresponding HTML and DocBook XML files.

---

AsciiDoc Document Types

There are three types of AsciiDoc documents: article, book and manpage. All document types share the same AsciiDoc format with some minor variations. If you are familiar with DocBook you will have noticed that AsciiDoc document types correspond to the same-named DocBook document types.

Use the asciidoc(1) -d (--doctype) option to specify the AsciiDoc document type — the default document type is article.

By convention the .txt file extension is used for AsciiDoc document source files.

article

Used for short documents, articles and general documentation. See the AsciiDoc distribution ./doc/article.txt example.

AsciiDoc defines standard DocBook article frontmatter and backmatter section markup templates (appendix, abstract, bibliography, glossary, index).

book

Books share the same format as articles, with the following differences:

• The part titles in multi-part books are top level titles (same level as book title).

• Some sections are book specific e.g. preface and colophon.

Book documents will normally be used to produce DocBook output since DocBook processors can automatically generate footnotes, table of contents, list of tables, list of figures, list of examples and indexes.

AsciiDoc defines standard DocBook book frontmatter and backmatter section markup templates (appendix, dedication, preface, bibliography, glossary, index, colophon).

Example book documents

Book

The ./doc/book.txt file in the AsciiDoc distribution.

Multi-part book

The ./doc/book-multi.txt file in the AsciiDoc distribution.

manpage

Used to generate roff format UNIX manual pages. AsciiDoc manpage documents observe special header title and section naming conventions — see the Manpage Documents section for details.

AsciiDoc defines the synopsis section markup template to generate the DocBook refsynopsisdiv section.

See also the asciidoc(1) man page source (./doc/asciidoc.1.txt) from the AsciiDoc distribution.

---

AsciiDoc Backends

The asciidoc(1) command translates an AsciiDoc formatted file to the backend format specified by the -b (--backend) command-line option. asciidoc(1) itself has little intrinsic knowledge of backend formats, all translation rules are contained in customizable cascading configuration files. Backend specific attributes are listed in the Backend Attributes section.

docbook45

Outputs DocBook XML 4.5 markup.

html4

This backend generates plain HTML 4.01 Transitional markup.

xhtml11

This backend generates XHTML 1.1 markup styled with CSS2. Output files have an .html extension.

html5

This backend generates HTML 5 markup, apart from the inclusion of audio and video block macros it is functionally identical to the xhtml11 backend.

slidy

Use this backend to generate self-contained Slidy HTML slideshows for your web browser from AsciiDoc documents. The Slidy backend is documented in the distribution doc/slidy.txt file and

wordpress

A minor variant of the html4 backend to support blogpost.

latex

Experimental LaTeX backend.

Backend Aliases

Backend aliases are alternative names for AsciiDoc backends. AsciiDoc comes with two backend aliases: html (aliased to xhtml11) and docbook (aliased to docbook45).

You can assign (or reassign) backend aliases by setting an AsciiDoc attribute named like backend-alias-<alias> to an AsciiDoc backend name. For example, the following backend alias attribute definitions appear in the [attributes] section of the global asciidoc.conf configuration file:

backend-alias-html=xhtml11
backend-alias-docbook=docbook45

Backend Plugins

The asciidoc(1) --backend option is also used to install and manage backend plugins.

• A backend plugin is used just like the built-in backends.

• Backend plugins take precedence over built-in backends with the same name.

• You can use the {asciidoc-confdir} intrinsic attribute to refer to the built-in backend configuration file location from backend plugin configuration files.

• You can use the {backend-confdir} intrinsic attribute to refer to the backend plugin configuration file location.

• By default backends plugins are installed in $HOME/.asciidoc/backends/<backend> where <backend> is the backend name.

---

DocBook

AsciiDoc generates article, book and refentry DocBook documents (corresponding to the AsciiDoc article, book and manpage document types).

Most Linux distributions come with conversion tools (collectively called a toolchain) for converting DocBook files to presentation formats such as Postscript, HTML, PDF, EPUB, DVI, PostScript, LaTeX, roff (the native man page format), HTMLHelp, JavaHelp and text. There are also programs that allow you to view DocBook files directly, for example Yelp (the GNOME help viewer).

Converting DocBook to other file formats

DocBook files are validated, parsed and translated various presentation file formats using a combination of applications collectively called a DocBook tool chain. The function of a tool chain is to read the DocBook markup (produced by AsciiDoc) and transform it to a presentation format (for example HTML, PDF, HTML Help, EPUB, DVI, PostScript, LaTeX).

A wide range of user output format requirements coupled with a choice of available tools and stylesheets results in many valid tool chain combinations.

a2x Toolchain Wrapper

One of the biggest hurdles for new users is installing, configuring and using a DocBook XML toolchain. a2x(1) can help — it’s a toolchain wrapper command that will generate XHTML (chunked and unchunked), PDF, EPUB, DVI, PS, LaTeX, man page, HTML Help and text file outputs from an AsciiDoc text file. a2x(1) does all the grunt work associated with generating and sequencing the toolchain commands and managing intermediate and output files. a2x(1) also optionally deploys admonition and navigation icons and a CSS stylesheet. See the a2x(1) man page for more details. In addition to asciidoc(1) you also need xsltproc(1), DocBook XSL Stylesheets and optionally: dblatex or FOP (to generate PDF); w3m(1) or lynx(1) (to generate text).

The following examples generate doc/source-highlight-filter.pdf from the AsciiDoc doc/source-highlight-filter.txt source file. The first example uses dblatex(1) (the default PDF generator) the second example forces FOP to be used:

$ a2x -f pdf doc/source-highlight-filter.txt
$ a2x -f pdf --fop doc/source-highlight-filter.txt

See the a2x(1) man page for details.

Tip	Use the --verbose command-line option to view executed toolchain commands.

HTML generation

AsciiDoc produces nicely styled HTML directly without requiring a DocBook toolchain but there are also advantages in going the DocBook route:

• HTML from DocBook can optionally include automatically generated indexes, tables of contents, footnotes, lists of figures and tables.

• DocBook toolchains can also (optionally) generate separate (chunked) linked HTML pages for each document section.

• Toolchain processing performs link and document validity checks.

• If the DocBook lang attribute is set then things like table of contents, figure and table captions and admonition captions will be output in the specified language (setting the AsciiDoc lang attribute sets the DocBook lang attribute).

On the other hand, HTML output directly from AsciiDoc is much faster, is easily customized and can be used in situations where there is no website]).

PDF generation

There are two commonly used tools to generate PDFs from DocBook, dblatex and FOP.

dblatex or FOP?

• dblatex is easier to install, there’s zero configuration required and no Java VM to install — it just works out of the box.

• dblatex source code highlighting and numbering is superb.

• dblatex is easier to use as it converts DocBook directly to PDF whereas before using FOP you have to convert DocBook to XML-FO using DocBook XSL Stylesheets.

• FOP is more feature complete (for example, callouts are processed inside literal layouts) and arguably produces nicer looking output.

HTML Help generation

1. Convert DocBook XML documents to HTML Help compiler source files using DocBook XSL Stylesheets and xsltproc(1).

2. Convert the HTML Help source (.hhp and .html) files to HTML Help (.chm) files using the Microsoft HTML Help Compiler.

Toolchain components summary

AsciiDoc

Converts AsciiDoc (.txt) files to DocBook XML (.xml) files.

DocBook XSL Stylesheets

These are a set of XSL stylesheets containing rules for converting DocBook XML documents to HTML, XSL-FO, manpage and HTML Help files. The stylesheets are used in conjunction with an XML parser such as xsltproc(1).

xsltproc

An XML parser for applying XSLT stylesheets (in our case the DocBook XSL Stylesheets) to XML documents.

dblatex

Generates PDF, DVI, PostScript and LaTeX formats directly from DocBook source via the intermediate LaTeX typesetting language —  uses DocBook XSL Stylesheets, xsltproc(1) and latex(1).

FOP

The Apache Formatting Objects Processor converts XSL-FO (.fo) files to PDF files. The XSL-FO files are generated from DocBook source files using DocBook XSL Stylesheets and xsltproc(1).

Microsoft Help Compiler

The Microsoft HTML Help Compiler (hhc.exe) is a command-line tool that converts HTML Help source files to a single HTML Help (.chm) file. It runs on MS Windows platforms and can be downloaded from http://www.microsoft.com.

AsciiDoc dblatex configuration files

The AsciiDoc distribution ./dblatex directory contains asciidoc-dblatex.xsl (customized XSL parameter settings) and asciidoc-dblatex.sty (customized LaTeX settings). These are examples of optional dblatex output customization and are used by a2x(1).

AsciiDoc DocBook XSL Stylesheets drivers

You will have noticed that the distributed HTML and HTML Help documentation files (for example ./doc/asciidoc.html) are not the plain outputs produced using the default DocBook XSL Stylesheets configuration. This is because they have been processed using customized DocBook XSL Stylesheets along with (in the case of HTML outputs) the custom ./stylesheets/docbook-xsl.css CSS stylesheet.

You’ll find the customized DocBook XSL drivers along with additional documentation in the distribution ./docbook-xsl directory. The examples that follow are executed from the distribution documentation (./doc) directory. These drivers are also used by a2x(1).

common.xsl

Shared driver parameters. This file is not used directly but is included in all the following drivers.

chunked.xsl

Generate chunked XHTML (separate HTML pages for each document section) in the ./doc/chunked directory. For example:

$ python ../asciidoc.py -b docbook asciidoc.txt
$ xsltproc --nonet ../docbook-xsl/chunked.xsl asciidoc.xml

epub.xsl

Used by a2x(1) to generate EPUB formatted documents.

fo.xsl

Generate XSL Formatting Object (.fo) files for subsequent PDF file generation using FOP. For example:

$ python ../asciidoc.py -b docbook article.txt
$ xsltproc --nonet ../docbook-xsl/fo.xsl article.xml > article.fo
$ fop article.fo article.pdf

htmlhelp.xsl

Generate Microsoft HTML Help source files for the MS HTML Help Compiler in the ./doc/htmlhelp directory. This example is run on MS Windows from a Cygwin shell prompt:

$ python ../asciidoc.py -b docbook asciidoc.txt
$ xsltproc --nonet ../docbook-xsl/htmlhelp.xsl asciidoc.xml
$ c:/Program\ Files/HTML\ Help\ Workshop/hhc.exe htmlhelp.hhp

manpage.xsl

Generate a roff(1) format UNIX man page from a DocBook XML refentry document. This example generates an asciidoc.1 man page file:

$ python ../asciidoc.py -d manpage -b docbook asciidoc.1.txt
$ xsltproc --nonet ../docbook-xsl/manpage.xsl asciidoc.1.xml

xhtml.xsl

Convert a DocBook XML file to a single XHTML file. For example:

$ python ../asciidoc.py -b docbook asciidoc.txt
$ xsltproc --nonet ../docbook-xsl/xhtml.xsl asciidoc.xml > asciidoc.html

If you want to see how the complete documentation set is processed take a look at the A-A-P script ./doc/main.aap.

---

Generating Plain Text Files

AsciiDoc does not have a text backend (for most purposes AsciiDoc source text is fine), however you can convert AsciiDoc text files to formatted text using the AsciiDoc a2x(1) toolchain wrapper utility.

---

HTML5 and XHTML 1.1

The xhtml11 and html5 backends embed or link CSS and JavaScript files in their outputs, there is also a themes plugin framework.

• If the AsciiDoc linkcss attribute is defined then CSS and JavaScript files are linked to the output document, otherwise they are embedded (the default behavior).

• The default locations for CSS and JavaScript files can be changed by setting the AsciiDoc stylesdir and scriptsdir attributes respectively.

• The default locations for embedded and linked files differ and are calculated at different times — embedded files are loaded when asciidoc(1) generates the output document, linked files are loaded by the browser when the user views the output document.

• Embedded files are automatically inserted in the output files but you need to manually copy linked CSS and Javascript files from AsciiDoc configuration directories to the correct location relative to the output document.

stylesdir attribute	Linked location (linkcss attribute defined)	Embedded location (linkcss attribute undefined)
Undefined (default).	Same directory as the output document.	stylesheets subdirectory in the AsciiDoc configuration directory (the directory containing the backend conf file).
Absolute or relative directory name.	Absolute or relative to the output document.	Absolute or relative to the AsciiDoc configuration directory (the directory containing the backend conf file).

Table 1. Stylesheet file locations

scriptsdir attribute	Linked location (linkcss attribute defined)	Embedded location (linkcss attribute undefined)
Undefined (default).	Same directory as the output document.	javascripts subdirectory in the AsciiDoc configuration directory (the directory containing the backend conf file).
Absolute or relative directory name.	Absolute or relative to the output document.	Absolute or relative to the AsciiDoc configuration directory (the directory containing the backend conf file).

Table 2. JavaScript file locations

Themes

The AsciiDoc theme attribute is used to select an alternative CSS stylesheet and to optionally include additional JavaScript code.

• Theme files reside in an AsciiDoc configuration directory named themes/<theme>/ (where <theme> is the the theme name set by the theme attribute). asciidoc(1) sets the themedir attribute to the theme directory path name.

• The theme attribute can also be set using the asciidoc(1) --theme option, the --theme option can also be used to manage theme plugins.

• AsciiDoc ships with two themes: flask and volnitsky.

• The <theme>.css file replaces the default asciidoc.css CSS file.

• The <theme>.js file is included in addition to the default asciidoc.js JavaScript file.

• If the data-uri attribute is defined then icons are loaded from the theme icons sub-directory if it exists (i.e. the iconsdir attribute is set to theme icons sub-directory path).

• Embedded theme files are automatically inserted in the output files but you need to manually copy linked CSS and Javascript files to the location of the output documents.

• Linked CSS and JavaScript theme files are linked to the same linked locations as other CSS and JavaScript files.

For example, the command-line option --theme foo (or --attribute theme=foo) will cause asciidoc(1) to search configuration file locations 1 for a sub-directory called themes/foo containing the stylesheet foo.css and optionally a JavaScript file name foo.js.