path: root/README.adoc

= 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

=== v0.1.4 (2013-09-05) - @mojavelinux

Performance::

  * 15% increase in speed compared to 0.1.3

Enhancements::

  * updated xref inline macro to support inter-document references (#417)
  * added extension API for document processing (#79)
  * added include directive processor extension (#100)
  * added id and role shorthand for formatted (quoted) text (#517)
  * added shorthand syntax for specifying block options (#481)
  * added support for checklists in unordered list (#200)
  * added support for inline style for unordered lists (#620)
  * added DocBook 5 backend (#411)
  * added docinfo option for footer (#486)
  * added Pygments as source highlighter option (pygments) (#538)
  * added icon inline macro (#529)
  * recognize implicit table header row (#387)
  * uri can be used in inline image (#470)
  * add float attribute to inline image (#616)
  * allow role to be specified on text enclosed in backticks (#419)
  * added XML comment-style callouts for use in XML listings (#582)
  * made callout bullets non-selectable in HTML output (#478)
  * pre-wrap literal blocks, added nowrap option to listing blocks (#303)
  * skip (retain) missing attribute references by default (#523)
  * added attribute-missing attribute to control how a missing attribute is handled (#495)
  * added attribute-undefined attribute to control how an undefined attribute is handled (#495)
  * permit !name syntax for undefining attribute (#498)
  * ignore front matter used by static site generators if skip-front-matter attribute is set (#502)
  * sanitize contents of HTML title element in html5 backend (#504)
  * support toc position for toc2 (#467)
  * cli accepts multiple files as input (@lordofthejars) (#227)
  * added Markdown-style horizontal rules and pass Markdown tests (#455)
  * added float clearing classes (.clearfix, .float-group) (#602)
  * don't disable syntax highlighting when explicit subs is used on listing block
  * asciidoctor package now available in Debian Sid and Ubuntu Saucy (@avtobiff) (#216)

Compliance::

  * embed CSS by default, copy stylesheet when linkcss is set unless copycss! is set (#428)
  * refactor reader to track include stack (#572)
  * made include directive resolve relative to current file (#572)
  * track include stack to enforce maximum depth (#581)
  * fixed greedy comment blocks and paragraphs (#546)
  * enable toc and numbered by default in DocBook backend (#540)
  * ignore comment lines when matching labeled list item (#524)
  * correctly parse footnotes that contain a URL (#506)
  * parse manpage metadata, output manpage-specific HTML, set docname and outfilesuffix (#488, #489)
  * recognize preprocessor directives on first line of AsciiDoc table cell (#453)
  * include directive can retrieve data from uri if allow-uri-read attribute is set (#445)
  * support escaping attribute list that precedes formatted (quoted) text (#421)
  * made improvements to list processing (#472, #469, #364)
  * support percentage for column widths (#465)
  * substitute attributes in docinfo files (#403)
  * numbering no longer increments on unnumbered sections (#393)
  * fixed false detection of list item with hyphen marker
  * skip include directives when processing comment blocks
  * added xmlns to root element in docbook45 backend, set noxmlns attribute to disable
  * added a Compliance module to control compliance-related behavior
  * added linkattrs feature to AsciiDoc compatibility file (#441)
  * added level-5 heading to AsciiDoc compatibility file (#388)
  * added new XML-based callouts to AsciiDoc compatibility file
  * added absolute and uri image target matching to AsciiDoc compatibility file
  * added float attribute on inline image macro to AsciiDoc compatibility file
  * removed linkcss in AsciiDoc compatibility file
  * fixed fenced code entry in compatibility file

Bug Fixes::

  * lowercase attribute names passed to API (#508)
  * numbered can still be toggled even when enabled in API (#393)
  * allow JRuby Map as attributes (#396)
  * don't attempt to highlight callouts when using CodeRay and Pygments (#534)
  * correctly calculate line length in Ruby 1.8 (#167)
  * write to specified outfile even when input is stdin (#500)
  * only split quote attribution on first comma in Markdown blockquotes (#389)
  * don't attempt to print render times when doc is not rendered
  * don't recognize line with four backticks as a fenced code block (#611)

Improvements::

  * upgraded Font Awesome to 3.2.1 (#451)
  * improved the built-in CodeRay theme to match Asciidoctor styles
  * link to CodeRay stylesheet if linkcss is set (#381)
  * style the video block (title & margin) (#590)
  * added Groovy, Clojure, Python and YAML to floating language hint
  * only process callouts for blocks in which callouts are found
  * added content_model to AbstractBlock, rename buffer to lines
  * use Untitled as document title in rendered output if document has no title
  * rename include-depth attribute to max-include-depth, set 64 as default value (#591)
  * the tag attribute can be used on the include directive to identify a single tagged region
  * output multiple authors in HTML backend (#399)
  * allow multiple template directories to be specified, document in usage and manpage (#437)
  * added option to cli to specify template engine (#406)
  * added support for external video hosting services in video block macro (@xcoulon) (#587)
  * strip leading separator(s) on section id if idprefix is blank (#551)
  * customized styling of toc placed inside body content (#507)
  * consolidate toc attribute so toc with or without toc-position can make sidebar toc (#618)
  * properly style floating images (inline & block) (#460)
  * add float attribute to inline images (#616)
  * use ul list for TOC in HTML5 backend (#431)
  * support multiple terms per labeled list item in model (#532)
  * added role?, has_role?, option? and roles methods to AbstractNode (#423, 474)
  * added captioned_title method to AbstractBlock
  * honor showtitle attribute as alternate to notitle! (#457)
  * strip leading indent from literal paragraph blocks assigned the style normal
  * only process lines in AsciiDoc files
  * emit message that tilt gem is required to use custom backends if missing (#433)
  * use attributes for version and last updated messages in footer (#596)
  * added a basic template cache (#438)
  * include line info in several of the warnings (for lists and tables)
  * print warning/error messages using warn (#556)
  * lines are not preprocessed when peeking ahead for section underline
  * introduced Cursor object to track line info
  * fixed table valign classes, no underline on image link
  * removed dependency on pending library, lock Nokogiri version to 1.5.10
  * removed require rubygems line in asciidoctor.rb, add to cli if RUBY_VERSION < 1.9
  * added tests for custom backends
  * added test that shorthand doesn't clobber explicit options (#481)
  * removed unnecessary monospace class from literal and listing blocks

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