AsciiDoc – text document format for writing

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)Ascii-DocWriters-Guide

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


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

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.

Project page

Notify of

This site uses Akismet to reduce spam. Learn how your comment data is processed.

Inline Feedbacks
View all comments