asciidoctor.orgAsciidoctor | A fast, open source text processor and publishing toolchain for converting AsciiDoc co

Asciidoctor About News Gist Code Discuss Docs Get Writing! Asciidoctor A fast text processor & publishing toolchain for converting AsciiDoc to HTML5, DocBook & more. Download gem from RubyGems Checkout source from GitHub = Hello, AsciiDoc! Doc Writer <doc@example.com> An introduction to http://asciidoc.org[AsciiDoc]. == First Section * item 1 * item 2 [source,ruby] puts "Hello, World!" Asciidoctor is a fast , open source text processor and publishing toolchain for converting AsciiDoc content to HTML5, DocBook, PDF, and other formats. Asciidoctor is written in Ruby and runs on all major operating systems. The Asciidoctor project is hosted on GitHub . To simplify installation, Asciidoctor is packaged and distributed as a RubyGem (aka gem) to RubyGems.org . It’s also distributed as a package for popular Linux distributions and macOS. In addition to running on Ruby, Asciidoctor can be executed on a JVM using AsciidoctorJ or in any JavaScript environment (including the browser) using Asciidoctor.js . Key documentation What is AsciiDoc? AsciiDoc Writer’s Guide Asciidoctor User Manual AsciiDoc Syntax Reference Sponsors We want to recognize our sponsors for their commitment to improving the state of technical documentation by supporting this project. Thank you sponsors! Without your generous support, Asciidoctor would not be possible. You can support this project by becoming a sponsor through OpenCollective . The Big Picture Asciidoctor reads content written in plain text, as shown in the panel on the left in the image below, and converts it to HTML5, as shown rendered in the right panel. Asciidoctor applies a default stylesheet to the HTML5 document to provide a pleasant out-of-the-box experience. AsciiDoc Processing Asciidoctor reads and parses text written in the AsciiDoc syntax, then feeds the parse tree to a set of built-in converters to produce HTML5, DocBook 5, and man(ual) page output. You have the option of using your own converter or loading Tilt -supported templates to customize the generated output or produce additional formats. Asciidoctor is a drop-in replacement for its predecessor, AsciiDoc Python ( asciidoc.py ). The Asciidoctor test suite has > 2,350 tests to ensure compatibility with the AsciiDoc syntax. In addition to the classic AsciiDoc syntax, Asciidoctor recognizes additional markup and formatting options, such as font-based icons (e.g., icon:fire[] ) and UI elements (e.g., button:[Save] ). Asciidoctor also offers a modern, responsive theme based on Foundation to style the HTML5 output. Where Ruby goes, Asciidoctor follows You can run Asciidoctor on the JVM using JRuby. To invoke the Asciidoctor API directly from Java and other JVM languages, use AsciidoctorJ . There are plugins available for Apache Maven , Gradle , and Javadoc , which allow you to integrate AsciiDoc processing directly into your build using AsciidoctorJ. Asciidoctor also runs in JavaScript. Opal is used to transcompile the Ruby source to JavaScript to produce Asciidoctor.js . Asciidoctor.js is a fully-functional version of Asciidoctor that works in any JavaScript environment, such as a web browser or Node.js. It’s used to power the AsciiDoc preview extensions for Chrome, Atom, Brackets and other web-based tooling. Requirements Asciidoctor works on Linux, macOS and Windows and requires one of the following implementations of Ruby : CRuby (aka MRI) 2.3 - 2.6 JRuby 9.1 - 9.2 TruffleRuby (GraalVM) Opal (JavaScript) 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 changing the active code page in your console to UTF-8: chcp 65001 Once you make this change, all your Unicode headaches will be behind you. If you’re using an IDE like Eclipse, make sure you set the encoding to UTF-8 there as well. Asciidoctor works best when you use UTF-8 everywhere. Installation Asciidoctor can be installed using (a) package managers for popular Linux distributions, (b) Homebrew for macOS, (c) the gem install command (recommended for Windows users), (d) the Asciidoctor Docker image, or (e) Bundler. The benefit of using your operating system’s package manager to install the gem is that it handles installing Ruby and the RubyGems library if those packages are not already installed on your machine. (a) Linux package managers The version of Asciidoctor installed by the package manager may not match the latest release of Asciidoctor. Consult the package repository for your distribution to find out which version is packaged per distribution release. Alpine Linux (asciidoctor) Arch Linux (asciidoctor) Debian (asciidoctor) Fedora (asciidoctor) OpenSUSE (rubygem-asciidoctor) Ubuntu (asciidoctor) If you want to use a version of Asciidoctor that is newer than what is installed by the package manager, see the gem installation instructions . apk (Alpine Linux) To install the gem on Alpine Linux, open a terminal and type: $ sudo apk add asciidoctor pacman (Arch Linux) To install the gem on Arch-based distributions, open a terminal and type: $ sudo pacman -S asciidoctor APT On Debian and Debian-based distributions such as Ubuntu, use APT to install Asciidoctor. To install the package, open a terminal and type: $ sudo apt-get install -y asciidoctor DNF On RPM-based Linux distributions, such as Fedora, CentOS, and RHEL, use the DNF package manager to install Asciidoctor. To install the package, open a terminal and type: $ sudo dnf install -y asciidoctor (b) Homebrew (macOS) You can use Homebrew, the macOS package manager, to install Asciidoctor. If you don’t have Homebrew on your computer, complete the installation instructions at brew.sh first. Once Homebrew is installed, you’re ready to install the asciidoctor gem. Open a terminal and type: $ brew install asciidoctor Homebrew installs the asciidoctor gem into an exclusive prefix that’s independent of system gems. (c) Windows To use Asciidoctor with Windows, you have two easy options. Chocolatey When you already use chocolatey on your machine, you can use: choco install ruby Then follow gem installation instructions . Rubyinstaller Or you use the Rubyinstaller , download the package for your Windows Version and after the installation go ahead with gem installation instructions . (d) gem install Before installing Asciidoctor using gem install , 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. Open a terminal and type: $ gem install asciidoctor If you want to install a pre-release version (e.g., a release candidate), use: $ gem install asciidoctor --pre (e) Docker See Installing Asciidoctor using Docker . (f) Bundler Create a Gemfile in the root folder of your project (or the current directory) Add the asciidoctor gem to your Gemfile as follows: source ' https://rubygems.org ' gem ' asciidoctor ' # or specify the version explicitly # gem 'asciidoctor', '2.0.10' Save the Gemfile 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 If you installed Asciidoctor using a package manager, your operating system is probably configured to automatically update packages, in which case you don’t need to update the gem manually. apk (Alpine Linux) To upgrade the gem, use: $ sudo apk add -u asciidoctor APT To upgrade the gem, use: $ sudo apt-get upgrade -y asciidoctor DNF To upgrade the gem, use: $ sudo dnf update -y asciidoctor Homebrew (macOS) To upgrade the gem, use: $ brew update $ brew upgrade asciidoctor gem install If you previously installed Asciidoctor using the gem command, you’ll need to manually upgrade Asciidoctor when a...