AsciiDoc is a

human-readable A human-readable medium or human-readable format is any encoding of data or information that can be naturally read by humans. In computing, ''human-readable'' data is often encoded as ASCII or Unicode text, rather than as binary data. In m ...

document format, semantically equivalent to DocBook

XML Extensible Markup Language (XML) is a markup language and file format for storing, transmitting, and reconstructing arbitrary data. It defines a set of rules for encoding documents in a format that is both human-readable and machine-readable. T ...

, but using plain-text mark-up conventions. AsciiDoc documents can be created using any

text editor A text editor is a type of computer program that edits plain text. Such programs are sometimes known as "notepad" software (e.g. Windows Notepad). Text editors are provided with operating systems and software development packages, and can be ...

and read “as-is”, or rendered to

HTML The HyperText Markup Language or HTML is the standard markup language for documents designed to be displayed in a web browser. It can be assisted by technologies such as Cascading Style Sheets (CSS) and scripting languages such as JavaS ...

or any other format supported by a DocBook tool-chain, i.e.

PDF Portable Document Format (PDF), standardized as ISO 32000, is a file format developed by Adobe in 1992 to present documents, including text formatting and images, in a manner independent of application software, hardware, and operating systems. ...

, TeX,

Unix Unix (; trademarked as UNIX) is a family of multitasking, multiuser computer operating systems that derive from the original AT&T Unix, whose development started in 1969 at the Bell Labs research center by Ken Thompson, Dennis Ritchie, ...

manpage A man page (short for manual page) is a form of software documentation usually found on a Unix or Unix-like operating system. Topics covered include computer programs (including library and system calls), formal standards and conventions, and ...

e-book An ebook (short for electronic book), also known as an e-book or eBook, is a book publication made available in digital form, consisting of text, images, or both, readable on the flat-panel display of computers or other electronic devices. A ...

s, slide presentations, etc. Common file extensions for AsciiDoc files are txt (as encouraged by AsciiDoc's creator) and adoc.

History

AsciiDoc was created in 2002 by Stuart Rackham, who published tools (‘asciidoc’ and ‘a2x’), written in the

Python programming language Python is a high-level, general-purpose programming language. Its design philosophy emphasizes code readability with the use of significant indentation. Python is dynamically-typed and garbage-collected. It supports multiple programming p ...

to convert plain-text, ‘human readable’ files to commonly used published document formats.

Asciidoctor

Ruby A ruby is a pinkish red to blood-red colored gemstone, a variety of the mineral corundum ( aluminium oxide). Ruby is one of the most popular traditional jewelry gems and is very durable. Other varieties of gem-quality corundum are called ...

implementation called ‘Asciidoctor’, released in 2013, is in use by

GitHub GitHub, Inc. () is an Internet hosting service for software development and version control using Git. It provides the distributed version control of Git plus access control, bug tracking, software feature requests, task management, cont ...

and

GitLab GitLab Inc. is an open-core company that operates GitLab, a DevOps software package which can develop, secure, and operate software. The open source software project was created by Ukrainian developer Dmitriy Zaporozhets and Dutch developer ...

. This implementation is also available in the

Java Java (; id, Jawa, ; jv, ꦗꦮ; su, ) is one of the Greater Sunda Islands in Indonesia. It is bordered by the Indian Ocean to the south and the Java Sea to the north. With a population of 151.6 million people, Java is the world's mo ...

ecosystem using JRuby and in the

JavaScript JavaScript (), often abbreviated as JS, is a programming language that is one of the core technologies of the World Wide Web, alongside HTML and CSS. As of 2022, 98% of websites use JavaScript on the client side for webpage behavior, of ...

ecosystem using Opal.js. Some of

O'Reilly Media O'Reilly Media (formerly O'Reilly & Associates) is an American learning company established by Tim O'Reilly that publishes books, produces tech conferences, and provides an online learning platform. Its distinctive brand features a woodcut of ...

's books and e-books are authored using AsciiDoc mark-up. Most of the Git project documentation is written in AsciiDoc. The AsciiDoc format is currently under standardization procedure by the

Eclipse Foundation The Eclipse Foundation AISBL is an independent, Europe-based not-for-profit corporation that acts as a steward of the Eclipse open source software development community, with legal jurisdiction in the European Union. It is an organization suppo ...

Example

The following shows text using AsciiDoc mark-up, and a rendering similar to that produced by an AsciiDoc processor:

Tools

Antora
– a multi-repository documentation site generator for tech writers using

git Git () is a distributed version control system: tracking changes in any set of files, usually used for coordinating work among programmers collaboratively developing source code during software development. Its goals include speed, data in ...

.
AsciiBinder
– (deprecated) a documentation system built on Asciidoctor for people who have a lot of docs to maintain and republish on a regular basis.
awestruct
– a static site generator inspired by Jekyll.
Asciidoc FX
– AsciiDoc Book Editor based on JavaFX 8.
AsciiDocLIVE
– AsciiDocLIVE is a free online AsciiDoc editor.

References

External links