AsciiDoc Home Page
Description: Text based document generation
Keywords: text to HTML, text to DocBook, text to XML, AsciiDoc

AsciiDoc
Text based document generation

»Home »Man Page »User Guide »a2x »README »ChangeLog »Installation »Downloads »FAQ »Support »Page Source | # AsciiDoc Home Page This release fixes couple of bugs in 8.2.4, in particular a nasty regression bug (`future feature with_statement is not defined`). No new features have been added. This release adds support for language specific configuration files along with a couple of other fairly minor additions. A read-only copy of the AsciiDoc Mercurial repository is now available online. The big news is the upcoming AsciiDoc version 9 release which has been undertaken by Yannick Gingras. See here for details. Read the CHANGELOG for a full description of additions and changes. Stuart Rackham ## 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, 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. This 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 using `xsltproc(1)`, DocBook XSL Stylesheets and FOP. ### 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. ## Mathematical Formulae You can include mathematical formulae in your AsciiDoc documents using ASCIIMathML or LaTeXMathML notation. ## Vim Syntax Highlighter An AsciiDoc syntax highlighter for the Vim text editor is included in the AsciiDoc distribution (see Appendix J 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 Check the Downloads page for packaged versions of AsciiDoc. Thomas Berker has written an AsciiDoc Cheatsheet. The WikiMatrix website has an excellent web page that compares the various Wiki markup syntaxes. An interesting attempt at Wiki markup standardization is CREOLE. 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. ## 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). Here's Benjamin's documentation. ## 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. The Linux kernel git source code management system. 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. 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. The *Nix Power Tools project uses AsciiDoc for documentation and has released an Emacs syntax highlighter (see Resources above). ## AsciiDoc version 9 The next version of AsciiDoc is underway — details here.