Install Using Ruby Packaging

gem install

Before installing Asciidoctor using gem install, you should set up RVM to install Ruby in your home directory (i.e., user space). Then, you can safely use the gem command to install or update the Asciidoctor gem, or any other gem for that matter. When using RVM, gems are installed in a location isolated from the system.

Once you’ve installed Ruby using RVM, and you have activated it using rvm use 2.7, open a terminal and type:

$ gem install asciidoctor

If the gem installed successfully, Asciidoctor’s command line interface (CLI) will be available on your PATH. To confirm that Asciidoctor is available, execute:

$ asciidoctor --version

You should see information about the Asciidoctor version and your Ruby environment printed in the terminal.

Asciidoctor 2.0.12 [https://asciidoctor.org]
Runtime Environment (ruby 2.7.0p0 [x86_64-linux]) (lc:UTF-8 fs:UTF-8 in:- ex:UTF-8)

Install a pre-release version

To install a pre-release version of Asciidoctor (e.g., a release candidate), open a terminal and type:

$ gem install asciidoctor --pre

Bundler

  1. Create a Gemfile in the root folder of your project (or the current directory)

  2. Add the asciidoctor gem to your Gemfile as follows:

    source 'https://rubygems.org'
gem 'asciidoctor'
# or specify the version explicitly
# gem 'asciidoctor', '2.0.12'

  3. Save the Gemfile

  4. Open a terminal and install the gem using:

    $ bundle

To upgrade the gem, specify the new version in the Gemfile and run bundle again. Using bundle update (without specifying a gem) is not recommended as it will also update other gems, which may not be the desired result.

Upgrade using gem update

You’re advised against using the gem update command to update a gem managed by the package manager. Doing so puts the system into an inconsistent state as the package manager can no longer track the files (which get installed under /usr/local). Simply put, system gems should only be updated by the package manager.

If you want to use a version of Asciidoctor that is newer than what is installed by the package manager, you should use RVM to install Ruby in your home directory (i.e., user space). Then, you can safely use the gem command to install or update the Asciidoctor gem. When using RVM, gems are installed in a location isolated from the system.

You can upgrade Asciidoctor using the gem update command:

$ gem update asciidoctor

If you accidentally use gem install instead of gem update, then you’ll end up with both versions installed. To remove the older version, use the following gem command:

$ gem cleanup asciidoctor