1 2 3 4 5 6 7 8 9 10 11 12 13 14 15 16 17 18 19 20 21 22 23 24 25 26 27 28 29 30 31 32 33 34 35 36 37 38 39 40 41 42 43 44 45 46 47 48 49 50 51 52 53 54 55 56 57 58 59 60 61 62 63 64 65 66 67 68 69 70 71 72 73 74 75 76 77 78 79 80 81 82 83 84 85 86 87 88 89 90 91 92 93 94 95 96 97 98 99 100 101 102 103 104 105 106 107 108 109 110 111 112 113 114 115 116 117 118 119 120 121 122 123 124 125 126 127 128 129 130 131 132 133 134 135 136 137 138 139 140 141 142 143 144 145 146 147 148 149 150 151 152 153 154 155 156 157 158 159 160 161 162 163 164 165 166 167 168 169 170 171 172 173 174 175 176 177 178 179 180 181 182 183 184 185 186 187 188 189 190 191 192 193 194 195 196 197 198 199 200 201 202 203 204 205 206 207 208 209 210 211 212 213 214 215 216 217 218 219 220 221 222 223 224 225 226 227 228 229 230 231 232 233 234 235 236 237 238 239 240 241 242 243 244 245 246 247 248 249 250 251 252 253 254 255 256 257 258 259 260 261 262 263 264 265 266 267 268 269 270 271 272 273 274 275 276 277 278 279 280 281 282 283 284 285 286 287 288 289 290 291 292 293 294 295 296 297 298 299 300 301 302 303 304 305 306 307 308 309 310 311 312 313 314 315 316 317 318 319 320 321 322 323 324 325 326 327 328 329 330 331 332 333 334 335 336 337 338 339 340 341 342 343 344 345 346 347 348 349 350 351 352 353 354 355 356 357 358 359 360 361 362 363 364 365 366 367 368 369 370 371 372 373 374 375 376 377 378 379 380 381 382 383 384 385 386 387 388 389 390 391 392 393 394 395 396 397 398 399 400 401 402 403 404 405 406 407 408 409 410 411 412 413 414 415 416 417 418 419 420 421 422 423 424 425 426 427 428 429 430 431 432 433 434 435 436 437 438 439 440 441 442 443 444 445 446 447 448 449 450 451 452 453 454 455 456 457 458 459 460 461 462 463 464 465 466 467 468 469 470 471 472 473 474 475 476
|
= Asciidoctor
Dan Allen <https://github.com/mojavelinux[@mojavelinux]>; Sarah White <https://github.com/graphitefriction[@graphitefriction]>; Ryan Waldron <https://github.com/erebor[@erebor]>
v1.5.8, 2018-10-28
// settings:
:idprefix:
:idseparator: -
:source-language: ruby
:language: {source-language}
ifndef::env-github[:icons: font]
ifdef::env-github[]
:status:
:outfilesuffix: .adoc
:caution-caption: :fire:
:important-caption: :exclamation:
:note-caption: :paperclip:
:tip-caption: :bulb:
:warning-caption: :warning:
endif::[]
// Variables:
:release-version: 1.5.8
// URIs:
:uri-org: https://github.com/asciidoctor
:uri-repo: {uri-org}/asciidoctor
:uri-asciidoctorj: {uri-org}/asciidoctorj
:uri-asciidoctorjs: {uri-org}/asciidoctor.js
:uri-gradle-plugin: {uri-org}/asciidoctor-gradle-plugin
:uri-maven-plugin: {uri-org}/asciidoctor-maven-plugin
:uri-asciidoclet: {uri-org}/asciidoclet
:uri-project: https://asciidoctor.org
ifdef::env-site[:uri-project: link:]
:uri-docs: {uri-project}/docs
:uri-news: {uri-project}/news
:uri-manpage: {uri-project}/man/asciidoctor
:uri-issues: {uri-repo}/issues
:uri-contributors: {uri-repo}/graphs/contributors
:uri-rel-file-base: link:
:uri-rel-tree-base: link:
ifdef::env-site[]
:uri-rel-file-base: {uri-repo}/blob/master/
:uri-rel-tree-base: {uri-repo}/tree/master/
endif::[]
:uri-changelog: {uri-rel-file-base}CHANGELOG.adoc
:uri-contribute: {uri-rel-file-base}CONTRIBUTING.adoc
:uri-license: {uri-rel-file-base}LICENSE
:uri-tests: {uri-rel-tree-base}test
:uri-discuss: http://discuss.asciidoctor.org
:uri-irc: irc://irc.freenode.org/#asciidoctor
:uri-rubygem: https://rubygems.org/gems/asciidoctor
:uri-what-is-asciidoc: {uri-docs}/what-is-asciidoc
:uri-user-manual: {uri-docs}/user-manual
:uri-install-docker: https://github.com/asciidoctor/docker-asciidoctor
//:uri-install-doc: {uri-docs}/install-toolchain
:uri-install-macos-doc: {uri-docs}/install-asciidoctor-macos
:uri-render-doc: {uri-docs}/render-documents
:uri-themes-doc: {uri-docs}/produce-custom-themes-using-asciidoctor-stylesheet-factory
:uri-gitscm-repo: https://github.com/git/git-scm.com
:uri-prototype: {uri-gitscm-repo}/commits/master/lib/asciidoc.rb
:uri-freesoftware: https://www.gnu.org/philosophy/free-sw.html
:uri-foundation: https://foundation.zurb.com
:uri-opal: https://opalrb.com
:uri-tilt: https://github.com/rtomayko/tilt
:uri-ruby: https://www.ruby-lang.org
// images:
:image-uri-screenshot: https://raw.githubusercontent.com/asciidoctor/asciidoctor/master/screenshot.png
{uri-project}[Asciidoctor] is a _fast_, {uri-license}[open source] text processor and publishing toolchain for converting {uri-what-is-asciidoc}[AsciiDoc] content to HTML5, DocBook, PDF, and other formats.
Asciidoctor is written in Ruby and runs on all major operation systems.
To simplify installation, Asciidoctor is packaged and distributed as a gem to {uri-rubygem}[RubyGems.org] and is packaged for popular Linux distributions and macOS.
Asciidoctor can also be run in a JVM using {uri-asciidoctorj}[AsciidoctorJ] or in any JavaScript environment using {uri-asciidoctorjs}[Asciidoctor.js].
The Asciidoctor project is {uri-repo}[hosted on GitHub].
ifndef::env-site[]
This document is also available in the following languages: +
{uri-rel-file-base}README-zh_CN.adoc[汉语]
|
{uri-rel-file-base}README-de.adoc[Deutsch]
|
{uri-rel-file-base}README-fr.adoc[Français]
|
{uri-rel-file-base}README-jp.adoc[日本語]
endif::[]
.Key documentation
[.compact]
* {uri-docs}/what-is-asciidoc[What is AsciiDoc?]
* {uri-docs}/asciidoc-writers-guide[AsciiDoc Writer's Guide]
* {uri-docs}/user-manual[Asciidoctor User Manual]
* {uri-docs}/asciidoc-syntax-quick-reference[AsciiDoc Syntax Reference]
ifdef::status[]
.*Project health*
image:https://img.shields.io/travis/asciidoctor/asciidoctor/master.svg[Build Status (Travis CI), link=https://travis-ci.org/asciidoctor/asciidoctor]
image:https://ci.appveyor.com/api/projects/status/ifplu67oxvgn6ceq/branch/master?svg=true&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::[]
== Sponsors
We want to recognize our generous sponsors, without whose support Asciidoctor would not be possible.
Thank you sponsors for your dedication to improving the state of technical documentation!
Major funding for Asciidoctor is provided by our *Change Makers*, https://developer.okta.com/signup?utm_source=asciidoctor&utm_medium=text-link&utm_campaign=sponsor[Okta] and https://opendevise.com[OpenDevise], and our *Strategy Sponsors*, https://www.khronos.org/[Khronos Group] and Linda Roberts.
Additional funding is provided by our https://asciidoctor.org/supporters[Community Backers].
You can support this project by becoming a sponsor on https://opencollective.com/asciidoctor[OpenCollective].
== The Big Picture
Asciidoctor reads content written in plain text, as shown in the panel on the left in the image below, and converts it to HTML5, as shown rendered in the right panel.
Asciidoctor applies a default stylesheet to the HTML5 document to provide a pleasant out-of-the-box experience.
image::{image-uri-screenshot}[Preview of AsciiDoc source and corresponding rendered HTML]
== AsciiDoc Processing
Asciidoctor reads and parses text written in the AsciiDoc syntax, then feeds the parse tree to a set of built-in converters to produce HTML5, DocBook 5, and 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.
Asciidoctor is a drop-in replacement for the original AsciiDoc Python processor (`asciidoc.py`).
The Asciidoctor test suite has {uri-tests}[> 2,000 tests] to ensure compatibility with the AsciiDoc syntax.
In addition to the classic AsciiDoc syntax, Asciidoctor recognizes additional markup and formatting options, such as font-based icons (e.g., `+icon:fire[]+`) and UI elements (e.g., `+button:[Save]+`).
Asciidoctor also offers a modern, responsive theme based on {uri-foundation}[Foundation] to style the HTML5 output.
== Where Ruby goes, Asciidoctor follows
You can run Asciidoctor on the JVM using JRuby.
To invoke the Asciidoctor API directly from Java and other JVM languages, use {uri-asciidoctorj}[AsciidoctorJ].
There are plugins available for {uri-maven-plugin}[Apache Maven], {uri-gradle-plugin}[Gradle], and {uri-asciidoclet}[Javadoc], which allow you to integrate AsciiDoc processing directly into your build using AsciidoctorJ.
Asciidoctor also runs in JavaScript.
{uri-opal}[Opal] is used to transcompile the Ruby source to JavaScript to produce {uri-asciidoctorjs}[Asciidoctor.js].
Asciidoctor.js is a fully-functional version of Asciidoctor that works in any JavaScript environment, such as a web browser or Node.js.
It's used to power the AsciiDoc preview extensions for Chrome, Atom, Brackets and other web-based tooling.
== Requirements
Asciidoctor works on Linux, macOS and Windows and requires one of the following implementations of {uri-ruby}[Ruby]:
* Ruby (MRI/CRuby 1.8.7 - 2.5)
* JRuby (1.7 in Ruby 1.8 and 1.9 modes, 9000)
* Rubinius 2.2.x
* Opal (JavaScript)
[CAUTION]
====
If you're using a non-English Windows environment, you may bump into an `Encoding::UndefinedConversionError` when invoking Asciidoctor.
To solve this issue, we recommend changing the active code page in your console to UTF-8:
chcp 65001
Once you make this change, all your Unicode headaches will be behind you.
If you're using an IDE like Eclipse, make sure you set the encoding to UTF-8 there as well.
Asciidoctor works best when you use UTF-8 everywhere.
====
== Installation
Asciidoctor can be installed using (a) package managers for popular Linux distributions, (b) Homebrew for macOS, (c) the `gem install` command (recommended for Windows users), (d) the Asciidoctor Docker image, or (e) Bundler.
The benefit of using your operating system's 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.
=== (a) Linux package managers
The version of Asciidoctor installed by the package manager may not match the latest release of Asciidoctor.
Consult the package repository for your distribution to find out which version is packaged per distribution release.
* https://pkgs.alpinelinux.org/packages?name=asciidoctor[Alpine Linux (asciidoctor)]
* https://www.archlinux.org/packages/?name=asciidoctor[Arch Linux (asciidoctor)]
* https://packages.debian.org/sid/asciidoctor[Debian (asciidoctor)]
* https://apps.fedoraproject.org/packages/rubygem-asciidoctor[Fedora (asciidoctor)]
* https://software.opensuse.org/package/rubygem-asciidoctor[OpenSUSE (rubygem-asciidoctor)]
* https://packages.ubuntu.com/search?keywords=asciidoctor[Ubuntu (asciidoctor)]
If you want to use a version of Asciidoctor that is newer than what is installed by the package manager, see the <<gem-install,gem installation instructions>>.
==== apk (Alpine Linux)
To install the gem on Alpine Linux, open a terminal and type:
$ sudo apk add asciidoctor
==== pacman (Arch Linux)
To install the gem on Arch-based distributions, open a terminal and type:
$ sudo pacman -S asciidoctor
==== APT
On Debian and Debian-based distributions such as Ubuntu, use APT to install Asciidoctor.
To install the package, open a terminal and type:
$ sudo apt-get install -y asciidoctor
==== DNF
On RPM-based Linux distributions, such as Fedora, CentOS, and RHEL, use the DNF package manager to install Asciidoctor.
To install the package, open a terminal and type:
$ sudo dnf install -y asciidoctor
=== (b) Homebrew (macOS)
You can use Homebrew, the macOS package manager, to install Asciidoctor.
If you don’t have Homebrew on your computer, complete the installation instructions at https://brew.sh/[brew.sh] first.
Once Homebrew is installed, you’re ready to install the `asciidoctor` gem.
Open a terminal and type:
$ brew install asciidoctor
Homebrew installs the `asciidoctor` gem into an exclusive prefix that's independent of system gems.
=== (c) Windows
To use Asciidoctor with Windows, you have two easy options.
==== Chocolatey
When you already use https://chocolatey.org[chocolatey] on your machine, you can use:
[source]
----
choco install ruby
----
Then follow <<gem-install,gem installation instructions>>.
==== Rubyinstaller
Or you use the https://rubyinstaller.org/downloads/[Rubyinstaller], download the package for your Windows Version and after the installation go ahead with <<gem-install,gem installation instructions>>.
[#gem-install]
=== (d) gem install
Before installing Asciidoctor using `gem install`, you should use https://rvm.io[RVM] to install Ruby in your home directory (i.e., user space).
Then, you can safely use the `gem` command to install or update the Asciidoctor gem.
When using RVM, gems are installed in a location isolated from the system.
Open a terminal and type:
$ gem install asciidoctor
If you want to install a pre-release version (e.g., a release candidate), use:
$ gem install asciidoctor --pre
=== (e) Docker
See {uri-install-docker}[Installing Asciidoctor using Docker].
=== (f) Bundler
. Create a Gemfile in the root folder of your project (or the current directory)
. Add the `asciidoctor` gem to your Gemfile as follows:
+
[source,subs=attributes+]
----
source 'https://rubygems.org'
gem 'asciidoctor'
# or specify the version explicitly
# gem 'asciidoctor', '{release-version}'
----
. Save the Gemfile
. Open a terminal and install the gem using:
$ bundle
To upgrade the gem, specify the new version in the Gemfile and run `bundle` again.
Using `bundle update` (without specifying a gem) is *not* recommended as it will also update other gems, which may not be the desired result.
== Upgrade
If you installed Asciidoctor using a package manager, your operating system is probably configured to automatically update packages, in which case you don't need to update the gem manually.
=== apk (Alpine Linux)
To upgrade the gem, use:
$ sudo apk add -u asciidoctor
=== APT
To upgrade the gem, use:
$ sudo apt-get upgrade -y asciidoctor
=== DNF
To upgrade the gem, use:
$ sudo dnf update -y asciidoctor
=== Homebrew (macOS)
To upgrade the gem, use:
$ brew update
$ brew upgrade asciidoctor
=== gem install
If you previously installed Asciidoctor using the `gem` command, you'll need to manually upgrade Asciidoctor when a new version is released.
You can upgrade the gem by typing:
$ gem install asciidoctor
When you install a new version of the gem using `gem install`, you end up with multiple versions installed.
Use the following command to remove the old versions:
$ gem cleanup asciidoctor
== Usage
If the Asciidoctor gem installed successfully, the `asciidoctor` command line interface (CLI) will be available on your PATH.
To verify it's available, run the following in your terminal:
$ asciidoctor --version
You should see information about the Asciidoctor version and your Ruby environment printed in the terminal.
[.output,subs=attributes+]
....
Asciidoctor {release-version} [https://asciidoctor.org]
Runtime Environment (ruby 2.5.1p57 [x86_64-linux]) (lc:UTF-8 fs:UTF-8 in:- ex:UTF-8)
....
Asciidoctor also provides an API.
The API is intended for integration with other Ruby software, such as Rails, Sinatra and GitHub, and other languages, such as Java (via {uri-asciidoctorj}[AsciidoctorJ]) and JavaScript (via {uri-asciidoctorjs}[Asciidoctor.js]).
=== Command line interface (CLI)
The `asciidoctor` command allows you to invoke Asciidoctor from the command line (i.e., a terminal).
The following command converts the file README.adoc to HTML and saves the result to the file README.html in the same directory.
The name of the generated HTML file is derived from the source file by changing its file extension to `.html`.
$ asciidoctor README.adoc
You can control the Asciidoctor processor by adding various flags and switches, which you can learn about using:
$ asciidoctor --help
For instance, to write the file to a different directory, use:
$ asciidoctor -D output README.adoc
The `asciidoctor` {uri-manpage}[man page] provides a complete reference of the command line interface.
Refer to the following resources to learn more about how to use the `asciidoctor` command.
* {uri-render-doc}[How do I convert a document?]
* {uri-themes-doc}[How do I use the Asciidoctor stylesheet factory to produce custom themes?]
=== Ruby API
To use Asciidoctor in your application, you first need to require the gem:
[source]
require 'asciidoctor'
You can then convert an AsciiDoc source file to an HTML file using:
[source]
Asciidoctor.convert_file 'README.adoc', to_file: true, safe: :safe
WARNING: When using Asciidoctor via the API, the default safe mode is `:secure`.
In secure mode, several core features are disabled, including the `include` directive.
If you want to enable these features, you'll need to explicitly set the safe mode to `:server` (recommended) or `:safe`.
You can also convert an AsciiDoc string to embeddable HTML (for inserting in an HTML page) using:
[source]
----
content = '_Zen_ in the art of writing https://asciidoctor.org[AsciiDoc].'
Asciidoctor.convert content, safe: :safe
----
If you want the full HTML document, enable the `header_footer` option as follows:
[source]
----
content = '_Zen_ in the art of writing https://asciidoctor.org[AsciiDoc].'
html = Asciidoctor.convert content, header_footer: true, safe: :safe
----
If you need access to the parsed document, you can split the conversion into discrete steps:
[source]
----
content = '_Zen_ in the art of writing https://asciidoctor.org[AsciiDoc].'
document = Asciidoctor.load content, header_footer: true, safe: :safe
puts document.doctitle
html = document.convert
----
Keep in mind that if you don't like the output Asciidoctor produces, _you can change it!_
Asciidoctor supports custom converters that can handle converting from the parsed document to the generated output.
One easy way to customize the output piecemeal is by using the template converter.
The template converter allows you to supply a {uri-tilt}[Tilt]-supported template file to handle converting any node in the document.
However you go about it, you _can_ have 100% control over the output.
For more information about how to use the API or to customize the output, refer to the {uri-user-manual}[user manual].
== Contributing
New contributors are always welcome!
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.
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 code with tests -- _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
Asciidoctor is developed to help you easily write and publish your content.
But we can't do it without your feedback!
We encourage you to ask questions and discuss any aspects of the project on the discussion list, on Twitter or in the chat room.
Discussion list (Nabble):: {uri-discuss}
Twitter:: https://twitter.com/search?f=tweets&q=%23asciidoctor[#asciidoctor] hashtag or https://twitter.com/asciidoctor[@asciidoctor] mention
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}
== License
Copyright (C) 2012-2018 Dan Allen, Sarah White and the individual contributors to Asciidoctor.
Use of this software is granted under the terms of the MIT License.
See the {uri-license}[LICENSE] for the full license text.
== 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 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 individuals in the AsciiDoc community.
ifndef::env-site[]
== Changelog
ifeval::[{safe-mode-level} < 20]
include::CHANGELOG.adoc[tag=compact,leveloffset=+1]
endif::[]
Refer to the {uri-changelog}[CHANGELOG] for a complete list of changes in older releases.
endif::[]
|