= Asciidoctor Dan Allen ; Sarah White ; Ryan Waldron v1.5.4, 2016-01-05 // settings: :page-layout: base :idprefix: :idseparator: - :source-language: ruby :language: {source-language} ifdef::env-github[:badges:] // 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: http://asciidoctor.org ifdef::awestruct-version[: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::awestruct-version[] :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.adoc :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-osx-doc: {uri-docs}/install-asciidoctor-macosx :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: http://foundation.zurb.com :uri-tilt: https://github.com/rtomayko/tilt :uri-ruby: https://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 5 (or 4.5) and other formats. Asciidoctor is written in Ruby, packaged as a RubyGem and published to {uri-rubygem}[RubyGems.org]. The gem is also included in several Linux distributions, including Fedora, Debian and Ubuntu. Asciidoctor is open source, {uri-repo}[hosted on GitHub] and released under {uri-license}[the MIT license]. .Key documentation [.compact] * {uri-docs}/what-is-asciidoc[What is Asciidoc?] * {uri-docs}/asciidoc-writers-guide[AsciiDoc Writer's Guide] * {uri-docs}/asciidoc-syntax-quick-reference[AsciiDoc Syntax Reference] * {uri-docs}/user-manual[Asciidoctor User Manual] .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 http://opalrb.org[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. **** ifdef::badges[] .*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&passingText=green%20bar&failingText=%23fail&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::[] == 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}[> 1,600 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. == Requirements Asciidoctor works on Linux, OSX (Mac) and Windows and requires one of the following implementations of {uri-ruby}[Ruby]: * MRI (Ruby 1.8.7, 1.9.3, 2.0, 2.1 & 2.2) * JRuby 1.7 (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 <<{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 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] ---- source 'https://rubygems.org' gem 'asciidoctor' # or specify the version explicitly # gem 'asciidoctor', '1.5.3' ---- . 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 ==== Yum (Fedora 21 or greater) To install the gem on Fedora 21 or greater using yum, open a terminal and type: $ sudo yum install -y asciidoctor To upgrade the gem, use: $ sudo yum update -y 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 * {uri-install-docker}[Installing Asciidoctor using Docker] * {uri-install-osx-doc}[Installing Asciidoctor on Mac OS X] // 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] .... Asciidoctor 1.5.3 [http://asciidoctor.org] Runtime Environment (ruby 2.2.2p95 [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 http://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 http://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 http://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 uses 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 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:: {uri-discuss} Twitter (Chat):: #asciidoctor hashtag Gitter (Chat):: image:https://badges.gitter.im/Join%20In.svg[Gitter, link=https://gitter.im/asciidoctor/asciidoctor] IRC (Chat):: {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-2016 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. == Changelog == 1.5.4 (2016-01-03) - @mojavelinux Enhancements:: * translate README into French (@anthonny, @mogztter, @gscheibel, @mgreau) (#1630) * allow linkstyle in manpage output to be configured (#1610) Improvements:: * upgrade to MathJax 2.6.0 and disable loading messages * upgrade to Font Awesome 4.5.0 * disable toc if document has no sections (#1633) * convert inline asciimath to MathML (using asciimath gem) in DocBook converter (#1622) * add attribute to control build reproducibility (@bk2204) (#1453) * recognize \file:/// as a file root in Opal browser env (#1561) * honor icon attribute on admonition block when font-based icons are enabled (@robertpanzer) (#1593) * resolve custom icon relative to iconsdir; add file extension if absent (#1634) * allow asciidoctor cli to resolve library path when invoked without leading ./ Compliance:: * allow special section to be nested at any depth (#1591) * ensure colpcwidth values add up to 100%; increase precision of values to 4 decimal places (#1647) * ignore blank cols attribute on table (#1647) * support shorthand syntax for block attributes on document title (#1650) Bug fixes:: * don't include default toc in AsciiDoc table cell; don't pass toc location attributes to nested document (#1582) * guard against nil dlist list item in find_by (#1618) * don't swallow trailing line when include file is not readable (#1602) * change xlink namespace to xl in DocBook 5 output to prevent parse error (#1597) * make callouts globally unique within document, including AsciiDoc table cells (#1626) * initialize Slim-related attributes regardless of when Slim was loaded (@terceiro) (#1576) * differentiate literal backslash from escape sequence in manpage output (@ds26gte) (#1604) * don't mistake line beginning with \. for troff macro in manpage output (@ds26gte) (#1589) * escape leading dots so user content doesn't trigger troff macros in manpage output (@ds26gte) (#1631) * use \c after .URL macro to remove extraneous space in manpage output (@ds26gte) (#1590) * fix missing endline after .URL macro in manpage output (#1613) * properly handle spacing around .URL/.MTO macro in manpage output (@ds26gte) (#1641) * don't swallow doctitle attribute followed by block title (#1587) * change strategy for splitting names of author; fixes bug in Opal/Asciidoctor.js * don't fail if library is loaded more than once Infrastructure:: * remove trailing endlines in project source code * update contributing guidelines * explicitly test ifeval scenario raised in issue #1585 * remove backreference substitution hack for Opal/Asciidoctor.js * fix assignment of default Hash value for Opal/Asciidoctor.js * add JRuby 9.0.4.0 and Ruby 2.3.0 to the Travis CI build matrix == 1.5.3 (2015-10-31) - @mojavelinux Enhancements:: * add support for interactive & inline SVGs (#1301, #1224) * add built-in manpage backend (@davidgamba) (#651) * create Mallard backend; asciidoctor/asciidoctor-mallard (@bk2204) (#425) * add AsciiMath to MathML converter to support AsciiMath in DocBook converter (@pepijnve) (#954) * allow text of selected lines to be highlighted in source block by Pygments or CodeRay (#1429) * use value of `docinfo` attribute to control docinfo behavior (#1510) * add `docinfosubs` attribute to control which substitutions are performed on docinfo files (@mogztter) (#405) * drop ability to specify multiple attributes with a single `-a` flag when using the CLI (@mogztter) (#405) * make subtitle separator chars for document title configurable (@rmannibucau) (#1350) * make XrefInlineRx regexp more permissive (Mathieu Boespflug) (#844) Improvements:: * load JavaScript and CSS at bottom of HTML document (@mogztter) (#1238) * list available backends in help text (@plaindocs) (#1271) * properly expand tabs in literal text (#1170, #841) * add `source-indent` as document attribute (@mogztter) (#1169) * upgrade MathJax to 2.5.3 (#1329) * upgrade Font Awesome to 4.4.0 (@mogztter) (#1465) * upgrade highlight.js to 8.6 (now 8.9.1) (#1390) * don't abort if syntax highlighter isn't available (#1253) * insert docinfo footer below footer div (#1503) * insert toc at default location in embeddable HTML (#1443) * replace _ and - in generated alt text for inline images * restore attributes to header attributes after parse (#1255) * allow docdate and doctime to be overridden (#1495) * add CSS class `.center` for center block alignment (#1456) * recognize U+2022 as alternative marker for unordered lists (@mogztter) (#1177) * allow videos to work for local files by prepending asset-uri-scheme (Chris) (#1320) * always assign playlist param when loop option is enabled for YouTube video * parse isolated version in revision line (@bk2204) (#790) * autoload Tilt when template converter is instantiated (#1313) * don't overwrite existing id entry in references table (#1256) * use outfilesuffix attribute defined in header when resolving outfile (#1412) * make AsciiDoc safe mode option on Slim engine match document (#1347) * honor htmlsyntax attribute when backend is html/html5 (#1530) * tighten spacing of wrapped lines in TOC (#1542) * tune padding around table cells in horizontal dlist (#1418) * load Droid Sans Mono 700 in default stylesheet * set line height of table cells used for syntax highlighting * set font-family of kbd; refine styling (#1423) * extract condition into `quote_lines?` method (@mogztter) * extract inline code into `read_paragraph` method (@mogztter) * parent of block in ListItem should be ListItem (#1359) * add helper methods to List and ListItem (#1551) * add method `AbstractNode#add_role` and `AbstractNode#remove_role` (@robertpanzer) (#1366) * introduce helper methods for sniffing URIs (#1422) * add helper to calculate basename without file extension * document `-I` and `-r` options in the manual page (@bk2204) * fix `+--help+` output text for `-I` (@bk2204) * don't require open-uri-cached if already loaded * do not attempt to scan pattern of non-existent directory in template converter Compliance:: * use `` for footnote reference in text instead of `` (#1523) * fix alignment of wrapped text in footnote (#1524) * include full stop after footnote number in embeddable HTML * show manpage title & name section in embeddable HTML (#1179) * resolve missing attribute in ifeval to empty string (#1387) * support unbreakable & breakable options on table (rockyallen) (#1140) Bug fixes:: * don't truncate exception stack in `Asciidoctor.load` (#1248) * don't fail to save cause of Java exception (@robertpanzer) (#1458) * fix precision error in timings report (#1342) * resolve regexp for inline macro lazily (#1336) * block argument to `find_by` should filter results (#1393) * strip comment lines in indented text of dlist item (#1537) * preserve escaped delimiter at end of line in a table (#1306) * correctly calculate colnames for implicit columns (#1556) * don't crash if colspan exceeds colspec (#1460) * account for empty records in colspec (#1375) * ignore empty cols attribute on table * use `.inspect` to print MathJax delimiters (again) (#1198) * use while loop instead of begin/while loop to address bug in Asciidoctor.js (#1408) * force encoding of attribute values passed from cli (#1191) * don't copy css if stylesheet or stylesdir is a URI (#1400) * fix invalid color value in default CodeRay theme * built-in writer no longer fails if output is nil (#1544) * custom template engine options should take precedence * fallback to require with a non-relative path to support Debian package (@mogztter) * pass opts to recursive invocations of `PathResolver#system_path` * fix and test external links in docbook backend * use format symbol `:html` instead of `:html5` for Slim to fix warnings * fix documentation for inline_macro and block_macro (Andrea Bedini) * fix grammar in warning messages regarding thread_safe gem Infrastructure:: * migrate opal_ext from core to Asciidoctor.js (#1517) * add Ruby 2.2 to CI build; only specify minor Ruby versions * enable containerized builds on Travis CI * add config to run CI build on AppVeyor * exclude benchmark folder from gem (#1522) == 1.5.2 (2014-11-27) - @mojavelinux Enhancements:: * add docinfo extension (@mogztter) (#1162) * allow docinfo to be in separate directory from content, specified by `docinfodir` attribute (@mogztter) (#511) * enable TeX equation auto-numbering if `eqnums` attribute is set (@jxxcarlson) (#1110) Improvements:: * recognize `+--+` as valid line comment for callout numbers; make line comment configurable (#1068) * upgrade highlight.js to version 8.4 (#1216) * upgrade Font Awesome to version 4.2.0 (@clojens) (#1201) * define JAVASCRIPT_PLATFORM constant to simplify conditional logic in the JavaScript environment (#897) * provide access to destination directory, outfile and outdir via Document object (#1203) * print encoding information in version report produced by `asciidoctor -v` (#1210) * add intrinsic attribute named `cpp` with value `pass:[C++]` (#1208) * preserve URI targets passed to `stylesheet` and related attributes (#1192) * allow numeric characters in block attribute name (#1103) * support custom YouTube playlists (#1105) * make start number for unique id generation configurable (#1148) * normalize and force UTF-8 encoding of docinfo content (#831) * allow subs and default_subs to be specified in Block constructor (#749) * enhance error message when reading binary input files (@mogztter) (#1158) * add `append` method as alias to `<<` method on AbstractBlock (#1085) * assign value of `preface-title` as title of preface node (#1090) * fix spacing around checkbox in checklist (#1138) * automatically load Slim's include plugin when using slim templates (@jirutka) (#1151) * mixin Slim helpers into execution scope of slim templates (@jirutka) (#1143) * improve DocBook output for manpage doctype (@bk2204) (#1134, #1142) Compliance:: * substitute attribute entry value in attributes defined outside of header (#1130) * allow empty cell to appear at end of table row (#1106) * only produce one row for table in CSV or DSV format with a single cell (#1180) Bug fixes:: * add explicit to_s call to generate delimiter settings for MathJax config (#1198) * fix includes that reference absolute Windows paths (#1144) * apply DSL to extension block in a way compatible with Opal Refer to the {uri-changelog}[CHANGELOG] for a complete list of changes in older releases.