Supported Platforms and System Requirements
Asciidoctor operates on Linux, macOS, and Windows and requires one of the supported Ruby implementations listed in the next section.
Our general policy is to align Asciidoctor’s support of a platform version with the upstream project’s lifecycle schedule for that version. When a platform version reaches the end of active support by its maintainers or its end of life—which ever comes first—Asciidoctor no longer supports it.
Ruby runtimes
Asciidoctor requires one of the following implementations of Ruby.
| Supported Runtime | Supported Versions |
|---|---|
Ruby |
≥ 2.3 |
JRuby |
≥ 9.1 |
TruffleRuby |
≥ 20.2 |
Operating systems
| Supported OS | Supported Versions |
|---|---|
Ubuntu |
≥ 18.04 LTS |
Fedora |
≥ 36 |
macOS |
≥ macOS 11 (Big Sur) |
Microsoft |
≥ Windows 10 |
While the community tests Asciidoctor on a variety of Linux distributions, it’s only officially tested on Ubuntu and Fedora.
System encoding
Asciidoctor assumes you’re using UTF-8 encoding. To minimize encoding problems, make sure the default encoding of your system is set to UTF-8.
If you’re using a non-English Windows environment, you may bump into an Encoding::UndefinedConversionError when invoking Asciidoctor.
To solve this issue, we recommend overriding the default external and internal character encodings to utf-8.
You can do so by setting the RUBYOPT environment variable as follows:
RUBYOPT="-E utf-8:utf-8"
Once you make this change, all your Unicode headaches should be behind you.
If you’re using an IDE like Eclipse, make sure you set the encoding to UTF-8 there as well. Asciidoctor is optimized to work with UTF-8 as the default encoding.