= Asciidoctor
Dan Allen <https://github.com/mojavelinux[@mojavelinux]>; Sarah White <https://github.com/graphitefriction[@graphitefriction]>; Ryan Waldron <https://github.com/erebor[@erebor]>
// [settings]
:page-layout: base
:idprefix:
ifdef::env-github[:idprefix: user-content-]
:idseparator: -
:source-language: ruby
:language: {source-language}
// [URIs]
:org-uri: https://github.com/asciidoctor
:repo-uri: {org-uri}/asciidoctor
:asciidoctorj-uri: {org-uri}/asciidoctorj
:asciidoctorjs-uri: {org-uri}/asciidoctor.js
:project-uri: http://asciidoctor.org
:docs-uri: {project-uri}/docs
:news-uri: {project-uri}/news
:manpage-uri: {project-uri}/man/asciidoctor
:issues-uri: {repo-uri}/issues
:contributors-uri: {repo-uri}/graphs/contributors
:rel-file-base-uri: link:
:rel-tree-base-uri: link:
ifdef::awestruct-version[]
:rel-file-base-uri: {repo-uri}/blob/master/
:rel-tree-base-uri: {repo-uri}/tree/master/
endif::[]
:changelog-uri: {rel-file-base-uri}CHANGELOG.adoc
:contribute-uri: {rel-file-base-uri}CONTRIBUTING.adoc
:license-uri: {rel-file-base-uri}LICENSE.adoc
:tests-uri: {rel-tree-base-uri}test
:discuss-uri: http://discuss.asciidoctor.org
:irc-uri: irc://irc.freenode.org/#asciidoctor
:rubygem-uri: http://rubygems.org/gems/asciidoctor
:what-is-asciidoc-uri: {docs-uri}/what-is-asciidoc
:user-manual-uri: {docs-uri}/user-manual
:install-doc-uri: {docs-uri}/install-toolchain
:install-osx-doc-uri: {docs-uri}/install-asciidoctor-macosx
:render-doc-uri: {docs-uri}/render-documents
:themes-doc-uri: {docs-uri}/produce-custom-themes-using-asciidoctor-stylesheet-factory
:gitscm-repo-uri: https://github.com/git/git-scm.com
:prototype-uri: {gitscm-repo-uri}/commits/master/lib/asciidoc.rb
:freesoftware-uri: https://www.gnu.org/philosophy/free-sw.html
:foundation-uri: http://foundation.zurb.com
:tilt-uri: https://github.com/rtomayko/tilt
:ruby-uri: https://ruby-lang.org
// [Images]
:screenshot-img: screenshot.png

{project-uri}[Asciidoctor] is a _fast_ text processor and publishing toolchain for converting {what-is-asciidoc-uri}[AsciiDoc] content to HTML5, DocBook 5 (or 4.5) and other formats.
Asciidoctor is written in {ruby-uri}[Ruby], packaged as a RubyGem and published to {rubygem-uri}[RubyGems.org].
The gem is also packaged in several Linux distributions, including Fedora, Debian and Ubuntu.
Asciidoctor is open source, {repo-uri}[hosted on GitHub] and released under the MIT license.

TIP: You can run Asciidoctor on the JVM using JRuby.
You can also use {asciidoctorj-uri}[AsciidoctorJ] to invoke Asciidoctor's APIs from Java and other JVM languages.
Asciidoctor can also be used in JavaScript.
http://opalrb.org[Opal] is used to transcompile the code from Ruby to JavaScript to make {asciidoctorjs-uri}[Asciidoctor.js], which can be used whereever JavaScript runs, such as in a web browser or on Node.js.

ifdef::env-github[]
*Project health:* image:https://travis-ci.org/asciidoctor/asciidoctor.png?branch=master[Build Status, link="https://travis-ci.org/asciidoctor/asciidoctor"]
endif::env-github[]

== 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 adds a default stylesheet to the HTML5 document, as shown, to provide a pleasant out-of-the-box experience.

