AsciiDoc is a human-readable document format, semantically equivalent to DocBookXML, but using plain textmark-up conventions. AsciiDoc documents can be created using any text editor and read “as-is”, or rendered to HTML or any other format supported by a DocBook tool-chain, i.e., PDF, TeX, Unixmanpages, e-books, slide presentations, etc.[2] Common file extensions for AsciiDoc files are adoc[3] and historically txt (as encouraged by AsciiDoc's creator).[4]
AsciiDoc was created in 2002 by Stuart Rackham, who published tools (asciidoc and a2x), written in the programming languagePython to convert plain text, human readable files to commonly used published document formats.[2]
Implementations also exist in Ruby (named Asciidoctor, released in 2013), the Java ecosystem via JRuby, the JavaScript ecosystem via Opal.js, and in Haskell and Go.
Standardizing and primacy of Asciidoctor (2019–present)
Since the start of the technical standardizing process in 2019, the Asciidoctor project has aimed to produce an independent, compatible implementation of the AsciiDoc specification in the making, with the support of Stuart Rackham, the original author of the language.[8] The official website of the AsciiDoc language has since begun linking to Asciidoctor's documentation of the language.
The start of the standardizing process in 2019 coincided with the release of Asciidoctor 2.0 and several parts of syntax being deprecated, such as single quotation marks (') to indicate italics.[9] Legacy syntax remains available through a compatibility mode.[10]
The original Python implementation by Stuart Rackham continues to be developed, and named AsciiDoc.py. Since 2021, its documentation describes it as legacy, and formally targets the older rendition of the language.[11]
The JetBrains IDE ecosystem supports AsciiDoc editing through plugins such as AsciiDoc and AsciiDoc Pro, which provide AsciiDoc documentation support including live preview, syntax highlighting and PDF export.[16]
Example
The following shows text using AsciiDoc mark-up, and a rendering similar to that produced by an AsciiDoc processor:
AsciiDoc source text
= My Article
J. Smith
https://wikipedia.org[Wikipedia] is an
on-line encyclopedia, available in
English and *many* other languages.
== Software
You can install _package-name_ by using
the `gem` command:
gem install package-name
== Hardware
Metals commonly used include:
* copper
* tin
* lead
HTML-rendered result
My Article
J. Smith
Wikipedia is an on-line encyclopedia,
available in English and many other languages.
Software
You can install package-name by using the gem command:
gem install package-name
Hardware
Metals commonly used include:
copper
tin
lead
Tools
Antora – multi-repository documentation site generator for tech writers using git
AsciiBinder – (deprecated) documentation system built on Asciidoctor for people who have many docs to maintain and republish regularly
![[icon]](?wiki_title=File:Wiki_letter_w_cropped.svg){kind=small}
