= Asciidoctor
Dan Allen <https://github.com/mojavelinux[@mojavelinux]>; Sarah White <https://github.com/graphitefriction[@graphitefriction]>; Ryan Waldron <https://github.com/erebor[@erebor]>
v1.5.7, 2018-05-02
// settings:
:idprefix:
:idseparator: -
:source-language: ruby
:language: {source-language}
ifndef::env-github[:icons: font]
ifdef::env-github[]
:status:
:outfilesuffix: .adoc
:caution-caption: :fire:
:important-caption: :exclamation:
:note-caption: :paperclip:
:tip-caption: :bulb:
:warning-caption: :warning:
endif::[]
// Variables:
:release-version: 1.5.7
// URIs:
:uri-org: https://github.com/asciidoctor
:uri-repo: {uri-org}/asciidoctor
:uri-asciidoctorj: {uri-org}/asciidoctorj
:uri-asciidoctorjs: {uri-org}/asciidoctor.js
:uri-project: https://asciidoctor.org
ifdef::env-site[:uri-project: link:]
:uri-docs: {uri-project}/docs
:uri-news: {uri-project}/news
:uri-manpage: {uri-project}/man/asciidoctor
:uri-issues: {uri-repo}/issues
:uri-contributors: {uri-repo}/graphs/contributors
:uri-rel-file-base: link:
:uri-rel-tree-base: link:
ifdef::env-site[]
:uri-rel-file-base: {uri-repo}/blob/master/
:uri-rel-tree-base: {uri-repo}/tree/master/
endif::[]
:uri-changelog: {uri-rel-file-base}CHANGELOG.adoc
:uri-contribute: {uri-rel-file-base}CONTRIBUTING.adoc
:uri-license: {uri-rel-file-base}LICENSE
:uri-tests: {uri-rel-tree-base}test
:uri-discuss: http://discuss.asciidoctor.org
:uri-irc: irc://irc.freenode.org/#asciidoctor
:uri-rubygem: https://rubygems.org/gems/asciidoctor
:uri-what-is-asciidoc: {uri-docs}/what-is-asciidoc
:uri-user-manual: {uri-docs}/user-manual
:uri-install-docker: https://github.com/asciidoctor/docker-asciidoctor
//:uri-install-doc: {uri-docs}/install-toolchain
:uri-install-macos-doc: {uri-docs}/install-asciidoctor-macos
:uri-render-doc: {uri-docs}/render-documents
:uri-themes-doc: {uri-docs}/produce-custom-themes-using-asciidoctor-stylesheet-factory
:uri-gitscm-repo: https://github.com/git/git-scm.com
:uri-prototype: {uri-gitscm-repo}/commits/master/lib/asciidoc.rb
:uri-freesoftware: https://www.gnu.org/philosophy/free-sw.html
:uri-foundation: https://foundation.zurb.com
:uri-tilt: https://github.com/rtomayko/tilt
:uri-ruby: https://www.ruby-lang.org
// images:
:image-uri-screenshot: https://raw.githubusercontent.com/asciidoctor/asciidoctor/master/screenshot.png

{uri-project}[Asciidoctor] is a _fast_ text processor and publishing toolchain for converting {uri-what-is-asciidoc}[AsciiDoc] content to HTML5, DocBook, PDF, and other formats.
Asciidoctor is written in Ruby, packaged and distributed as a gem to {uri-rubygem}[RubyGems.org], and packaged for popular Linux distributions, including Fedora, Debian, Ubuntu, and Alpine.
Asciidoctor can be run on the JVM using AsciidoctorJ and in all JavaScript environments using Asciidoctor.js.
Asciidoctor is {uri-license}[open source software] and {uri-repo}[hosted on GitHub].

ifndef::env-site[]
This document is also available in the following languages: +
{uri-rel-file-base}README-zh_CN.adoc[汉语]
|
{uri-rel-file-base}README-fr.adoc[Français]
|
{uri-rel-file-base}README-jp.adoc[日本語]
endif::[]

