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.

Learn about AsciiDoc

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.

If you need a condensed refresher, or want a glimpse of what AsciiDoc has to offer, check out the syntax quick reference. You can also find a side-by-side comparison with Markdown if you’re looking to upgrade.

Process your AsciiDoc content

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.

Asciidoctor.js JavaScript

Transpiles Asciidoctor into JavaScript so you can run it in the browser or a Node.js application. It provides a CLI as well as a porcelain API for methods in the Asciidoctor document model and even enables you to write Asciidoctor extensions in JavaScript.

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.

Explore Asciidoctor

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.

Extensions

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.