»Home
»User Guide
»Installation
»FAQ
»asciidoc(1)
»a2x(1)
»API
»Plugins
»Cheatsheet
»Tests
»ChangeLog
»Support
»Page Source
AsciiDoc
Text based document generation
16 July 2024: AsciiDoc 10.2.1 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.

Introduction

AsciiDoc is a text document format for writing notes, documentation, articles, books, ebooks, slideshows, web pages, man pages and blogs. AsciiDoc files can be translated to many formats including HTML, PDF, EPUB, man page.

AsciiDoc.py is a legacy processor for this syntax, handling an older rendition of AsciiDoc. As such, this will not properly handle the current AsciiDoc specification. It is suggested that unless you specifically require the AsciiDoc.py toolchain, you should find a processor that handles the modern AsciiDoc syntax.

AsciiDoc.py 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.py is free software and is licensed under the terms of the GNU General Public License version 2 (GPLv2).

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, EPUB, 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.

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 Slideshows

The Slidy backend generates HTML slideshows that can be viewed in any web browser. What’s nice is that you can create completely self contained slideshows including embedded images.

Example Web Site

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

More examples

eBook Publication

The two most popular open eBook formats are EPUB and PDF. The AsciiDoc a2x toolchain wrapper makes it easy to publish EPUB and PDF eBooks with AsciiDoc. See also example books and AsciiDoc EPUB Notes).

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.

Source code highlighter

AsciiDoc includes a source code highlighter filter that uses GNU source-highlight to highlight HTML outputs. You also have the option of using the Pygments highlighter.

Mathematical Formulae

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

The AsciiDoc LaTeX filter translates LaTeX source to an image that is automatically inserted into the AsciiDoc output documents.

AsciiDoc also has latexmath macros for DocBook outputs — they are documented in this PDF file and can be used in AsciiDoc documents processed by dblatex(1).

Editor Support

Try AsciiDoc on the Web

Thaddée Tyl has written an online live editor named AsciiDocBox to try AsciiDoc in your browser.

You can use DocGist to preview AsciiDoc files hosted on GitHub, Dropbox, and other services. DocGist also features a real-time collaboration mode.

External Resources and Applications

Here are various useful resources, feel free to open a pull request to add additional ones:

  • Check the installation page for packaged versions of AsciiDoc.

  • Asciidoctor provides a modern, compliant, and substantially faster implementation of the AsciiDoc processor written in Ruby. This implementation can also be run on the JVM (with AsciidoctorJ) or using JavaScript (with Asciidoctor.js). The Asciidoctor project now maintains the official definition of the AsciiDoc syntax.

  • Alex Efros has written an HTML formatted AsciiDoc Cheatsheet using AsciiDoc. The Asciidoctor project also provides a comprehensive AsciiDoc syntax quick reference. However, the syntax supported by Asciidoctor differs slightly, see this page for more details.

  • 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.

  • Glenn Eychaner has reworked the Asciidoc plugin for ikiwiki that was created by Karl Mowson.

  • 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.packages("ascii") from R). Briefly, ascii replaces R results in AsciiDoc document with AsciiDoc markup. More information and examples here: https://eusebe.github.io/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.

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

  • Ivo’s blog describes a ditaa filter for AsciiDoc which converts ASCII art into graphics.

  • Gollum is a git-powered wiki, it supports various formats, including AsciiDoc.

  • Gregory Romé has written an AsciiDoc plugin for the Redmine project management application.

  • Paul Hsu has started a Chinese translation of the AsciiDoc User Guide.

  • Dag Wieers has written UNOCONV. UNOCONV can export AsciiDoc outputs to OpenOffice export formats.

  • Ed Keith has written Code Extractor, it extracts code snippets from source code files and inserts them into AsciiDoc documents.

  • Ryan Tomayko has written an number of themes for AsciiDoc.

  • Lex Trotman has written codiicsa, a program that converts DocBook to AsciiDoc.

  • Qingping Hou has written an AsciiDoc backend for deck.js. deck.js is a JavaScript library for building modern HTML presentations (slideshows).

  • The guys from O’Reilly Media have posted an XSL Stylesheet to github that converts DocBook to AsciiDoc.

  • Lex Trotman has written flexndex, an index generator tool that be used with AsciiDoc.

  • Michael Haberler has created a blockdiag filter for AsciiDoc which embeds blockdiag images in AsciiDoc documents.

  • Dan Allen has written a Bootstrap backend for AsciiDoc.

  • Steven Boscarine has written Maven wrapper for AsciiDoc.

  • Christian Goltz has written Shaape, an Ascii art to image converter for AsciiDoc.

  • Eduardo Santana has written an Asciidoc Highlight for Notepad++.

  • Geany 1.23 adds document structure support for AsciiDoc.

Please let me know if any of these links need updating.

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.

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). Due 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 PRs to the asciidoc-py3 repository.

  • Post questions about using AsciiDoc or AsciiDoc syntax to the asciidoc discussion list, this keeps things transparent and gives everyone a chance to comment.

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.

Pull Requests

  • Keep pull requests small and atomic (one issue per PR) — no patch bombs.

  • If possible test your PR against the current master.

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

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