You can not select more than 25 topics
Topics must start with a letter or number, can include dashes ('-') and can be up to 35 characters long.
143 lines
3.9 KiB
143 lines
3.9 KiB
////
|
|
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[]
|
|
|