AsciiDoc
Text based document generation
»Home
»Man Page
»User Guide
»Cheatsheet
»a2x
»README
»ChangeLog
»Installation
»Downloads
»FAQ
»Support
Table of Contents

Introduction

AsciiDoc is a text document format for writing short documents, articles, books and UNIX man pages. AsciiDoc files can be translated to HTML and DocBook markups using the asciidoc(1) command.

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.

Tip 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, DVI, LaTeX, roff, and Postscript using readily available Open Source tools.

Example Articles

Example Books

AsciiDoc markup supports all the standard DocBook frontmatter and backmatter sections (dedication, preface, bibliography, glossary, index, colophon) plus footnotes and index entries.

Book

This AsciiDoc book’s DocBook output produced this HTML file using the DocBook XSL Stylesheets.

Multi-part book

This multi-part AsciiDoc book’s DocBook output produced this HTML file using the DocBook XSL Stylesheets.

Example UNIX Man Pages

HTML formatted AsciiDoc man pages with stylesheets and without stylesheets were generated by AsciiDoc from this file.

This roff formatted man page was generated from asciidoc(1) DocBook output using xsltproc(1) and DocBook XSL Stylesheets.

Example Web Site

The AsciiDoc website is included in the AsciiDoc distribution (in ./examples/website/) as example website built using AsciiDoc. See ./examples/website/README-website.txt.

Music Filter

A music filter is included in the distribution ./filters/ directory. It translates music in LilyPond or ABC notation to standard classical notation

Source Code Highlight Filter

A source code highlight filter is included in the distribution ./filters/ directory.

Graphviz Filter

Gouichi Iisaka has written a Graphviz filter for AsciiDoc. Graphviz generates diagrams from a textual specification. Gouichi Iisaka’s Graphviz filter is included in the AsciiDoc distribution. Here are some AsciiDoc Graphviz examples.

Mathematical Formulae

You can include mathematical formulae in AsciiDoc XHTML documents using ASCIIMathML or LaTeXMathML notation.

LaTeX Math can be included in AsciiDoc documents processed by dblatex(1).

Vim Syntax Highlighter

An AsciiDoc syntax highlighter for the Vim text editor is included in the AsciiDoc distribution (see Appendix F of the AsciiDoc User Guide for details).

Syntax highlighter screenshot

Dag Wieers has implemented an alternative Vim syntax file for AsciiDoc which can be found here http://svn.rpmforge.net/svn/trunk/tools/asciidoc-vim/.

Resources

Blogpost weblog client

blogpost is a command-line weblog client for publishing AsciiDoc documents to WordPress blog hosts. It creates and updates weblog posts and pages directly from AsciiDoc source documents.

LaTeX Backend

An experimental LaTeX backend has been written for AsciiDoc by Benjamin Klum. Benjamin has done a superhuman job (I admit it, I didn’t think this was doable due to AsciiDoc's SGML/XML bias).

Note Owning to to other commitments, Benjamin is unable to maintain this backend. I don’t have the expertise or time to take this on consequently the LaTeX backend has not been tested or updated since AsciiDoc version 8.2.7 and is currently unsupported.

Projects using AsciiDoc

Here are some projects I know of, if you know of more drop me a line and I’ll add them to the list.

AsciiDoc version 9

The next version of AsciiDoc is underway — details here.