Install Asciidoctor

Asciidoctor requires one of the following Ruby implementations:

CRuby (MRI) 2.7 – 3.4
JRuby 9.4.0 – 10.0.2
TruffleRuby (GraalVM)

Asciidoctor runs on Linux, macOS, and Windows.

Choose your installation method

The gem command installs the latest stable release of Asciidoctor directly from RubyGems.org.Before running gem install, set up a Ruby version manager such as RVM or rbenv so gems are installed in user space rather than system-wide.

Activate your Ruby version

rvm use 3.4

Install the gem

gem install asciidoctor

To install a pre-release version (such as a release candidate):

gem install asciidoctor --pre

Verify the installation

asciidoctor --version

Upgrading

gem install asciidoctor
gem cleanup asciidoctor

Running gem install again installs the new version alongside the old one. Run gem cleanup asciidoctor afterwards to remove older versions.

Use Bundler when you want to lock Asciidoctor to a specific version in a Ruby project.

Add asciidoctor to your Gemfile

Gemfile

source 'https://rubygems.org'

gem 'asciidoctor'
# Pin to a specific version:
# gem 'asciidoctor', '2.0.22'

Install dependencies

bundle install

Verify the installation

bundle exec asciidoctor --version

UpgradingUpdate the version pin in your Gemfile, then run:

bundle install

Avoid running bundle update without specifying a gem name, as it updates all gems in your project.

Install using Homebrew or MacPorts

brew install asciidoctor

If you don’t have Homebrew, follow the installation instructions first. If you don’t have MacPorts, follow the MacPorts installation instructions first.Homebrew installs Asciidoctor into an exclusive prefix that is independent of system gems.

Verify the installation

asciidoctor --version

Upgrading

brew update
brew upgrade asciidoctor

Asciidoctor is packaged for most major Linux distributions. The version provided by your package manager may lag behind the latest RubyGems release. To get the latest version, use gem install instead.

Install using your package manager

sudo apt-get install -y asciidoctor

Verify the installation

asciidoctor --version

Upgrading

sudo apt-get upgrade -y asciidoctor

Package repositories for each distribution:

On non-English Windows environments, you may encounter an Encoding::UndefinedConversionError when invoking Asciidoctor. To fix this, override the default character encodings to UTF-8 by setting the RUBYOPT environment variable:

set RUBYOPT=-E utf-8:utf-8

Add this to your shell profile or system environment variables so it persists across sessions. If you use an IDE such as Eclipse, also configure the encoding to UTF-8 there.

You have two options to get Ruby on Windows.

Install Ruby

choco install ruby

Install the asciidoctor gem

gem install asciidoctor

Verify the installation

asciidoctor --version

Upgrading

gem install asciidoctor
gem cleanup asciidoctor

The official Asciidoctor Docker image includes Asciidoctor and a set of commonly used extensions.

Pull the image

docker pull asciidoctor/docker-asciidoctor

Convert a document

Run the container with your document directory mounted as a volume:

docker run --rm -v $(pwd):/documents asciidoctor/docker-asciidoctor \
  asciidoctor document.adoc

See the docker-asciidoctor repository for full usage instructions, available tags, and extension details.

Get Started

Using Asciidoctor

Converters

Extensions

Syntax Highlighting

Migration

Tooling & Ecosystem

Choose your installation method

Build docs developers (and LLMs) love

Get Started

Using Asciidoctor

Converters

Extensions

Syntax Highlighting

Migration

Tooling & Ecosystem

​Choose your installation method

Build docs developers (and LLMs) love

Choose your installation method