//// Install and upgrade documentation for Asciidoctor Portions of this file are included in the install-toolchain and user-manual documents //// == System Requirements //tag::systemreq[] Asciidoctor works on Linux, macOS and Windows. Asciidoctor requires one of the following implementations of Ruby: * Ruby 1.8.7 * Ruby 1.9.3 * Ruby 2 (2.0.0 or better) * JRuby 1.7 (Ruby 1.8 and 1.9 modes) * JRuby 9000 * Rubinius 2.0 (Ruby 1.8 and 1.9 modes) * Opal (Javascript) We expect Asciidoctor to work with other versions of Ruby as well. We welcome your help testing those versions if you are interested in seeing them supported. //end::systemreq[] == Installing the Asciidoctor Ruby Gem //tag::intro[] Asciidoctor can be installed using the `gem` command, Bundler or a Linux package manager. //end::intro[] === Install using `gem` //tag::gem[] To install Asciidoctor using the `gem` command: . Open a terminal . Type the following `gem` command $ gem install asciidoctor If the Asciidoctor gem installed successfully, the `asciidoctor` command line interface (CLI) will be available on your PATH. To confirm that Asciidoctor is available, execute: $ asciidoctor --version The following output should appear in your terminal: Asciidoctor 1.5.6.2 [https://asciidoctor.org] Runtime Environment (ruby 2.3.0p0 [x86_64-linux]) (lc:UTF-8 fs:UTF-8 in:- ex:UTF-8) //end::gem[] === Install using Bundler //tag::bundler[] To install Asciidoctor for a project using Bundler: . Open your project's Gemfile . Add the `asciidoctor` gem using: gem 'asciidoctor' . Save the Gemfile . Open a terminal . Install the gem using the `bundle` command: $ bundle //end::bundler[] === Install on Fedora //tag::yum[] To install Asciidoctor on Fedora (or RHEL via EPEL) using the https://apps.fedoraproject.org/packages/rubygem-asciidoctor[rubygem-asciidoctor] package: . Open a terminal . Run the installation command on Fedora: + $ sudo dnf install asciidoctor The benefit of installing the gem using this method is that the package manager will also install Ruby and RubyGems if not already on your machine. //end::yum[] === Install on Debian or Ubuntu //tag::aptget[] To install Asciidoctor on Debian or Ubuntu: . Open a terminal . Type the following `apt-get` command using sudo: $ sudo apt-get install asciidoctor The benefit of installing the gem via `apt-get` is that the package manager will also install Ruby and RubyGems if not already on your machine. //end::aptget[] === Install on Alpine Linux //tag::apk[] To install Asciidoctor on Alpine Linux using the https://pkgs.alpinelinux.org/packages?name=asciidoctor[asciidoctor] package: . Open a terminal . Type the following `apk` command using sudo: $ sudo apk add asciidoctor The benefit of installing the gem via `apk` is that the package manager will also install Ruby and RubyGems if not already on your machine. //end::apk[] == Upgrading the Asciidoctor Ruby Gem //tag::upgrade[] If you have an earlier version of Asciidoctor installed, you can update the gem using the `gem` command: $ gem update asciidoctor [TIP] ==== 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 ==== On Fedora, you can update the package using: $ sudo dnf update asciidoctor TIP: Your Fedora system may be configured to automatically update packages, in which case no further action is required by you. Refer to the {fedora-docs}[Fedora docs] if you are unsure. On Debian or Ubuntu, you can update the package using: $ sudo apt-get upgrade asciidoctor On Alpine Linux, you can update the package using: $ sudo apk add --upgrade asciidoctor NOTE: The Linux packages may not be available right away after a release of the gem. It may take several weeks for the packages to be updated. If you need to upgrade to the latest version immediately, use the `gem` install option documented above. //end::upgrade[]