////
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[]