AsciiDoc is a human-readable document format, semantically equivalent to

DocBook DocBook is a Semantics (computer science), semantic markup language for technical documentation. It was originally intended for writing technical documents related to computer hardware and software, but it can be used for any other sort of docume ...

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

, but using

plain text In computing, plain text is a loose term for data (e.g. file contents) that represent only characters of readable material but not its graphical representation nor other objects ( floating-point numbers, images, etc.). It may also include a lim ...

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. An example of such program is "notepad" software (e.g. Windows Notepad). Text editors are provided with operating systems and software development packages, and can be used to c ...

and read “as-is”, or rendered to

HTML Hypertext Markup Language (HTML) is the standard markup language for documents designed to be displayed in a web browser. It defines the content and structure of web content. It is often assisted by technologies such as Cascading Style Sheets ( ...

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 Inc., Adobe in 1992 to present documents, including text formatting and images, in a manner independent of application software, computer hardware, ...

TeX Tex, TeX, TEX, may refer to: People and fictional characters * Tex (nickname), a list of people and fictional characters with the nickname * Tex Earnhardt (1930–2020), U.S. businessman * Joe Tex (1933–1982), stage name of American soul singer ...

Unix Unix (, ; trademarked as UNIX) is a family of multitasking, multi-user 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, a ...

manpage A man page (short for manual page) is a form of software documentation found on Unix and Unix-like operating systems. Topics covered include programs, system libraries, system calls, and sometimes local system details. The local host administ ...

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

s, slide presentations, etc. Common file extensions for AsciiDoc files are adoc and historically txt (as encouraged by AsciiDoc's creator). The AsciiDoc format is being standardized by the

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

History

Early history

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

programming language A programming language is a system of notation for writing computer programs. Programming languages are described in terms of their Syntax (programming languages), syntax (form) and semantics (computer science), semantics (meaning), usually def ...

Python to convert plain text, ''human readable'' files to commonly used published document formats. Implementations exist in

Ruby 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 sapph ...

(named ''Asciidoctor'', released in 2013), the

Java Java is one of the Greater Sunda Islands in Indonesia. It is bordered by the Indian Ocean to the south and the Java Sea (a part of Pacific Ocean) to the north. With a population of 156.9 million people (including Madura) in mid 2024, proje ...

ecosystem via JRuby, the

JavaScript JavaScript (), often abbreviated as JS, is a programming language and core technology of the World Wide Web, alongside HTML and CSS. Ninety-nine percent of websites use JavaScript on the client side for webpage behavior. Web browsers have ...

ecosystem via Opal.js, and in

Haskell Haskell () is a general-purpose, statically typed, purely functional programming language with type inference and lazy evaluation. Designed for teaching, research, and industrial applications, Haskell pioneered several programming language ...

and Go.

Standardizing and primacy of Asciidoctor (2019–present)

Since the start of the

technical standard A technical standard is an established Social norm, norm or requirement for a repeatable technical task which is applied to a common and repeated use of rules, conditions, guidelines or characteristics for products or related processes and producti ...

izing 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. 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 In linguistics, syntax ( ) is the study of how words and morphemes combine to form larger units such as phrases and sentences. Central concerns of syntax include word order, grammatical relations, hierarchical sentence structure (constituenc ...

being deprecated, such as single quotation marks (') to indicate italics. Legacy syntax remains available through a compatibility mode. 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.

Notable applications

Most of the Git project documentation is written in AsciiDoc. Some of

O'Reilly Media O'Reilly Media, Inc. (formerly O'Reilly & Associates) is an American learning company established by Tim O'Reilly that provides technical and professional skills development courses via an online learning platform. O'Reilly also publishes b ...

's books and e-books are authored using AsciiDoc mark-up.

Red Hat Red Hat, Inc. (formerly Red Hat Software, Inc.) is an American software company that provides open source software products to enterprises and is a subsidiary of IBM. Founded in 1993, Red Hat has its corporate headquarters in Raleigh, North ...

's product documentatio
is written in AsciiDoc
Asciidoctor is usable within

GitHub GitHub () is a Proprietary software, proprietary developer platform that allows developers to create, store, manage, and share their code. It uses Git to provide distributed version control and GitHub itself provides access control, bug trackin ...

and

GitLab GitLab is a software forge primarily developed by GitLab Inc. It is available as a community edition and a commercial edition. History GitLab was created in 2011 by Ukrainian programmer Dmitriy Zaporozhets as a side project written in Rub ...

Example

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

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
awestruct
– static site generator inspired by Jekyll
Asciidoc FX
– AsciiDoc Book Editor based on JavaFX 18
AsciiDocLIVE
– free online AsciiDoc editor
DAPS
– DocBook Authoring and Publishing Suite (DAPS) is command-line software to publish DocBook & AsciiDoc as HTML, PDF, and EPUB

References

External links

* * {{DEFAULTSORT:Asciidoc Free software programmed in Python Lightweight markup languages