Asciidoctor Documentation Home
Welcome to the Asciidoctor documentation site! Here you can find the reference materials, guides, and examples to write and publish content in AsciiDoc using Asciidoctor. This documentation will help you start your journey with AsciiDoc or dive deeper if you’re already well on your way.
AsciiDoc is a plain text authoring format (i.e., lightweight markup language) for writing technical content such as documentation, articles, and blog posts. If you’re just starting out with AsciiDoc, or want to discover what it’s all about, head over to the documentation for the AsciiDoc Language. You’ll learn everything from how to make your first AsciiDoc document to how to use advanced language features such as list continuations and tailoring substitutions.
The AsciiDoc language documentation is primarily about the source you type to compose a document. One you’re done writing and want to publish your AsciiDoc document, you’ll need an AsciiDoc processor. That’s where Asciidoctor fits in.
Asciidoctor is the core AsciiDoc processor. It reads the AsciiDoc source, parses it into a document model, and converts it to a publishable format such as HTML using a converter. Asciidoctor has both a CLI and an API that you can use to invoke a built-in converter (HTML, DocBook, man page) or an add-on converter. Asciidoctor enriches the HTML it produces from AsciiDoc by applying a default stylesheet, adding stylistic icons, and syntax highlighting source blocks.
Choose a processor
There are three variants of the core Asciidoctor processor that all share the same code base. With few exceptions, these variants all provide the full Asciidoctor experience. From these three implementations extend a host of extensions, build tool integrations, and tooling plugins in the Asciidoctor community and beyond. Choose the one that best suits the language platform you’re using.
- Asciidoctor Ruby
The original code base enables you to run Asciidoctor using any Ruby implementation, including C Ruby, JRuby, and TruffleRuby. JRuby and TruffleRuby allow you to use Asciidoctor on a JVM.
- AsciidoctorJ Java/JVM
A Java library that encapsulates the use of JRuby to load and run Asciidoctor on the JVM. It provides a CLI as well as native Java API wrappers for all of the Asciidoctor APIs and even enables you to write Asciidoctor extensions in Java.
- Build automation
Convert your content from AsciiDoc automatically when you run your build. Encapsulate assets, configuration profiles, and extensions for your publishing process in your build scripts. Even extract and convert AsciiDoc inside Javadoc comments or include snippets from your test suite.
Author HTML slide presentations in AsciiDoc without having to wrestle with the clutter of HTML or add diagrams to the output file that are generated from plain text markup inside your AsciiDoc document using extensions. The possiblities are boundless!
- Site generation
Want to build a documentation site like this one? Write the content for the site in AsciiDoc. A static site generator delegates to an AsciiDoc processor to convert the AsciiDoc files to embedded HTML, then applies a template to that HTML to generate pages for the site.
- Essential reference
Keep this essential reference material for writing and publishing content with AsciiDoc and Asciidoctor close at hand.
How to search the docs
On any page, you can press the s key to focus the search box. Enter one or more terms (i.e., a query) to search the documentation. As you enter your query, the search results will be displayed in a panel immediately below the search box. You can navigate the search results either using the mouse or the up and down keys. To navigate to a result, hover over it with the mouse curosr and click it with the left mouse button. You can also press Enter (or Tab) when the result is highlighted with the light blue selection box to navigate to a result.
The search will look for results using fuzzy matching.
That means it will locate pages with words or phrases that are close to what you entered, but not exactly.
This strategy helps bridge the gap between your terminology or phrasing with that used in the documentation.
If you want to look for an exact match, enclose the query in double quotes (e.g.,
"the details of the syntax").
This strategy helps you to find exactly what you’re looking for with no false positives.
However, it will yield less results.
By default, the search looks for results across the whole documentation site. If you want to limit the scope of the search to the documentation for the version of the project you’re currently looking at, tick the "In this project" checkbox.
If you want to keep the search results open while you are looking for the best result, you can open the result in a new tab in the normal way. For example, you can right click on the result and select "Open link in new tab" or you can hold down Ctrl when you click the link. To close the search results, press Esc or click anywhere outside of the panel of search results.