image::{screenshot-img}[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 into a set of built-in templates to produce HTML5, DocBook 5 (or 4.5).
You have the option of writing your own converter or providing {tilt-uri}[Tilt]-supported templates to customize the generated output or produce alternative formats.

NOTE: Asciidoctor is a drop-in replacement for the original AsciiDoc Python processor (`asciidoc.py`).
The Asciidoctor test suite has {tests-uri}[> 1,500 tests] to ensure compatibility with the AsciiDoc syntax.

In addition to the standard AsciiDoc syntax, Asciidoctor recognizes additional markup and formatting options, such as font-based icons (e.g., [x-]`icon:fire[]`) and UI elements (e.g., [x-]`button:[Save]`).
Asciidoctor also offers a modern, responsive theme based on {foundation-uri}[Foundation] to style the HTML5 output.

== Requirements

Asciidoctor works on Linux, OSX (Mac) and Windows and requires one of the following implementations of {ruby-uri}[Ruby]:

* MRI (Ruby 1.8.7, 1.9.3, 2.0.0 & 2.1.2)
* JRuby 1.7 (Ruby 1.8 and 1.9 modes)
* Rubinius 2.2.x
* Opal (JavaScript)

We welcome your help testing Asciidoctor on these and other platforms.
Refer to <<{idprefix}contributing,Contributing>> to learn how to get involved.

== Installation

Asciidoctor can be installed using (a) the `gem install` command, (b) Bundler or (c) package managers for popular Linux distributions.

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 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: (without 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 upgrade 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]
----
source 'https://rubygems.org'
gem 'asciidoctor'
# or set the version explicitly
# gem 'asciidoctor', '1.5.0'
----

. Save the Gemfile
. Open a terminal and install the gem using:

 $ bundle

To upgrade the gem, set 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

==== Yum (Fedora 18 or greater)

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

 $ sudo yum install -y rubygem-asciidoctor

To upgrade the gem, use:

 $ sudo yum update -y rubygem-asciidoctor

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

==== apt-get (Debian Sid, Ubuntu Saucy or greater)

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

 $ sudo apt-get install -y asciidoctor

To upgrade the gem, use:

 $ sudo apt-get upgrade -y asciidoctor

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

=== Other installation options

* {install-doc-uri}[Installing the Asciidoctor toolchain]
* {install-osx-doc-uri}[Installing Asciidoctor on Mac OS X]

== Usage

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

 $ asciidoctor --version

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

  Asciidoctor 1.5.0 [http://asciidoctor.org]
  Runtime Environment (ruby 2.1.2p95 (2014-05-08 revision 45877) [x86_64-linux])

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 {asciidoctorj-uri}[AsciidoctorJ]) and JavaScript (via {asciidoctorjs-uri}[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 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` {manpage-uri}[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.

* {render-doc-uri}[How do I convert a document?]
* {themes-doc-uri}[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 http://asciidoctor.org[AsciiDoc].', safe: 'safe'
Asciidoctor.convert content
----

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

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

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

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

Keep in mind, if you don't like the output you see, _you can change it!_
Asciidoctor supports custom {tilt-uri}[Tilt]-supported templates, which to allow you customize the output piecemeal, or custom converters, which give you 100% control over the output.

For more information about how to use the API or to customize the output, see the {user-manual-uri}[user manual].

== Contributing

In the spirit of {freesoftware-uri}[free software], _everyone_ is encouraged to help improve this project.
If you discover errors or ommisions 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 alpha, beta, and prerelease 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 {issues-uri}[issues]
* by reviewing patches

The {contribute-uri}[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 that without your feedback!
We encourage you to ask questions and discuss any aspects of the project on the discussion list, Twitter or IRC.

Mailing list:: {discuss-uri}
Twitter (Chat):: #asciidoctor hashtag
IRC (Chat):: {irc-uri}[#asciidoctor] on FreeNode IRC

Further information and documentation about Asciidoctor can be found on the project's website.

Home:: {project-uri}
News:: {news-uri}
Docs:: {docs-uri}

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

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

== Copyright and Licensing

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

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

== Authors

*Asciidoctor* is lead by https://github.com/mojavelinux[Dan Allen] and https://github.com/graphitefriction[Sarah White] and has received contributions from {contributors-uri}[many other individuals] in Asciidoctor's awesome community.
The project was initiated in 2012 by https://github.com/erebor[Ryan Waldron] and based on {prototype-uri}[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.

== Changelog

== 1.5.0 (pending) - @mojavelinux

Performance::

  * 10% increase in speed compared to 0.1.4
  * rewrite built-in converters in Ruby instead of ERB

Enhancements::

  * introduce new curved quote syntax (pass:["`double quotes`"], pass:['`single quotes`']) if compat-mode attribute not set (#1046)
  * add single curved quote replacement for pass:[`'] (#715)
  * use backtick (pass:[`]) for monospaced text if compat-mode attribute not set (#714, #718)
  * use single and double plus (pass:[+], pass:[++]) for inline passthrough if compat-mode attribute not set (#714, #718)
  * disable single quotes as formatting marks for emphasized text if compat-mode attribute not set (#717)
  * enable compat-mode by default if document has atx-style doctitle
  * output phrase surrounded by # as marked text (i.e., <mark>) (#225)
  * add MathJax integration and corresponding blocks and macros (#492, #760)
  * switch to Open Source fonts (OpenSans, Noto Serif and Droid Sans Mono) in default stylesheet, make refinements to theme (#879)
  * embed remote images when data-uri and allow-uri-read attributes are set (#612)
  * support leveloffset on include directive and honor relative leveloffset values (#530)
  * switch default docbook backend to docbook5 (@bk2204) (#554)
  * added hide-uri-scheme attribute to hide uri scheme in automatic links (#800)
  * allow substitutions to be incrementally added & removed (#522)
  * add compatibility with Opal, add shim compat library, use compatibility regexp, require libraries properly (@mogztter) (#679, #836, #846)
  * output XHTML when backend is xhtml or xhtml5 (#494)
  * add shorthand subs and specialchars as an alias for specialcharacters (#579)
  * deprecate toc2 attribute in favor of position and placement values on toc attribute (e.g., toc=left) (#706)
  * add source map (file and line number) information to blocks (#861)
  * write to file by default if input is file (#907)
  * add -r and -I flags from ruby command to asciidoctor command for loading additional libraries (#574)
  * support backslash (\) as line continuation character in the value of an attribute entry (#1022)
  * disable subs on pass block by default (#737)
  * add basic support for resolving xref target from reftext (#589)
  * add time range anchor to video element (#886)
  * match implicit URLs that use the file scheme (#853)
  * added sectnumlevels to control depth of section numbering (#549)
  * add hardbreaks option to block (#630)
  * sub attributes in manname (e.g., pass:[{docname}])
  * warn on reference to missing attribute if attribute-missing is "warn"
  * only enable toc macro if toc is enabled and toc-placement attribute has the value macro (#706)
  * add sectnums attribute as alternative alias to numbered attribute (#684)

Improvements::

  * don't select lines that contain a tag directive when including tagged lines, make tag regexp more strict (#1027)
  * use https scheme for assets by default
  * upgrade to Font Awesome 4.1 (@mogztter) (#752)
  * improve print styles, add print styles for book doctype (@leif81) (#997, #952)
  * add proper grid and frame styles for tables (@leif81) (#569)
  * use glyphs for checkboxes when not using font icons (#878)
  * prefer source-language attribute over language attribute for defining default source language (#888)
  * pass document as first argument to process method on Preprocessor
  * allow Treeprocessor#process method to replace tree (#1035)
  * add AbstractNode#find_by method to locate nodes in tree (#862)
  * add API for parsing title and subtitle (#1000)
  * add use_fallback option to doctitle, document method
  * constrain subscript & superscript markup (#564, #936)
  * match cell specs when cell separator is customized (#985)
  * use stylesheet to set default table width (#975)
  * display nested elements correctly in toc (@kenfinnigan) (#967)
  * add support for id attribute on links (@mogztter) (#935)
  * add support for title attribute on links (@aslakknutsen)
  * add -t flag to cli to control output of timing information (@mogztter) (#909)
  * rewrite converter API (#778)
  * rewrite extensions to support extension instances for AsciidoctorJ (#804)
  * integrate thread_safe gem (#638)
  * allow inline macro extensions that define a custom regexp to be matched (#792)
  * make Reader#push_include work with default file, path and dir (@bk2204) (#743)
  * honor custom outfilesuffix and introduce relfileprefix (#801)
  * add author and copyright to meta in HTML5 backend (#838)
  * recognize float style with shorthand syntax outside block (#818)
  * honor background color in syntax highlighting themes (#813)
  * print runtime environment in version output, support -v as version flag (#785)
  * unwrap preamble if standalone (#533)
  * drop leading & trailing blank lines in verbatim & raw content (#724)
  * remove trailing endlines from source data (#727)
  * add flag to cli to suppress warnings (#557)
  * emit warning if tag(s) not found in include file (#639)
  * use <th> element for vertical table headers instead of header class (@davidgamba) (#738)
  * share select references between AsciiDoc-style cell & main document (#729)
  * number chapters sequentially, always (#685)
  * add vbar attribute, make brvbar resolve properly (#643)
  * add implicit user-home attribute that resolves to user's home directory (#629)
  * enable sidebar toc for small screens (#628)
  * add square brackets around button in HTML output (#631)
  * add sass and go to source language hover
  * set background color on toc2 to cover scrolling content (@neher)
  * make document parsing a discrete step, make Reader accessible as property on Document
  * allow custom converter to set backend info such as outfilesuffix and htmlsyntax
  * report an informative error message when a converter cannot be resolved (@mogztter)
  * add conum class to b element when icons are disabled, make conum CSS selector more specific
  * expose Document object to extension point IncludeProcessor (@aslakknutsen)
  * style audioblock title, simplify rules for block titles
  * alias :name_attributes to :positional_attributes in extension DSL
  * upgrade to highlight.js 7.4 (and later 8.0) (@mogztter) (#756)

Compliance::

  * only include xmlns in docbook45 backend if xmlns attribute is specified (#929)
  * add xmlns attribute for xhtml output (@bk2204)
  * warn if table without a body is converted to DocBook (#961)
  * wrap <para> around admonition inside example block in DocBook 4.5 (#931)
  * use <informalfigure> if block image doesn't have a title (#927)
  * fix invalid docbook when adding role to formatted text (#956)
  * move all compliance flags to Compliance module (#624)
  * add compliance setting to control use of shorthand property syntax (#789)
  * wrap top-level content inside preamble in DocBook backend when doctype is book (#971)
  * escape special chars in image alt text (#972)
  * set starting number in ordered list for docbook (@megathaum) (#925)
  * match word characters in regular expressions as defined by Unicode (#892)
  * put source language class names on child code element of pre element (#921)
  * ignore case of attribute in conditional directives (#903)
  * allow attribute entry to reset / reseed counter (#870)
  * allow doctype to be set in AsciiDoc table cell (#863)
  * match URL macro following entity (@jmbruel) (#819)
  * handle BOM when normalizing source (#824)
  * don't output revhistory if revdate is not set (#802)
  * perform normal subs on verse content (#799)
  * automatically wrap part intro content in partintro block, emit warning if part is invalid (#768)
  * force encoding of docinfo content to UTF-8 (#773)
  * add scaling & alignment attributes to block image in DocBook backend (#763)
  * add support for pass:[anchor:<id>[<reftext>\]] macro (#531)
  * substitute anchor and xref macros in footnotes (#676)
  * remove all string mutation operations for compatibility with Opal (#735)
  * honor reftext defined in embedded section title anchor (#697)
  * allow spaces in reftext defined in block anchor (#695)
  * use reftext of section or block in text of xref link (#693)
  * number sections in appendix using appendix number (#683)
  * unescape escaped square closing bracket in footnote text (#677)
  * support quoted index terms that may contain commas (#597)
  * don't assign role attribute if quoted text has no roles (#647)
  * disallow quoted values in block and inline anchors
  * add % to scaledwidth if no units given
  * ignore block attribute with unquoted value None
  * preserve entity references with 5 digits

Bug Fixes::

  * resolve relative paths relative to base_dir in unsafe mode (#690)
  * properly handle nested passthroughs (#1034)
  * don't clobber outfilesuffix attribute if locked (#1024)
  * correctly calculate columns if colspan used in first row of table (#924)
  * pass theme to Pygments when pygments-css=style (#919)
  * fallback to text lexer when using pygments for source highlighting (#987)
  * only make special section if style is specified (#917)
  * an unresolved footnote ref should not crash processor (#876)
  * rescue failure to resolve ::Dir.home (#896)
  * recognize Windows UNC path as absolute and preserve it (#806)
  * adjust file glob to account for backslash in Windows paths (#805)
  * don't match e-mail address inside URL (#866)
  * test include directive resolves file with space in name (#798)
  * return nil from Reader#push_include and Reader#pop_include methods (#745)
  * fixed broken passthroughs caused by source highlighting (#720)
  * copy custom stylesheet if linkcss is set (#300)
  * honor list continuations for indented, nested list items (#664)
  * fix syntax errors in converters (@jljouannic)
  * fix iconfont-remote setting
  * fix syntax error (target -> node.target) in Docbook 5 converter (@jf647)
  * output and style HTML for toc macro correctly

Infrastructure::

  * add Ruby 2.1 to list of supported platforms
  * reenable rbx in Travis build
  * switch tests to minitest (@ktdreyer)
  * update RPM for Fedora Rawhide (@ktdreyer)
  * refactor unit tests so they work in RubyMine (@cmoulliard)
  * add preliminary benchmark files to repository (#1021)
  * clean out old fixtures from test suite (#960)
  * add initial Cucumber test infrastructure (#731)
  * use gem tasks from Bundler in Rakefile (#654)
  * build gemspec files using git ls-tree (#653)
  * use in-process web server for URI tests
  * update manpage to reflect updates in 1.5.0
  * rework README (@mogztter) (#651)

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