# Asciidoctor: a Ruby text processor for AsciiDoc, and when it beats Markdown > Asciidoctor parses AsciiDoc into a document model and converts it to HTML 5, DocBook 5 and man pages. This is what it does, how to install it, and where its Ruby dependency and converter split become a problem. **asciidoctor/asciidoctor** — :gem: A fast, open source text processor and publishing toolchain, written in Ruby, for converting AsciiDoc content to HTML 5, DocBook 5, and other formats. - Repository: https://github.com/asciidoctor/asciidoctor - Website: https://asciidoctor.org - Stars: 5,218 · Forks: 844 - Language: Ruby - License: NOASSERTION - Published: 2026-09-23 · Updated: 2026-09-23 · Language: en - Canonical page: https://hysenlabs.com/projects/asciidoctor-asciidoctor ## What Asciidoctor actually converts, and for whom AsciiDoc is the language. Asciidoctor is the processor. That split is the first thing to internalise, because the repository name and the format name get used interchangeably in search queries and issue threads. Asciidoctor reads AsciiDoc source, builds a document model, and converts that model into publishable output. The built-in converters cover three formats: HTML 5, DocBook 5, and man page (manual page). Everything else, including PDF and EPUB 3, arrives through separate gems. The audience is narrower than the README's tone suggests. This is a tool for people who write documentation as plain text files kept in version control, and who want more structure than Markdown offers without moving to a full XML authoring stack. The README positions Asciidoctor as the successor to AsciiDoc.py and links a migration guide for anyone still on the older Python implementation. If your documents are short README files, the extra structure is overhead. If they are books, API references or man pages, the structure is the point. ## How the processor and its converters fit together The architecture visible in the repository is a parser plus a set of pluggable converters. The lib/ directory holds the processor; data/ holds supporting data; bin/ holds the executable entry point; man/ holds man page sources; test/ and features/ hold the test suites. A Gemfile and an asciidoctor.gemspec define the gem, and release.sh and run-tests.sh are the maintenance scripts. The converter boundary is the design decision that matters most for planning. HTML 5 output ships with a default stylesheet and integrations for Font Awesome icons, highlight.js, Rouge and Pygments for source highlighting, and MathJax for STEM processing. DocBook 5 and man page output are also built in. PDF and EPUB 3 are not, and the README says so directly. That means a documentation pipeline targeting PDF has at least two dependencies to track: the processor and the converter gem, each with its own release cadence. The same processor runs in three runtimes. Natively on Ruby, on the JVM through AsciidoctorJ, and in JavaScript environments including the browser through Asciidoctor.js. The README states plainly that being written in Ruby does not mean you need Ruby to use it. That is the escape hatch for teams that cannot ship a Ruby runtime but still want the AsciiDoc syntax. ## Installing Asciidoctor and converting your first file The README links the RubyGems page for the gem, so the standard path is a gem install. The requirements section states CRuby (MRI) 2.7 through 3.4, JRuby 9.4.0 through 10.0.2, or TruffleRuby on GraalVM, on Linux, macOS or Windows. Check your Ruby version before anything else, because the range is explicit and older or newer runtimes are outside it. The README gives the install command as a gem install of the asciidoctor gem. After it completes, the asciidoctor command is on your path. The project's man page lives at https://asciidoctor.org/man/asciidoctor, which is where the README points for command reference rather than reproducing flags inline. Point the command at a .adoc file and the default converter writes HTML 5 next to the source. Open that file in a browser and you should see the rendered document with the default stylesheet applied. The README does not spell out the invocation line in its own text, so treat the man page as the source for exact flags. If you are on a non-English Windows environment and the command fails with Encoding::UndefinedConversionError, the README's fix is to override the external and internal character encodings to utf-8 by setting the RUBYOPT environment variable to the value shown in the README: ```bash RUBYOPT="-E utf-8:utf-8" ``` The README describes this as resolving Unicode issues on those systems. It is an environment-level change, so it affects every Ruby process in that shell, not just Asciidoctor. Set it in the shell where you invoke the tool rather than globally unless you have checked what else depends on the default encoding. ## Where Asciidoctor is the wrong tool The Ruby requirement is the first real constraint, and it is not softened by the JVM and JavaScript ports. Those ports are separate projects with their own documentation. If your build image has no Ruby and you do not want to add one, you are choosing between a new runtime dependency and a different documentation toolchain. The second constraint is the converter split. A team that needs PDF output from the same source cannot treat the core gem as the whole product. The README lists EPUB 3 and PDF converters as separate gems in the ecosystem, alongside Asciidoctor Diagram, the Maven plugin and site module, the Gradle plugin, Asciidoclet, the reveal.js converter, and an IntelliJ plugin. Each of those is a dependency with its own maintenance state, and the README does not document their release cadence. The third is scale of need. If your content is a handful of Markdown files rendered by a static site generator, moving to AsciiDoc buys structure you will not use and adds a processor to your build. The AsciiDoc syntax quick reference that the README links is the honest test: read it and ask whether your documents need what is in there. Finally, the repository's licence field reads NOASSERTION, which means the metadata does not declare a recognised licence identifier. The README links a LICENSE file at the repository root. Anyone planning to redistribute Asciidoctor or embed it in a product should read that file rather than trusting the metadata label. ## Asciidoctor against Markdown, Pandoc and MkDocs The most common comparison is Asciidoctor against Markdown, and the difference is not cosmetic. Markdown has no standard way to express admonitions, tables with spans, includes, or cross-references that survive a converter change. AsciiDoc does, and Asciidoctor's document model is what makes DocBook 5 and man page output possible from the same source that produces HTML 5. Markdown-to-DocBook pipelines exist, but they go through a converter that has to guess at structure the source never expressed. Pandoc takes a different approach: one tool, many input and output formats, with a universal intermediate representation. Asciidoctor is narrower on input (AsciiDoc, via a Ruby parser) and deeper on the AsciiDoc semantics it preserves. If your need is converting between arbitrary formats, Pandoc's breadth is the match. If your need is authoring technical documentation in one format and publishing it in several, Asciidoctor's depth is the match. MkDocs is a documentation site generator built around Markdown and a configuration file. It owns the site, the theme and the navigation. Asciidoctor does not own a site; it produces documents, and site assembly is left to other tools in the ecosystem. That is a real difference in scope. Choosing Asciidoctor means you also choose how the output gets published. ## Maintenance, releases and what upgrading costs The repository is not archived, and the last push was on 2026-09-01. The recent release list shows v2.0.26 on 2025-10-24, v2.0.25 on 2025-10-17 and v2.0.24 on 2025-10-13. Those three releases landed inside twelve days, which is a burst pattern rather than a steady drip. The README's own release-version variable reads 2.0.22, older than all three, so the README text does not track the newest gem version automatically. Upgrade cost depends on which converters you use. The core gem's version is what the CHANGELOG.adoc at the repository root documents, and the README links that file. If you also depend on the PDF or EPUB 3 converter gems, an Asciidoctor upgrade can require a matching converter upgrade, and the README does not state a compatibility matrix between them. Pin both versions and read the changelog before moving. The licence situation deserves its own line. The repository metadata reports NOASSERTION rather than a named licence, while a LICENSE file exists at the root and the README links to it. That mismatch is a verification step, not a blocker. Check the LICENSE file contents against whatever your organisation requires before you build a publishing pipeline on top of the gem. ## Conclusion Adopt Asciidoctor if your team writes long technical documents in plain text and needs HTML 5, DocBook 5 or man page output from one source, and if Ruby 2.7 to 3.4, JRuby 9.4.0 to 10.0.2 or TruffleRuby is already available or acceptable on your machines. Do not adopt it if you need PDF or EPUB 3 from the core gem alone, since the README states those come from separate gems, or if nobody on the team will own a Ruby toolchain. Verify first that your Ruby version falls inside the stated range, that your Windows environment is not non-English (the README documents an Encoding::UndefinedConversionError there), and whether the NOASSERTION licence label on the repository matches the LICENSE file your legal review needs. ## FAQ ### What is the difference between AsciiDoc and Asciidoctor? AsciiDoc is the language; Asciidoctor is the processor that reads it. The README states this directly: AsciiDoc is the language, Asciidoctor is the processor. ### What does Asciidoctor do? It parses AsciiDoc into a document model and converts it to output formats. The built-in converters cover HTML 5, DocBook 5 and man pages, with PDF and EPUB 3 provided by separate gems. ### How do I install Asciidoctor? The README links the RubyGems page for the gem, so the standard install is a gem install of asciidoctor. It requires CRuby 2.7 to 3.4, JRuby 9.4.0 to 10.0.2, or TruffleRuby on GraalVM, on Linux, macOS or Windows. ### How do I install Asciidoctor PDF? The README states that PDF is provided by a separate gem rather than by the core processor, and it does not give install steps for that gem in the text. Treat it as an ecosystem dependency alongside the EPUB 3 converter. ### How do I install Asciidoctor on Windows? Installation follows the same gem path, since the requirements list Windows alongside Linux and macOS. The README warns that on a non-English Windows environment you may hit Encoding::UndefinedConversionError, and recommends setting RUBYOPT="-E utf-8:utf-8". ## Sources - [asciidoctor/asciidoctor on GitHub](https://github.com/asciidoctor/asciidoctor) - [Issues](https://github.com/asciidoctor/asciidoctor/issues) - [Project website](https://asciidoctor.org) - [README](https://github.com/asciidoctor/asciidoctor/blob/main/README.md) - [Releases](https://github.com/asciidoctor/asciidoctor/releases) --- Hysen Labs editorial analysis, written from the project's own repository and release notes. Cite the canonical page: https://hysenlabs.com/projects/asciidoctor-asciidoctor