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.
![]() |
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.
Example Articles
-
This version of the AsciiDoc User Guide was generated by AsciiDoc from this AsciiDoc file.
-
Here’s the same document created by first generating DocBook markup using AsciiDoc and then converting the DocBook markup to HTML using DocBook XSL Stylesheets.
-
The User Guide again, this time a chunked version.
-
AsciiDoc generated this stand-alone HTML file containing embedded CSS, JavaScript and images from this AsciiDoc article template with this command:
asciidoc -a data-uri -a icons -a toc -a max-width=55em article.txt
-
The same AsciiDoc article template produced this HTML file and this PDF file via DocBook markup generated by AsciiDoc.
-
This PDF formatted User Guide was generated from asciidoc(1) DocBook output.
-
This EPUB formatted article was generated using a2x.
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.
More examples
-
See below: Documents written using AsciiDoc.
-
Example Tables.
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).
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/.
matplotlib Filter
Leonid Volnitsky has written a matplotlib filter for AsciiDoc. Using this filter you can generate charts from inline matplotlib scripts.
Try AsciiDoc on the Web
Andrew Koster has written a Web based application to interactively convert and display AsciiDoc source: http://andrewk.webfactional.com/asciidoc.php
Resources
Here are resources that I know of, if you know of more drop me a line and I’ll add them to the list.
-
Check the installation page for packaged versions of AsciiDoc.
-
Alex Efros has written an HTML formatted AsciiDoc Cheatsheet using Asciidoc.
-
Thomas Berker has written an AsciiDoc Cheatsheet in Open Document and PDF formats.
-
The WikiMatrix website has an excellent web page that compares the various Wiki markup syntaxes. An interesting attempt at Wiki markup standardization is CREOLE.
-
Terrence Brannon has written AsciiDoc functions for Emacs.
-
The *Nix Power Tools project has released an AsciiDoc syntax highlighter for Emacs.
-
Franck Pommereau has written Asciidoctest, a program that doctests snippets of Python code within your Asciidoc documents.
-
The ReMIPS project website has been built using AsciiDoc.
-
Here are some DocBook XSL Stylesheets Notes.
-
Karl Mowatt-Wilson has developed an ikiwiki plugin for AsciiDoc which he uses to render his website. The plugin is available here and there is some discussion of the ikiwiki integration here.
-
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/.
-
Pascal Rapaz has written a Python script to automate AsciiDoc website generation. You can find it at http://www.rapazp.ch/opensource/tools/asciidoc.html.
-
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 toolset is called eWEB.
Please let me know if any of these links need updating.
Blogpost weblog client
Documents written using AsciiDoc
Here are some documents I know of, if you know of more drop me a line and I’ll add them to the list.
-
The book Programming Scala by Dean Wampler and Alex Payne (O’Reilly) was written using Asciidoc.
-
The fishR website has a number of book examples written using AsciiDoc.
-
Frugalware Linux uses AsciiDoc for documentation.
-
Henrik Maier produced this professional User manual using AsciiDoc: http://www.proconx.com/gcpmg/UMGCPMG-0801.pdf.
-
Henrik also produced this folded single page brochure format example: http://www.proconx.com/gcpmg/IGGCPMG-0801-up.pdf.
See this AsciiDoc discussion group thread for details.
-
The Git User’s Manual.
-
Git Magic
http://www-cs-students.stanford.edu/~blynn/gitmagic/
http://github.com/blynn/gitmagic/tree/1e5780f658962f8f9b01638059b27275cfda095c -
CouchDB: The Definitive Guide
http://books.couchdb.org/relax/
http://groups.google.com/group/asciidoc/browse_thread/thread/a60f67cbbaf862aa/d214bf7fa2d538c4?lnk=gst&q=book#d214bf7fa2d538c4 -
Ramaze Manual
http://book.ramaze.net/
http://github.com/manveru/ramaze-book/tree/master -
Some documentation about git by Nico Schottelius (in German) http://nico.schotteli.us/papers/linux/git-firmen/.
-
The KirbyBase for Ruby database management system manual.
-
The Mercurial distributed SCM uses asciidoc for its man pages.
-
The *Nix Power Tools project uses AsciiDoc for documentation and has released an Emacs syntax highlighter (see Resources above).
-
The Battle for Wesnoth project uses AsciiDoc for it’s Manual in a number of different languages.
-
Troy Hanson uses AsciiDoc to generate user guides for the tpl and uthash projects (the HTML versions have a customised contents sidebar).
-
Leonid Volnitsky’s site is generated using AsciiDoc and includes Leonid’s matplotlib filter.
-
WeeChat uses AsciiDoc for project documentation.
Please let me know if any of these links need updating.
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).