AsciiDoc

AsciiDoc file format
Filename extensions
.adoc, .asciidoc, .txt
Internet media type
text/asciidoc, text/plain
Initial releaseNovember 25, 2002; 23 years ago (2002-11-25)
Open format?Yes
Websiteasciidoc.org Edit this at Wikidata

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. It was created by Stuart Rackham, whose first processor, written in Python, was released in November 2002, as a less laborious means of producing human-readable DocBook than writing its XML by hand. 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.

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.

History

Origins and AsciiDoc.py (2002–2013)

AsciiDoc.py
Original authorStuart Rackham
DeveloperAsciiDoc contributors
Release25 November 2002; 23 years ago (2002-11-25)
Stable release
10.2.1 Edit this on Wikidata / 17 July 2024
Written inPython
Operating systemCross-platform
TypeDocumentation generator
LicenseGPL-2.0
Websiteasciidoc-py.github.io
Repositorygithub.com/asciidoc-py/asciidoc-py

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. The three AsciiDoc document types (article, book and manpage) correspond to the DocBook document types of the same names.

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

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

Asciidoctor

Asciidoctor
Original authorRyan Waldron
DevelopersDan Allen, Sarah White, et al.
ReleaseJanuary 30, 2013; 13 years ago (2013-01-30)
Stable release
2.0.26 Edit this on Wikidata / 24 October 2025
Written inRuby
Operating systemCross-platform
TypeDocumentation generator
LicenseMIT
Websiteasciidoctor.org
Repositorygithub.com/asciidoctor

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, and the modern form of the language is in practice AsciiDoc as Asciidoctor interprets it. 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. AsciiDoc is a trademark of the Eclipse Foundation.

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

Software documentation

Most of the Git project documentation is written in AsciiDoc. Its build instructions require AsciiDoc.py but allow Asciidoctor to be used instead, and in Git 2.49 all of the documentation's .txt source files were renamed with the .adoc extension "to help content aware editors". Asciidoctor is usable within GitHub and GitLab.

Some of O'Reilly Media's books and e-books are authored using AsciiDoc mark-up. Meanwhile, some Red Hat's product documentations are written in AsciiDoc. Their OpenShift container platform is sourced in AsciiDoc and converted to HTML and other formats with automation based on Asciidoctor,

Contributors to the Fedora project's documentation write in AsciiDoc, which is published as a website by the static site generator Antora. Antora itself uses AsciiDoc as its content markup and assembles documentation sites from one or more Git repositories in a "docs as code" workflow. 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.

Hosting platforms and editors

GitHub renders files with the extensions .asciidoc, .adoc and .asc using Asciidoctor, and GitLab uses the Asciidoctor gem to convert AsciiDoc to HTML5 in wiki pages and in repository files with the .adoc or .asciidoc extension. 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.

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.

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

Implementations

See also

References

  1. 1 2 3 "AsciiDoc Language Documentation". Asciidoctor Docs. Retrieved 1 November 2026.
  2. 1 2 "AsciiDoc ChangeLog". AsciiDoc.py. Retrieved 1 November 2026.
  3. 1 2 3 4 5 6 7 Rackham, Stuart; et al. "AsciiDoc User Guide". AsciiDoc.py. Retrieved 1 November 2026.
  4. ↑ "AsciiDoc Recommended Practices". Asciidoctor.org. Retrieved 2020-03-20.
  5. ↑ "AsciiDoc Frequently Asked Questions". asciidoc.org. Retrieved 2020-03-20.
  6. ↑ "AsciiDoc Language". Eclipse.org. 27 July 2020.
  7. ↑ "AsciiDoc Working Group Charter". Eclipse.org.
  8. ↑ "Release 10.2.1". 17 July 2024. Retrieved 21 July 2024.
  9. ↑ "AsciiDoc". Linuxlinks.com. Archived from the original on 2016-03-03. Retrieved 2013-10-18.
  10. 1 2 "AsciiDoc Home Page". AsciiDoc.py. Retrieved 1 November 2026.
  11. ↑ 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.
  12. ↑ "Release 2.0.26". 24 October 2025. Retrieved 12 November 2025.
  13. 1 2 Allen, Dan (30 January 2013). "AsciiDoc, powered by Asciidoctor, returns to GitHub and its 5+ million repositories". Asciidoctor. Retrieved 1 November 2026.
  14. 1 2 "Asciidoctor.js Documentation". Asciidoctor Docs. Retrieved 1 November 2026.
  15. 1 2 "AsciiDoc Language Project". Eclipse GitLab. Eclipse Foundation. Retrieved 1 November 2026.
  16. ↑ "AsciiDoc Language: Creation Review". Eclipse Projects. Eclipse Foundation. Retrieved 1 November 2026.
  17. ↑ White, Sarah; Allen, Dan (2019-01-07). "Starting the AsciiDoc Specification Journey". Asciidoctor.org. Retrieved 2025-03-31.
  18. ↑ "What's New in 2.0: Asciidoctor Docs". Asciidoctor.org. 2019-03-22. Retrieved 2025-03-31.
  19. ↑ "Upgrade from Asciidoctor 1.5.x to 2.0". Retrieved 2025-03-31.
  20. ↑ Peveler, Matthew (MasterOdin) (2021-02-09). "Add small blurb on legacy nature of AsciiDoc.py". GitHub. Retrieved 2025-05-18.
  21. ↑ "Git wiki". Git SCM.
  22. ↑ "INSTALL". Git source repository. Retrieved 1 November 2026.
  23. ↑ "Git 2.49 Release Notes". Git source repository. Retrieved 1 November 2026.
  24. ↑ Allen, Dan (2013-01-30). "AsciiDoc, powered by Asciidoctor, returns to GitHub and its 5+ million repositories". Retrieved 2025-03-31.
  25. ↑ "Asciidoc". GitLab User Docs. Archived from the original on 2019-07-22. Retrieved 18 May 2025.
  26. ↑ "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.
  27. ↑ "Red Hat Documentation". GitHub.
  28. ↑ "OpenShift documentation". GitHub. Retrieved 1 November 2026.
  29. ↑ "Contributing to Fedora Docs". Fedora Docs. Fedora Project. Retrieved 1 November 2026.
  30. ↑ "Antora Documentation". Antora Docs. Retrieved 1 November 2026.
  31. ↑ "Spring REST Docs". Spring. Retrieved 1 November 2026.
  32. ↑ "GitHub Markup". GitHub. Retrieved 1 November 2026.
  33. ↑ "AsciiDoc". GitLab Docs. Retrieved 1 November 2026.
  34. ↑ "AsciiDoc Pro - IntelliJ IDEs Plugin | Marketplace". JetBrains Marketplace. Retrieved 2026-02-20.
  35. 1 2 "Asciidoctor PDF Documentation". Asciidoctor Docs. Retrieved 1 November 2026.
  36. ↑ "AsciidoctorJ: Java Bindings for Asciidoctor". Asciidoctor Docs. Retrieved 1 November 2026.
  37. ↑ "Asciidoctor.js Documentation (version 3.0)". Asciidoctor Docs. Retrieved 1 November 2026.
  38. ↑ "Libasciidoc". GitHub. Retrieved 1 November 2026.
  39. ↑ MacFarlane, John. "Pandoc User's Guide". Pandoc. Retrieved 1 November 2026.

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