Jump to content

AsciiDoc

From Wikipedia, the free encyclopedia
AsciiDoc file format
Filename extensions
.adoc, .asciidoc, .txt
Internet media type
text/asciidoc, text/plain
Initial releaseNovember 25, 2002; 22 years ago (2002-11-25)
Open format?Yes
Websiteasciidoc.org Edit this at Wikidata
Asciidoctor
Original author(s)Ryan Waldron
Developer(s)Dan Allen, Sarah White, et al.
Initial releaseJanuary 30, 2013; 12 years ago (2013-01-30)
Stable release
2.0.23[1] Edit this on Wikidata / 17 May 2024
Repositorygithub.com/asciidoctor
Written inRuby
Operating systemCross-platform
TypeDocumentation generator
LicenseMIT
Websiteasciidoctor.org

AsciiDoc is a human-readable document format, semantically equivalent to DocBook XML, but using plain text mark-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, Unix manpages, 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]

The AsciiDoc format is being standardized by the Eclipse Foundation.[5][6]

History

[edit]

Early history

[edit]
AsciiDoc.py
Original author(s)Stuart Rackham
Developer(s)Matthew Peveler, Dan Allen, Michel Krämer, et al.
Initial releaseNovember 25, 2002; 22 years ago (2002-11-25)
Stable release
10.2.1[7] Edit this on Wikidata / 17 July 2024
Repositorygithub.com/asciidoc/asciidoc-py3
Written inPython
Operating systemCross-platform
TypeDocumentation generator
LicenseGPL v2
Websiteasciidoc-py.github.io

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.[2]

Implementations 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)

[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.[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 version of the language.[11]

Notable applications

[edit]

Most of the Git project documentation is written in AsciiDoc.[12]

Some of O'Reilly Media's books and e-books are authored using AsciiDoc mark-up.[13]

Red Hat's product documentation is written in AsciiDoc.

Asciidoctor is usable within GitHub[14] and GitLab.[15]

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

The _package-name_ can be installed
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 using the gem command: 

gem install package-name
Hardware

Metals commonly used include:

  • copper
  • tin
  • lead

Tools

[edit]
  • 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

See also

[edit]

References

[edit]
  1. ^ "Release 2.0.23". 17 May 2024. Retrieved 20 May 2024.
  2. ^ a b "AsciiDoc". Linuxlinks.com. Archived from the original on 2016-03-03. Retrieved 2013-10-18.
  3. ^ "AsciiDoc Recommended Practices". Asciidoctor.org. Retrieved 2020-03-20.
  4. ^ "AsciiDoc Frequently Asked Questions". asciidoc.org. Retrieved 2020-03-20.
  5. ^ "AsciiDoc Language". Eclipse.org. 27 July 2020.
  6. ^ "AsciiDoc Working Group Charter". Eclipse.org.
  7. ^ "Release 10.2.1". 17 July 2024. Retrieved 21 July 2024.
  8. ^ White, Sarah; Allen, Dan (2019-01-07). "Starting the AsciiDoc Specification Journey". Asciidoctor.org. Retrieved 2025-03-31.
  9. ^ "What's New in 2.0: Asciidoctor Docs". Asciidoctor.org. 2019-03-22. Retrieved 2025-03-31.
  10. ^ "Upgrade from Asciidoctor 1.5.x to 2.0". Retrieved 2025-03-31.
  11. ^ Peveler, Matthew (MasterOdin) (2021-02-09). "Add small blurb on legacy nature of AsciiDoc.py". GitHub. Retrieved 2025-05-18.
  12. ^ "Git wiki". Git SCM.
  13. ^ "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.
  14. ^ Allen, Dan (2013-01-30). "AsciiDoc, powered by Asciidoctor, returns to GitHub and its 5+ million repositories". Retrieved 2025-03-31.
  15. ^ "Asciidoc". GitLab User Docs. Archived from the original on 2019-07-22. Retrieved 18 May 2025.
[edit]
Retrieved from "https://en.wikipedia.org/w/index.php?title=AsciiDoc&oldid=1291028514"