.Key documentation
[.compact]
* {uri-docs}/what-is-asciidoc[What is AsciiDoc?]
* {uri-docs}/asciidoc-writers-guide[AsciiDoc Writer's Guide]
* {uri-docs}/user-manual[Asciidoctor User Manual]
* {uri-docs}/asciidoc-syntax-quick-reference[AsciiDoc Syntax Reference]

ifdef::status[]
.*Project health*
image:https://img.shields.io/travis/asciidoctor/asciidoctor/master.svg[Build Status (Travis CI), link=https://travis-ci.org/asciidoctor/asciidoctor]
image:https://ci.appveyor.com/api/projects/status/ifplu67oxvgn6ceq/branch/master?svg=true&amp;passingText=green%20bar&amp;failingText=%23fail&amp;pendingText=building%2E%2E%2E[Build Status (AppVeyor), link=https://ci.appveyor.com/project/asciidoctor/asciidoctor]
//image:https://img.shields.io/coveralls/asciidoctor/asciidoctor/master.svg[Coverage Status, link=https://coveralls.io/r/asciidoctor/asciidoctor]
//image:https://codeclimate.com/github/asciidoctor/asciidoctor/badges/gpa.svg[Code Climate, link="https://codeclimate.com/github/asciidoctor/asciidoctor"]
image:https://inch-ci.org/github/asciidoctor/asciidoctor.svg?branch=master[Inline docs, link="https://inch-ci.org/github/asciidoctor/asciidoctor"]
endif::[]

== Sponsors

We want to recognize our generous sponsors, without whose support Asciidoctor would not be possible.
Thank you sponsors for your dedication to improving the state of technical documentation!

image:https://www.okta.com/sites/all/themes/Okta/images/blog/Logos/Okta_Logo_BrightBlue_Medium.png[Okta,280,link=https://developer.okta.com/signup?utm_source=asciidoctor&utm_medium=logo&utm_campaign=sponsor,title="Add User Auth to Your Apps in Minutes with Okta"]
&nbsp; &nbsp; &nbsp;
image:https://secure.gravatar.com/avatar/823717a797dbd78ceff7b26aa397f383.png?size=200[OpenDevise,100,link=https://opendevise.com,title="Let the Creators of Asciidoctor and Antora Help You to Accelerate Your Docs"]

Major funding for Asciidoctor is provided by our *Change Makers*, https://developer.okta.com/signup?utm_source=asciidoctor&utm_medium=text-link&utm_campaign=sponsor[Okta] and https://opendevise.com[OpenDevise], and our *Strategy Sponsors*, Khronos Group and Linda Roberts.
Additional funding is provided by our https://asciidoctor.org/supporters[Community Backers].

You can support this project by becoming a sponsor on https://opencollective.com/asciidoctor[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.

image::{image-uri-screenshot}[Preview of AsciiDoc source and corresponding rendered HTML]

== 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 (or 4.5) or man(ual) page output.
You have the option of using your own converter or loading {uri-tilt}[Tilt]-supported templates to customize the generated output or produce additional formats.

NOTE: Asciidoctor is a drop-in replacement for the original AsciiDoc Python processor (`asciidoc.py`).
The Asciidoctor test suite has {uri-tests}[> 2,000 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 {uri-foundation}[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 {uri-asciidoctorj}[AsciidoctorJ].
There are plugins available, based on AsciidoctorJ, that integrate the Asciidoctor processor into Apache Maven, Gradle or Javadoc builds.

Asciidoctor also runs in JavaScript.
We use https://opalrb.com[Opal] to transcompile the Ruby source to JavaScript to produce {uri-asciidoctorjs}[Asciidoctor.js], a fully-functional version of Asciidoctor that works in any JavaScript environment, such as a web browser or Node.js.
Asciidoctor.js is 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 {uri-ruby}[Ruby]:

* Ruby (MRI/CRuby 1.8.7 - 2.5)
* JRuby (1.7 in Ruby 1.8 and 1.9 modes, 9000)
* Rubinius 2.2.x
* Opal (JavaScript)

We welcome your help testing Asciidoctor on these and other platforms.
Refer to the <<Contributing>> section to learn how to get involved.

[CAUTION]
====
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) the `gem install` command, (b) Bundler, (c) package managers for popular Linux distributions, or (d) Homebrew for macOS.

TIP: The benefit of using a Linux 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.
The drawback is that the package may not be available immediately after the release of the gem.
If you need the latest version, you can always fallback to using the `gem` command.

=== (a) gem install

Open a terminal and type (excluding the leading `$`):

 $ gem install asciidoctor

If you want to install a pre-release version (e.g., a release candidate), use:

 $ gem install asciidoctor --pre

.Upgrading your installation
[TIP]
====
If you have an earlier version of Asciidoctor installed, you can update it using:

 $ gem update asciidoctor

If you install a new version of the gem using `gem install` instead of gem update, you'll have multiple versions installed.
If that's the case, use the following gem command to remove the old versions:

 $ gem cleanup asciidoctor
====

=== (b) 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,subs=attributes+]
----
source 'https://rubygems.org'
gem 'asciidoctor'
# or specify the version explicitly
# gem 'asciidoctor', '{release-version}'
----

. 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` is *not* recommended as it will also update other gems, which may not be the desired result.

=== (c) Linux package managers

==== DNF (Fedora 21 or greater)

To install the gem on Fedora 21 or greater using dnf, open a terminal and type:

 $ sudo dnf install -y asciidoctor

To upgrade the gem, use:

 $ sudo dnf update -y asciidoctor

TIP: Your system may be configured to automatically update rpm packages, in which case no action is required by you to update the gem.

==== apt-get (Debian, Ubuntu, or Mint)

To install the gem on Debian, Ubuntu or Mint, open a terminal and type:

 $ sudo apt-get install -y asciidoctor

To upgrade the gem, use:

 $ sudo apt-get upgrade -y asciidoctor

TIP: Your system may be configured to automatically update deb packages, in which case no action is required by you to update the gem.

The version of Asciidoctor installed by the package manager (apt-get) 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.

* https://packages.debian.org/search?keywords=asciidoctor&searchon=names&exact=1&suite=all&section=all[asciidoctor package by Debian release]
* https://packages.ubuntu.com/search?keywords=asciidoctor&searchon=names&exact=1&suite=all&section=all[asciidoctor package by Ubuntu release]
* https://community.linuxmint.com/software/view/asciidoctor[asciidoctor package by Mint release]

[CAUTION]
====
You're advised against using the `gem update` command to update a gem managed by the package manager.
Doing so puts the system into an inconsistent state as the package manager can no longer track the files (which get installed under /usr/local).
Simply put, system gems should only be managed by the package manager.

If you want to use a version of Asciidoctor that is newer than what is installed by the package manager, you should use https://rvm.io[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.
====

==== apk (Alpine Linux)

To install the gem on Alpine Linux, open a terminal and type:

 $ sudo apk add asciidoctor

To upgrade the gem, use:

 $ sudo apk add -u asciidoctor

TIP: Your system may be configured to automatically update apk packages, in which case no action is required by you to update the gem.

=== (d) Homebrew (macOS)

You can use Homebrew to install Asciidoctor on macOS.
If you haven't yet installed Homebrew, follow the instructions at https://brew.sh/[brew.sh].

Once Homebrew is installed, you can install the `asciidoctor` gem using the http://brewformulas.org/Asciidoctor[asciidoctor] package.
To do so, open a terminal and type:

 $ brew install asciidoctor

To upgrade the gem, use:

 $ brew update
 $ brew upgrade asciidoctor

TIP: Homebrew installs the `asciidoctor` gem into an exclusive prefix that's independent of system gems.

=== Other installation options

* {uri-install-docker}[Installing Asciidoctor using Docker]
* {uri-install-macos-doc}[Installing Asciidoctor on macOS]
// at the moment, the following entry is just a reiteration of the information in this README
//* {uri-install-doc}[Installing the Asciidoctor toolchain]

== Usage

If the Asciidoctor gem installed successfully, the `asciidoctor` command line interface (CLI) will be available on your PATH.
To verify it's available, run the following in your terminal:

 $ asciidoctor --version

You should see information about the Asciidoctor version and your Ruby environment printed in the terminal.

[.output,subs=attributes+]
....
Asciidoctor {release-version} [https://asciidoctor.org]
Runtime Environment (ruby 2.4.1p111 [x86_64-linux]) (lc:UTF-8 fs:UTF-8 in:- ex:UTF-8)
....

Asciidoctor also provides an API.
The API is intended for integration with other Ruby software, such as Rails, Sinatra and GitHub, and other languages, such as Java (via {uri-asciidoctorj}[AsciidoctorJ]) and JavaScript (via {uri-asciidoctorjs}[Asciidoctor.js]).

=== Command line interface (CLI)

The `asciidoctor` command allows you to invoke Asciidoctor from the command line (i.e., a terminal).

The following command converts the file README.adoc to HTML and saves the result to the file README.html in the same directory.
The name of the generated HTML file is derived from the source file by changing its file extension to `.html`.

 $ asciidoctor README.adoc

You can control the Asciidoctor processor by adding various flags and switches, which you can learn about using:

 $ asciidoctor --help

For instance, to write the file to a different directory, use:

 $ asciidoctor -D output README.adoc

The `asciidoctor` {uri-manpage}[man page] provides a complete reference of the command line interface.

Refer to the following resources to learn more about how to use the `asciidoctor` command.

* {uri-render-doc}[How do I convert a document?]
* {uri-themes-doc}[How do I use the Asciidoctor stylesheet factory to produce custom themes?]

=== Ruby API

To use Asciidoctor in your application, you first need to require the gem:

[source]
require 'asciidoctor'

You can then convert an AsciiDoc source file to an HTML file using:

[source]
Asciidoctor.convert_file 'README.adoc', to_file: true, safe: :safe

WARNING: When using Asciidoctor via the API, the default safe mode is `:secure`.
In secure mode, several core features are disabled, including the `include` directive.
If you want to enable these features, you'll need to explicitly set the safe mode to `:server` (recommended) or `:safe`.

You can also convert an AsciiDoc string to embeddable HTML (for inserting in an HTML page) using:

[source]
----
content = '_Zen_ in the art of writing https://asciidoctor.org[AsciiDoc].'
Asciidoctor.convert content, safe: :safe
----

If you want the full HTML document, enable the `header_footer` option as follows:

[source]
----
content = '_Zen_ in the art of writing https://asciidoctor.org[AsciiDoc].'
html = Asciidoctor.convert content, header_footer: true, safe: :safe
----

If you need access to the parsed document, you can split the conversion into discrete steps:

[source]
----
content = '_Zen_ in the art of writing https://asciidoctor.org[AsciiDoc].'
document = Asciidoctor.load content, header_footer: true, safe: :safe
puts document.doctitle
html = document.convert
----

Keep in mind that if you don't like the output Asciidoctor produces, _you can change it!_
Asciidoctor supports custom converters that can handle converting from the parsed document to the generated output.

One easy way to customize the output piecemeal is by using the template converter.
The template converter allows you to supply a {uri-tilt}[Tilt]-supported template file to handle converting any node in the document.

However you go about it, you _can_ have 100% control over the output.
For more information about how to use the API or to customize the output, refer to the {uri-user-manual}[user manual].

== Contributing

In the spirit of {uri-freesoftware}[free software], _everyone_ is encouraged to help improve this project.
If you discover errors or omissions in the source code, documentation, or website content, please don't hesitate to submit an issue or open a pull request with a fix.
New contributors are always welcome!

Here are some ways *you* can contribute:

* by using prerelease (alpha, beta or preview) versions
* by reporting bugs
* by suggesting new features
* by writing or editing documentation
* by writing specifications
* by writing code -- _No patch is too small._
** fix typos
** add comments
** clean up inconsistent whitespace
** write tests!
* by refactoring code
* by fixing {uri-issues}[issues]
* by reviewing patches

The {uri-contribute}[Contributing] guide provides information on how to create, style, and submit issues, feature requests, code, and documentation to the Asciidoctor Project.

== Getting Help

The Asciidoctor project is developed to help you easily write and publish your content.
But we can't do it without your feedback!
We encourage you to ask questions and discuss any aspects of the project on the discussion list, on Twitter or in the chat room.

Discussion list (Nabble):: {uri-discuss}
Twitter:: https://twitter.com/search?f=tweets&q=%23asciidoctor[#asciidoctor] hashtag or https://twitter.com/asciidoctor[@asciidoctor] mention
Chat (Gitter):: image:https://badges.gitter.im/Join%20In.svg[Gitter, link=https://gitter.im/asciidoctor/asciidoctor]
////
Chat (IRC):: {uri-irc}[#asciidoctor] on FreeNode IRC
////

ifdef::env-github[]
Further information and documentation about Asciidoctor can be found on the project's website.

{uri-project}[Home] | {uri-news}[News] | {uri-docs}[Docs]
endif::[]

The Asciidoctor organization on GitHub hosts the project's source code, issue tracker, and sub-projects.

Source repository (git):: {uri-repo}
Issue tracker:: {uri-issues}
Asciidoctor organization on GitHub:: {uri-org}

== Copyright and Licensing

Copyright (C) 2012-2018 Dan Allen, Ryan Waldron and the Asciidoctor Project.
Free use of this software is granted under the terms of the MIT License.

See the {uri-license}[LICENSE] file for details.

== Authors

*Asciidoctor* is led by https://github.com/mojavelinux[Dan Allen] and https://github.com/graphitefriction[Sarah White] and has received contributions from {uri-contributors}[many other individuals] in Asciidoctor's awesome community.
The project was initiated in 2012 by https://github.com/erebor[Ryan Waldron] and based on {uri-prototype}[a prototype] written by https://github.com/nickh[Nick Hengeveld].

*AsciiDoc* was started by Stuart Rackham and has received contributions from many other individuals in the AsciiDoc community.

ifndef::env-site[]
== Changelog

ifeval::[{safe-mode-level} < 20]
include::CHANGELOG.adoc[tag=compact,leveloffset=+1]
endif::[]

Refer to the {uri-changelog}[CHANGELOG] for a complete list of changes in older releases.
endif::[]
