Last Updated on April 13, 2020
AsciiDoc is a lightweight markup language for writing notes, documentation, articles, books, ebooks, slideshows, web pages, man pages and blogs. It’s a plain text human readable/writable document format that dates back to 2002.
AsciiDoc comes with a “converter program” that converts AsciiDoc documents to XHTML, DocBook or HTML. DocBook, in turn, can be converted to other formats such as PDF, TeX, Unix manpages and many more using the tool A2X which comes with AsciiDoc. Most of the Git documentation is written in AsciiDoc.
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 AsciiDoc syntax is based on time-tested plain-text conventions from the last few decades of computing.
AsciiDoc is licenced under the terms of the GNU General Public License version 2.
Ways to Learn AsciiDoc
AsciiDoc Writer’s Guide
(PDF; 57 pages)
This guide provides a good introduction to AsciiDoc. This introduction is intended for anyone who wants to reduce the effort required to write and publish content, whether for technical documentation, articles, web pages or good ol’-fashioned prose.
This book teaches you:
- Basic structure of an AsciiDoc document;
- Create your first AsciiDoc document;
- Add other structural elements such as lists, block quotes, and source code;
- Render an AsciiDoc document to HTML, DocBook, and PDF.
AsciiDoc Syntax Quick Reference – a quick reference for the common AsciiDoc document and text formatting markup.
Cheatsheet – for AsciiDoc 8.6.9, using default CSS with translations into French, Lithuanian, Polish, Russian, Slovak, Spanish, and Ukrainian.
Good and Bad about AsciiDoc
| Advantages | |
|---|---|
 | Produces beautiful output (HTML, DocBook, PDF, ePub and more) |
| Extensible - its syntax was designed to be extended as a core feature |
| Designed to read, write and edit in raw form |
| Concise with syntax designed with the requirements of publishing in mind |
| GitHub supports AsciiDoc syntax in repositories, wikis and gists |
| Disadvantages | |
|---|---|
 | Not nearly as widely adopted or supported as Markdown |
| AsciiDoc's validation option is only available with a handful of text editors |
| Some of AsciiDoc's extras can take some time to master |
Useful Software
Asciidoctor – a fast text processor and publishing toolchain for converting AsciiDoc content to HTML5, DocBook, PDF, and other formats.
ascii – a R package for writing asciidoc, txt2tags, reStructuredText, org or textile documents with embedded R code.