Skip to content

Latest commit

 

History

History
588 lines (462 loc) · 28.2 KB

README.adoc

File metadata and controls

588 lines (462 loc) · 28.2 KB
Raw

Asciidoctor

Asciidoctor is a fast text processor and publishing toolchain for converting AsciiDoc content to HTML5, DocBook 5 (or 4.5) and other formats. Asciidoctor is written in Ruby, packaged as a RubyGem and published to RubyGems.org. The gem is also included in several Linux distributions, including Fedora, Debian and Ubuntu. Asciidoctor is open source, hosted on GitHub and released under the MIT license.

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, based on AsciidoctorJ, that integrate the Asciidoctor processor into Apache Maven, Gradle or Javadoc builds.

Asciidoctor also runs in JavaScript. We use Opal to transcompile the Ruby source to JavaScript to produce 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.

Project health

Build Status (Travis CI) Build Status (AppVeyor) Code Climate Inline docs

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.

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-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 > 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., icon:fire[]) and UI elements (e.g., button:[Save]). Asciidoctor also offers a modern, responsive theme based on Foundation to style the HTML5 output.

Requirements

Asciidoctor works on Linux, OSX (Mac) and Windows and requires one of the following implementations of 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 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: (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
Tip
Upgrading your installation

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

  1. Create a Gemfile in the root folder of your project (or the current directory)

  2. Add the asciidoctor gem to your Gemfile as follows:

    source 'https://rubygems.org'
gem 'asciidoctor'
# or specify the version explicitly
# gem 'asciidoctor', '1.5.2'

  3. Save the Gemfile

  4. 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 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.

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.

Asciidoctor 1.5.2 [http://asciidoctor.org]
Runtime Environment (ruby 2.2.0p0 (2014-12-25 revision 49005) [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 AsciidoctorJ) and JavaScript (via 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 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.

Ruby API

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

require 'asciidoctor'

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

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:

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:

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:

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 Asciidoctor produces, you can change it! Asciidoctor supports custom 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.

Contributing

In the spirit of 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 issues

  • by reviewing patches

The 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

http://discuss.asciidoctor.org

Twitter (Chat)

#asciidoctor hashtag

IRC (Chat)

#asciidoctor on FreeNode IRC

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

Home | News | Docs

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

Copyright and Licensing

Copyright © 2012-2015 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 file for details.

Authors

Asciidoctor is lead by Dan Allen and Sarah White and has received contributions from many other individuals in Asciidoctor’s awesome community. The project was initiated in 2012 by Ryan Waldron and based on a prototype written by Nick Hengeveld.

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

Changelog

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 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

1.5.1 (2014-09-29) - @mojavelinux

Bug fixes

  • recognize tag directives inside comments within XML files for including tagged regions

  • restore passthroughs inside footnotes when more than one footnote appears on the same line

  • -S flag in cli recognizes safe mode name as lowercase string

  • do not match # in character reference when looking for marked text

  • add namespace to lang attribute in DocBook 5 backend

  • restore missing space before conum on last line of listing when highlighting with Pygments

  • place conums on correct lines when line numbers are enabled when highlighting with Pygments

  • don’t expand mailto links in print styles

Improvements

  • implement File.read in Node (JavaScript) environment

  • assign sectnumlevels and toclevels values to maxdepth attribute on AsciiDoc processing instructions in DocBook output

  • add test for usage of image block macro with data URI

  • use badges from shields.io in README

1.5.0 (2014-08-12) - @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 ("`double quotes`", '`single quotes`') if compat-mode attribute not set (#1046)

  • add single curved quote replacement for `' (#715)

  • use backtick (`) for monospaced text if compat-mode attribute not set (#714, #718)

  • use single and double plus (+, ++) 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 (Open Sans, Noto Serif and Droid Sans Mono) in default stylesheet, major 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., {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

  • don’t parse link attributes when linkattrs is set unless text contains equal sign

  • detect bare links, mark with bare class; don’t repeat URL of bare link in print styles

  • 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)

  • output attribution in front of citetitle for quote and verse blocks

  • 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)

  • make language hover text work for all languages in listing block

  • 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 anchor:[] 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 for a complete list of changes in older releases.