1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
|
= Asciidoctor Documentation
:navtitle: Introduction
:description: A brief introduction to Asciidoctor, its ecosystem, its relationship to AsciiDoc, and the language platforms on which it runs.
This is the documentation for the Ruby-based AsciiDoc processor named Asciidoctor.
Asciidoctor currently serves as the reference implementation for how to interpret the AsciiDoc language.
If you're looking for the documentation for the AsciiDoc language, see the xref:asciidoc::index.adoc[AsciiDoc section] of this website.
== What is Asciidoctor?
Asciidoctor is a fast, open source, text processor for parsing AsciiDoc into a document model, then converting it to output formats such as [.nowrap]#HTML 5#, [.nowrap]#DocBook 5#, man(ual) pages, PDF, and [.nowrap]#EPUB 3#.
Asciidoctor is written in the Ruby programming language.
When we use the name "`Asciidoctor`" in this area of the documentation, we're referring to the core Asciidoctor Ruby processor, abbreviated as _Asciidoctor core_ or _Asciidoctor Ruby_.
We add the qualifier "`core`" because Asciidoctor is also the name of the suite of projects that provides runtimes, extensions, and tools for processing AsciiDoc.
To simplify installation, Asciidoctor is packaged as a gem named {url-rubygems}/asciidoctor[asciidoctor^] and published to the gem hosting service located at RubyGems.org.
A https://guides.rubygems.org/what-is-a-gem/[gem^] is a packaged Ruby application or library (in this case, both).
The *asciidoctor* gem can be installed directly from RubyGems.org on all major operating systems using Ruby packaging tools (gem or bundle).
Asciidoctor is also distributed as a Docker image, as a package for numerous Linux distributions, and as a package for macOS (via Homebrew and MacPorts).
Asciidoctor is open source software available under the terms of the MIT license and {url-org}[hosted on GitHub^].
Asciidoctor is the successor to AsciiDoc.py, the legacy Python-based processor for the AsciiDoc language.
If you're using AsciiDoc.py, follow xref:migrate:asciidoc-py.adoc[] to learn how to upgrade to Asciidoctor.
== Basic usage
Asciidoctor provides two interfaces for processing AsciiDoc documents, a xref:cli:index.adoc[CLI] named `asciidoctor` and a xref:api:index.adoc[Ruby API] named `Asciidoctor`.
The following table gives you an idea of how to use these interfaces.
|===
^|CLI ^|API
a|
$ asciidoctor document.adoc
a|
[,ruby]
----
require 'asciidoctor'
Asciidoctor.convert_file \
'document.adoc', safe: :safe
----
|See xref:cli:index.adoc[] to learn more about this interface.
|See xref:api:index.adoc[] to learn more about this interface.
|===
== Relationship to AsciiDoc
AsciiDoc is the language. +
Asciidoctor is the processor.
You compose documents using the xref:asciidoc::index.adoc[AsciiDoc language], which is a text-based writing format.
The AsciiDoc language was designed to be unobtrusive and concise to simplify writing and make it more pleasant.
But AsciiDoc itself is not a publishing format.
It's more like a shorthand.
That's where an AsciiDoc processor comes in.
//Asciidoctor reads and parses text written in the AsciiDoc syntax, then feeds the parse tree into a set of built-in templates to produce HTML, PDF, DocBook, man page, and other output formats.
//You have the option of writing your own converter or loading Tilt-supported templates to customize the generated output or produce alternative formats.
//Asciidoctor also offers a responsive theme based on Foundation to style the HTML5 output.
An AsciiDoc processor, such as Asciidoctor, reads the AsciiDoc source and converts it to publishable formats such as HTML 5 or PDF.
It can also convert it to formats which themselves can be processed by a publishing toolchain, such as DocBook.
Since AsciiDoc is not published as is, the processing step provides an opportunity to augment the document by expanding shorthand codes, layering in integrations, and applying a pleasant visual style.
That augmentation is a large part of what Asciidoctor does.
In brief, you give AsciiDoc source to Asciidoctor and it gives you a result you can publish.
== Ecosystem
When we talk about Asciidoctor in this section, we are talking about the core processor and built-in converters.
Asciidoctor also has an ecosystem of extensions, converters, build plugins, and tools to help you author and publish content written in AsciiDoc.
You can find the documentation for these projects elsewhere on this site or in the Asciidoctor organization on GitHub.
== Beyond Ruby
Although Asciidoctor is written in Ruby, it does not mean you need Ruby to use it.
You can also run Asciidoctor using a JVM via AsciidoctorJ or JavaScript via Asciidoctor.js.
=== Java / JVM
Thanks to xref:asciidoctorj::index.adoc[AsciidoctorJ], Asciidoctor can be used in any program that runs on a Java Virtual Machine (JVM).
Under the covers, AsciidoctorJ uses JRuby to run Asciidoctor, but this is hidden behind a Java API.
AsciidoctorJ even provides an alternate CLI, which means you can get the full Asciidoctor experience with only a Java runtime.
Building atop AsciidoctorJ, there are also plugins that integrate Asciidoctor into Apache Maven, Gradle, or Javadoc builds.
=== JavaScript
Thanks to xref:asciidoctor.js::index.adoc[Asciidoctor.js], Asciidoctor can also be used in JavaScript.
The Asciidoctor.js project uses Opal to transpile the Ruby source in Asciidoctor to JavaScript.
The result is a fully-functional version of Asciidoctor that works on any JavaScript runtime, such as a modern browser or Node.js.
Asciidoctor.js even provides an alternate CLI, which means you can get the full Asciidoctor experience with only a JavaScript runtime.
Asciidoctor.js is used to power the AsciiDoc language preview extensions for Chrome, Atom, Brackets, and other web-based tooling.
To be accurate, you can run Asciidoctor using Ruby, a JVM, or JavaScript.
This documentation focuses on the Ruby version of Asciidoctor.
|
