AsciiDoc
| AsciiDoc file format | |
|---|---|
| Filename extensions |
.adoc, .asciidoc, .txt |
| Internet media type |
text/asciidoc, text/plain |
| Initial release | November 25, 2002 |
| Open format? | Yes |
| Website | asciidoc |
AsciiDoc is a lightweight markup language for writing technical documentation, articles, books and other structured text in a plain text form that remains legible without processing.[1] It was created by Stuart Rackham, whose first processor, written in Python, was released in November 2002,[2] as a less laborious means of producing human-readable DocBook than writing its XML by hand.[3] An AsciiDoc processor parses the source document and converts its structure into one or more output formats, such as HTML, PDF, EPUB, man pages and DocBook; the language itself is not tied to any particular output.[1]
Common file extensions for AsciiDoc files are adoc[4] and historically txt (as encouraged by AsciiDoc's creator).[5] The AsciiDoc format is being standardized by the Eclipse Foundation.[6][7]
History
[edit]Origins and AsciiDoc.py (2002–2013)
[edit]| AsciiDoc.py | |
|---|---|
| Original author | Stuart Rackham |
| Developer | AsciiDoc contributors |
| Release | 25 November 2002 |
| Stable release | |
| Written in | Python |
| Operating system | Cross-platform |
| Type | Documentation generator |
| License | GPL-2.0 |
| Website | asciidoc-py |
| Repository | github |
AsciiDoc was his answer: a plain-text format that could be translated by the asciidoc command into HTML or DocBook, the latter of which could then be processed by an existing DocBook toolchain, or by the accompanying a2x wrapper, into PDF, EPUB, DVI, LaTeX, PostScript, man pages and plain text.[3] The three AsciiDoc document types (article, book and manpage) correspond to the DocBook document types of the same names.[3]
AsciiDoc was created in 2002 by Stuart Rackham, who published tools (asciidoc and a2x), written in the programming language Python to convert plain text, human readable files to commonly used published document formats.[9] Rackham explained the motivation for AsciiDoc in the introduction to its user guide. DocBook had, in his words, "emerged as the de facto standard Open Source documentation format", but it was "a complex language" whose markup was "difficult to read and even more difficult to write directly"; he had found himself spending more time typing tags, consulting reference manuals and correcting syntax errors than writing documentation.[3]
The program was designed to be highly configurable: both the source syntax and the output markup were defined in text-based configuration files, so that users could alter the default conventions or add back ends producing other SGML or XML vocabularies.[3][10] A filter mechanism allowed content such as diagrams to be generated from text embedded in the source, which made the format attractive for single-source technical publishing.[11] The project's copyright notice credits Rackham for 2002–2013 and "AsciiDoc Contributors" from 2013 onwards; after version 8.6.9 (9 November 2013), the next release, 8.6.10, did not appear until 22 September 2017.[2][3]
Asciidoctor
[edit]| Asciidoctor | |
|---|---|
| Original author | Ryan Waldron |
| Developers | Dan Allen, Sarah White, et al. |
| Release | January 30, 2013 |
| Stable release | |
| Written in | Ruby |
| Operating system | Cross-platform |
| Type | Documentation generator |
| License | MIT |
| Website | asciidoctor |
| Repository | github |
Asciidoctor is a processor written in Ruby and first released in 2013. It has since been made available on the Java virtual machine and in JavaScript,[13][14] and the modern form of the language is in practice AsciiDoc as Asciidoctor interprets it.[15] Implementations also exist in the Java ecosystem via JRuby, the JavaScript ecosystem via Opal.js, and in Haskell and Go.
In 2020 the language was placed under the Eclipse Foundation, where a working group and a specification project are developing a formal AsciiDoc Language Specification together with a technology compatibility kit (TCK) for testing conforming processors.[16][15] AsciiDoc is a trademark of the Eclipse Foundation.[3]
Standardizing and primacy of Asciidoctor (2019-Present)
[edit]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.[17] 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.[18] Legacy syntax remains available through a compatibility mode.[19]
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.[20]
Notable applications
[edit]Software documentation
[edit]Most of the Git project documentation is written in AsciiDoc.[21] Its build instructions require AsciiDoc.py but allow Asciidoctor to be used instead,[22] and in Git 2.49 all of the documentation's .txt source files were renamed with the .adoc extension "to help content aware editors".[23] Asciidoctor is usable within GitHub[24] and GitLab.[25]
Some of O'Reilly Media's books and e-books are authored using AsciiDoc mark-up.[26] Meanwhile, some Red Hat's product documentations are written in AsciiDoc.[27] Their OpenShift container platform is sourced in AsciiDoc and converted to HTML and other formats with automation based on Asciidoctor,[28]
Contributors to the Fedora project's documentation write in AsciiDoc, which is published as a website by the static site generator Antora.[29] Antora itself uses AsciiDoc as its content markup and assembles documentation sites from one or more Git repositories in a "docs as code" workflow.[30] The Spring REST Docs project, which generates documentation for RESTful services from snippets produced by tests, uses Asciidoctor by default, with Markdown available as an alternative.[31]
Hosting platforms and editors
[edit]GitHub renders files with the extensions .asciidoc, .adoc and .asc using Asciidoctor,[32] and GitLab uses the Asciidoctor gem to convert AsciiDoc to HTML5 in wiki pages and in repository files with the .adoc or .asciidoc extension.[33] The Asciidoctor documentation site lists editor integrations, including a plug-in for IntelliJ IDEA, an extension for Visual Studio Code and a browser extension for previewing AsciiDoc files.[1]
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.[34]
Example
[edit]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 |
|---|
|
J. Smith Wikipedia is an on-line encyclopedia, available in English and many other languages.
You can install package-name by using the gem install package-name Metals commonly used include:
|
Implementations
[edit]- AsciiDoc.py, the original Python processor, now described by its maintainers as a legacy implementation of an older form of the language.[10]
- Asciidoctor, the Ruby processor, which converts AsciiDoc to HTML5 and DocBook and supports further output formats through add-on converters.[13][35] Among these, Asciidoctor PDF converts documents directly to PDF without first generating an intermediate format such as DocBook or LaTeX.[35]
- Asciidoctor.js, which up to its 3.x series was produced by transpiling the Ruby source of Asciidoctor to JavaScript with the Opal compiler,[36] and whose current documentation describes a native JavaScript implementation that runs in Node.js and in web browsers.[14]
- AsciidoctorJ, which bundles Asciidoctor and its dependencies for execution on the Java virtual machine through JRuby and exposes it as a Java API.[37]
- Independent implementations of part of the language in other languages, such as libasciidoc, a Go library that converts AsciiDoc to HTML but, according to its documentation, does not support the full syntax.[38] The document converter Pandoc reads AsciiDoc and writes both modern AsciiDoc "as interpreted by Asciidoctor" and the legacy dialect of AsciiDoc.py.[39]
See also
[edit]References
[edit]- 1 2 3 "AsciiDoc Language Documentation". Asciidoctor Docs. Retrieved 1 November 2026.
- 1 2 "AsciiDoc ChangeLog". AsciiDoc.py. Retrieved 1 November 2026.
- 1 2 3 4 5 6 7 Rackham, Stuart; et al. "AsciiDoc User Guide". AsciiDoc.py. Retrieved 1 November 2026.
- ↑ "AsciiDoc Recommended Practices". Asciidoctor.org. Retrieved 2020-03-20.
- ↑ "AsciiDoc Frequently Asked Questions". asciidoc.org. Retrieved 2020-03-20.
- ↑ "AsciiDoc Language". Eclipse.org. 27 July 2020.
- ↑ "AsciiDoc Working Group Charter". Eclipse.org.
- ↑ "Release 10.2.1". 17 July 2024. Retrieved 21 July 2024.
- ↑ "AsciiDoc". Linuxlinks.com. Archived from the original on 2016-03-03. Retrieved 2013-10-18.
- 1 2 "AsciiDoc Home Page". AsciiDoc.py. Retrieved 1 November 2026.
- ↑ Meier, Wilhelm (14 December 2012). AsciiDoc – medienneutrales, technisches Publizieren [AsciiDoc: media-neutral technical publishing] (PDF). Chemnitzer Linux-Tage 2013 (in German). Retrieved 1 November 2026.
- ↑ "Release 2.0.26". 24 October 2025. Retrieved 12 November 2025.
- 1 2 Allen, Dan (30 January 2013). "AsciiDoc, powered by Asciidoctor, returns to GitHub and its 5+ million repositories". Asciidoctor. Retrieved 1 November 2026.
- 1 2 "Asciidoctor.js Documentation". Asciidoctor Docs. Retrieved 1 November 2026.
- 1 2 "AsciiDoc Language Project". Eclipse GitLab. Eclipse Foundation. Retrieved 1 November 2026.
- ↑ "AsciiDoc Language: Creation Review". Eclipse Projects. Eclipse Foundation. Retrieved 1 November 2026.
- ↑ White, Sarah; Allen, Dan (2019-01-07). "Starting the AsciiDoc Specification Journey". Asciidoctor.org. Retrieved 2025-03-31.
- ↑ "What's New in 2.0: Asciidoctor Docs". Asciidoctor.org. 2019-03-22. Retrieved 2025-03-31.
- ↑ "Upgrade from Asciidoctor 1.5.x to 2.0". Retrieved 2025-03-31.
- ↑ Peveler, Matthew (MasterOdin) (2021-02-09). "Add small blurb on legacy nature of AsciiDoc.py". GitHub. Retrieved 2025-05-18.
- ↑ "Git wiki". Git SCM.
- ↑ "INSTALL". Git source repository. Retrieved 1 November 2026.
- ↑ "Git 2.49 Release Notes". Git source repository. Retrieved 1 November 2026.
- ↑ Allen, Dan (2013-01-30). "AsciiDoc, powered by Asciidoctor, returns to GitHub and its 5+ million repositories". Retrieved 2025-03-31.
- ↑ "Asciidoc". GitLab User Docs. Archived from the original on 2019-07-22. Retrieved 18 May 2025.
- ↑ "AsciiDoc 101 (chapter 4 of Getting Started with Atlas)". Author Welcome Kit. O'Reilly Media. Archived from the original on 14 October 2017. Retrieved 19 May 2016.
- ↑ "Red Hat Documentation". GitHub.
- ↑ "OpenShift documentation". GitHub. Retrieved 1 November 2026.
- ↑ "Contributing to Fedora Docs". Fedora Docs. Fedora Project. Retrieved 1 November 2026.
- ↑ "Antora Documentation". Antora Docs. Retrieved 1 November 2026.
- ↑ "Spring REST Docs". Spring. Retrieved 1 November 2026.
- ↑ "GitHub Markup". GitHub. Retrieved 1 November 2026.
- ↑ "AsciiDoc". GitLab Docs. Retrieved 1 November 2026.
- ↑ "AsciiDoc Pro - IntelliJ IDEs Plugin | Marketplace". JetBrains Marketplace. Retrieved 2026-02-20.
- 1 2 "Asciidoctor PDF Documentation". Asciidoctor Docs. Retrieved 1 November 2026.
- ↑ "Asciidoctor.js Documentation (version 3.0)". Asciidoctor Docs. Retrieved 1 November 2026.
- ↑ "AsciidoctorJ: Java Bindings for Asciidoctor". Asciidoctor Docs. Retrieved 1 November 2026.
- ↑ "Libasciidoc". GitHub. Retrieved 1 November 2026.
- ↑ MacFarlane, John. "Pandoc User's Guide". Pandoc. Retrieved 1 November 2026.
External links
[edit]- Official website
- AsciiDoc Language Documentation
- AsciiDoc Language project at the Eclipse Foundation
- AsciiDoc.py
- Asciidoctor on GitHub
Tools
[edit]- Antora – multi-repository documentation site generator for tech writers using git
- 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
- 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