Asciidoctor
Afast text processor & publishing toolchain for converting AsciiDoc to HTML5, DocBook & more.
= Hello, AsciiDoc!Doc Writer <doc@example.com>An introduction to http://asciidoc.org[AsciiDoc].== First Section* item 1* item 2[source,ruby]puts "Hello, World!"Asciidoctor is a fast, open source, Ruby-based text processor for parsing AsciiDoc® into a document model and converting it to output formats such as HTML 5, DocBook 5, manual pages, PDF, EPUB 3, and other formats.
Asciidoctor also has an ecosystem of extensions, converters, build plugins, and tools to help you author and publish content written inAsciiDoc.You can find the documentation for these projects athttps://docs.asciidoctor.org.
In addition to running on Ruby, Asciidoctor can be executed on a JVM usingAsciidoctorJ or in any JavaScript environment usingAsciidoctor.js.
Sponsors
We want to recognize oursponsors for their commitment to improving the state of technical documentation by supporting this project.Thank you sponsors!Without your generous support, Asciidoctor would not be possible.
You can support this project by becoming a sponsor throughOpenCollective.
AsciiDoc Processing and Built-in Converters
AsciiDoc is the language.
Asciidoctor is the processor.
Asciidoctor reads the AsciiDoc source, as shown in the panel on the left in the image below, and converts it to publishable formats, such as HTML 5, as shown rendered in the panel on the right.
Asciidoctor provides built-inconverters for three output formats by default:HTML 5,DocBook 5, andman page (short for manual page).Additional converters, such as PDF and EPUB 3, are provided by separate gems.Asciidoctor also provides an out-of-the-box HTML experience complete with adefault stylesheet and built-in integrations like Font Awesome (for icons), highlight.js, Rouge, and Pygments (for source highlighting), and MathJax (for STEM processing).
Asciidoctor Ecosystem
Although Asciidoctor is written in Ruby, it does not mean you need Ruby to use it.Asciidoctor can be executed on a JVM usingAsciidoctorJ or in any JavaScript environment (including the browser) usingAsciidoctor.js.
Installing an Asciidoctor processor is just the beginning of your publishing experience.Asciidoctor gives you access to a ecosystem of extensions and tools, ranging from add-on converters, to extended syntax, to build plugins, to integrated writing and preview environments:
Asciidoctor is the successor to AsciiDoc.py.If you’re using AsciiDoc.py, seeMigrate from AsciiDoc.py to learn how to upgrade to Asciidoctor.
Requirements
Asciidoctor works on Linux, macOS and Windows and requires one of the following implementations ofRuby:
CRuby (aka MRI) 2.3 - 3.3
JRuby 9.1 - 9.4
TruffleRuby (GraalVM)
If you’re using a non-English Windows environment, you may bump into an RUBYOPT="-E utf-8:utf-8" Once you make this change, all your Unicode headaches should be behind you. If you’re using an IDE like Eclipse, make sure you set the encoding to UTF-8 there as well.Asciidoctor is optimized to work with UTF-8 as the default encoding. |
Installation
Asciidoctor is packaged and distributed to RubyGems.org as a RubyGem (aka gem) namedasciidoctor.The asciidoctor gem can be installed on all major operating systems using Ruby packaging tools (gem or bundle).Asciidoctor is also distributed as a Docker image, as a package for numerous Linux distributions, and as a package for macOS (via Homebrew and MacPorts).
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.
If you want to use a version of Asciidoctor that’s newer than what is installed by the package manager, see thegem 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
macOS
Homebrew
You can useHomebrew, the macOS package manager, to install Asciidoctor.If you don’t have Homebrew on your computer, complete theinstallation instructions first.
Once Homebrew is installed, you’re ready to install theasciidoctor gem.Open a terminal and type:
$ brew install asciidoctor
Homebrew installs theasciidoctor gem into an exclusive prefix that’s independent of system gems.
MacPorts
You can also useMacPorts, another package manager for macOS, to install Asciidoctor.If you don’t have MacPorts on your computer, complete theinstallation instructions first.
Once MacPorts is installed, you’re ready to install theasciidoctor gem via theAsciidoctor port.Open a terminal and type:
$ sudo port install asciidoctor
Windows
To use Asciidoctor with Windows, you have two options.
Chocolatey
When you already usechocolatey on your machine, you can use:
choco install rubyThen followgem installation instructions.
Rubyinstaller
Or you use theRubyinstaller, download the package for your Windows Version and after the installation go ahead withgem installation instructions.
gem install
Before installing Asciidoctor usinggem install, you should set upRVM (or similar) to install Ruby in your home directory (i.e., user space).Then, you can safely use thegem command to install or update the Asciidoctor gem, or any other gem for that matter.When using RVM, gems are installed in a location isolated from the system.(You should never use the gem command to install system-wide gems).
Once you’ve installed Ruby using RVM, and you have activated it usingrvm use 3.0, 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
Bundler
Create a Gemfile in the root folder of your project (or the current directory)
Add the
asciidoctorgem to your Gemfile as follows:source'https://rubygems.org'gem'asciidoctor'# or specify the version explicitly# gem 'asciidoctor', '2.0.23'Save the Gemfile
Open a terminal and install the gem using:
$ bundle
To upgrade the gem, specify the new version in the Gemfile and runbundle again.Usingbundle update (without specifying a gem) isnot 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.
gem install
If you previously installed Asciidoctor using thegem 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 usinggem 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, theasciidoctor 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 2.0.23 [https://asciidoctor.org]Runtime Environment (ruby 3.0.1p64 [x86_64-linux]) (lc:UTF-8 fs:UTF-8 in:UTF-8 ex:UTF-8)
Command line interface (CLI)
Theasciidoctor 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
Theasciidoctorman page provides a complete reference of the command line interface.
Refer to the following resources to learn more about how to use theasciidoctor command.
Ruby API
Asciidoctor also provides an API.The API is intended for integration with other Ruby software, such as Rails, GitHub, and GitLab, as well as other languages, such as Java (via AsciidoctorJ) and JavaScript (via Asciidoctor.js).
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::safeWhen using Asciidoctor via the API, the default safe mode is:secure.In secure mode, several core features are disabled, including theinclude 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 https://asciidoctor.org[AsciiDoc].'Asciidoctor.convert content,safe::safeIf you want the full HTML document, enable theheader_footer option as follows:
content ='_Zen_ in the art of writing https://asciidoctor.org[AsciiDoc].'html =Asciidoctor.convert content,header_footer:true,safe::safeIf you need access to the parsed document, you can split the conversion into discrete steps:
content ='_Zen_ in the art of writing https://asciidoctor.org[AsciiDoc].'document =Asciidoctor.load content,header_footer:true,safe::safeputs document.doctitlehtml = document.convertKeep 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 aTilt-supported template file to handle converting any node in the document.
However you go about it, youcan have 100% control over the output.For more information about how to use the API or to customize the output, see:
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 waysyou 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 fixingissues
by reviewing patches
TheContributing guide provides information on how to create, style, and submit issues, feature requests, code, and documentation to Asciidoctor.
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.
- Chat (Zulip)
- Discussion list (Nabble)
Follow@asciidoctor or search for the#asciidoctor hashtag
The Asciidoctor organization on GitHub hosts the project’s source code, issue tracker, and sub-projects.
- Source repository (git)
- Issue tracker
- Asciidoctor organization on GitHub
Code of Conduct
The core Asciidoctor project is governed by theCode of Conduct for the Asciidoctor community of projects.By participating, you’re agreeing to honor this code.Let’s work together to make this a welcoming, professional, inclusive, and safe environment for everyone.
Versioning and Release Policy
This project adheres to semantic versioning (major.minor.patch).Typically, patch releases are only made for the current minor release.However, exceptions are made on a case-by-case basis to address security vulnerabilities and other high-priority issues.
Copyright and License
Copyright © 2012-present Dan Allen, Sarah White, Ryan Waldron, and the individual contributors to Asciidoctor.Use of this software is granted under the terms of the MIT License.
See theLICENSE for the full license text.
Authors
Asciidoctor is led byDan Allen andSarah White and has received contributions frommany individuals in Asciidoctor’s awesome community.The project was initiated in 2012 byRyan Waldron based on a prototype written byNick Hengeveld for the Git website.
AsciiDoc.py was started and maintained by Stuart Rackham from2002 to 2013 and has received contributions from many individuals in theAsciiDoc.py community.
Use AsciiDoc for document markup. Really. It's actuallyreadable by humans, easier to parse and way more flexible than XML.
Asciidoctor Project
The Asciidoctor project is an effort to bring a comprehensive and accessible publishing toolchain, centered around the AsciiDoc syntax, to a growing range of ecosystems, including Ruby, JavaScript and the JVM.
In addition to an AsciiDoc processor and a collection of stylesheets, the project provides plugins for Maven, Gradle and Guard and packages for operating systems such as Fedora, Debian and Ubuntu. It also pushes AsciiDoc to evolve by introducing new ideas and innovation and helps promote AsciiDoc through education and advocacy.
Contribute to asciidoctor.org
This website is open source! The source is hosted under the Asciidoctor organization on GitHub.
If you want to help by improving upon it,fork the project, revise the content, then send a pull request. When the pull request is merged, the site will be updated automatically.