asciidoctor / asciidoctor-community-docs

Process, policy, and other shared documentation for the Asciidoctor community of projects.

Asciidoctor

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 in AsciiDoc. You can find the documentation for these projects at https://docs.asciidoctor.org.

In addition to running on Ruby, Asciidoctor can be executed on a JVM using AsciidoctorJ or in any JavaScript environment using Asciidoctor.js.

This document is also available in the following languages:
简体中文 | Deutsch | Français | 日本語

Key documentation

• Asciidoctor Documentation

• AsciiDoc Language Documentation

• AsciiDoc Syntax Quick Reference

Sponsors

We want to recognize our sponsors 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 through OpenCollective.

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-in converters for three output formats by default: HTML 5, DocBook 5, and man 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 a default 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 using AsciidoctorJ or in any JavaScript environment (including the browser) using Asciidoctor.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 Diagram

• Maven plugin and site module

• Gradle plugin

• Asciidoclet

• reveal.js converter

• EPUB 3 converter

• IntelliJ plugin

• web browser extensions

• and more

Asciidoctor is the successor to AsciiDoc.py. If you’re using AsciiDoc.py, see Migrate 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 of Ruby:

• CRuby (aka MRI) 2.7 - 3.3

• JRuby 9.2 - 9.4

• TruffleRuby (GraalVM)

🔥

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 overriding the default external and internal character encodings to utf-8. You can do so by setting the RUBYOPT environment variable as follows: 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) named asciidoctor. 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.

• Alpine Linux (asciidoctor)

• Arch Linux (asciidoctor)

• Debian (asciidoctor)

• Fedora (asciidoctor)

• OpenSUSE (rubygem-asciidoctor)

• Ubuntu (asciidoctor)

If you want to use a version of Asciidoctor that’s newer than what is installed by the package manager, see the 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

macOS

Homebrew

You can use Homebrew, the macOS package manager, to install Asciidoctor. If you don’t have Homebrew on your computer, complete the installation instructions 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.

MacPorts

You can also use MacPorts, another package manager for macOS, to install Asciidoctor. If you don’t have MacPorts on your computer, complete the installation instructions first.

Once MacPorts is installed, you’re ready to install the asciidoctor gem via the Asciidoctor port. Open a terminal and type:

$ sudo port install asciidoctor

Windows

To use Asciidoctor with Windows, you have two options.

Chocolatey

When you already use chocolatey on your machine, you can use:

choco install ruby

Then follow gem installation instructions.

Rubyinstaller

Or you use the Rubyinstaller, download the package for your Windows Version and after the installation go ahead with gem installation instructions.

gem install

Before installing Asciidoctor using gem install, you should set up RVM (or similar) 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, 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 using rvm 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

Docker

See Installing Asciidoctor using Docker.

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', '2.0.22'

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

MacPorts (macOS)

To upgrade the gem, use:

$ sudo port selfupdate
$ sudo port 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.

Asciidoctor 2.0.22 [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)

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.

• Process AsciiDoc using the CLI

• CLI options

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

⚠️	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 https://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 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:

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 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, see:

• Process AsciiDoc using the API

• API options

• Safe modes

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 issues

• by reviewing patches

The Contributing 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 input. If you need assistance or want to provide feedback, please follow the links to the resources listed on the Get Help page in the docs. Here’s a quick summary:

Project chat (Zulip)

https://chat.asciidoctor.org

Discussion list (archived)

https://discuss.asciidoctor.org

Social media (Twitter)

Follow @asciidoctor or search the #asciidoctor hashtag

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.

Source repository (git)

https://github.com/asciidoctor/asciidoctor

Issue tracker

https://github.com/asciidoctor/asciidoctor/issues

Asciidoctor organization on GitHub

https://github.com/asciidoctor

Code of Conduct

The core Asciidoctor project is governed by the Code 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 the LICENSE for the full license text.

Authors

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

AsciiDoc.py was started and maintained by Stuart Rackham from 2002 to 2013 and has received contributions from many individuals in the AsciiDoc.py community.

Trademarks

AsciiDoc® and AsciiDoc Language™ are trademarks of the Eclipse Foundation, Inc.

Changelog

Refer to the CHANGELOG for a complete list of changes in older releases.

asciidoctor-community-docs's Issues

Revise AsciiDoc entry on Wikipedia

The AsciiDoc entry on Wikipedia doesn't do the technology justice. Revise the page, building on information that's been collected for asciidoctor.org, to make the entry more complete and accurate.

For the first round, the focus should be on getting to something respectable, not necessarily on length.

Keep in mind that the entry must be impartial, so Asciidoctor should only be cited as a recent implementation, not touted as better or even faster.

Naming convention for Asciidoctor extensions

This certainly applies to processor extensions, and presumably also to converter, template, and highlighter extensions.

In order to encourage 3rd party extensions to release to ruby gems, it would be helpful to have a suggested naming convention that avoided collisions and credited the 3rd party.

In javascript, npm has namespaces. Thus I can release a @djencks/asciidoctor-openblock processor extension that won't collide with anyone else's asciidoctor-openblock extension. RubyGems apparently has no such namespace facility.

As a starting point for discussion, I suggest a pattern of <orgname>-asciidoctor-<extensionpurpose>. This doesn't fit with the advice that would indicate that this relates to Orgname::Asciidoctor::Extensionpurpose, but the existing extensions such as asciidoctor-mathematical don't do this either.

With this proposed convention, my ruby extension gem name would be djencks-asciidoctor-openblock.

Define pull request conventions

Within the Asciidoctor community of projects, I think we should agree on a general set of conventions / guidelines for PRs (at the very least, for the core projects and those closely associated with it). This will make it easier to work in the various projects without having to remember what all the individual rules are. I have been adhering certain conventions over the years, but even those may need to be revisited and revised. What I'm about to propose are meant to be general guidelines, not strict rules. But the closer we stick to the guidelines, the easier it is to get into the flow.

• issue requirement - First, I think it should be a recommendation that every human-created PR has an associated issue. The idea is that the issue is where the decision is made to approve the proposed idea and proceed with a code fix before anyone has invested time working on it. It's also where the architecture for the issue can be discussed. The issue number is what gets referenced by the CHANGELOG, so we want that to point to that initial conversation / full context. The PR can then be focused on the code review itself.

• branch name - Second, The branch from which the PR is submitted should include the issue number and a short description in the form issue-<issue number>-<desc> (e.g., issue-1897-keep-anchor-with-block). This makes it easier to organize branches locally and ensures we don't get PRs from branches that are changing while we are trying to review the PR.

• subject line - Third, we should agree on the format for the subject line for a PR. Should it start with an action keyword, like fixes|resolves|closes <issue number>? If we use these prefixes, when it's merged, the issue automatically gets closed. I know that GitHub refuses to recognize the issue number in the subject. But if it's not in the subject, then you can't quickly scan for issue-closing commits in the git history after merging it. So perhaps we need it in both the subject and the description.

• changelog entry - Fourth, every PR should include an addition to the CHANGELOG. I know some people like to generate a CHANGELOG at the time of a release, but then no one knows what's in a release until it's made. Keeping the CHANGELOG up to date with each merge has proved to be very effective in communicating what's coming. It's a living document. It also makes doing the release a lot simpler.

• merge strategy - Finally, how do we merge and what template do we use for the subject? Thus far, I've been using resolves #<issue number> summary goes here (PR #<pr number>). Does that seem right? Here's how it looks: asciidoctor/asciidoctor@a1505ef

Of course, we can't mandate behavior. That's not the point. The point is for us maintainers to lead by example and develop a workflow that's consistent and works well across the projects. What other recommendations would you add that have proven to work well?

Recommend a generic set of labels to add to a project's issue tracker

Recommend a generic, but useful, set of labels that should be added to a project's issue tracker.

Refer to the asciidoctor, asciidoctor.org and asciidoctor-documentation issue trackers for some ideas.

When the issue tracker lacks appropriate labels, it makes it more difficult for a user to enter a good "bug" report. The labels act as a guide to focus the user on the type of information that's needed.

The labels also help the maintainer keep the issues organized and scheduled. Without a good set of labels, the issue tracker ends up being a dumping ground of ideas and problems all mixed together.

That's my experience, at least.

I also think there should be several generic milestones that complement the labels. One of the most important is "support". These are issues that don't require changes to the software, and thus aren't tied to a release, but do needed to be answered and eventually closed like other issues. Other generic milestones may include "future", "design", "on hold" and so forth.

One note about the "design" milestone. I'm still debating whether this milestone can be used to group issues as a substitute for a mailinglist. It can quickly get abused for large, open ended questions or pie in the sky feature requests. On a mailinglist these naturally fall by the wayside, but in an issue tracker they earn a certain permanence. Perhaps we can just mention that this may happen and to be careful not to let it distract the focus of keeping the issue tracker groomed and addressing the more pressing issues.

Architect shared structure for project meta docs

Each of the projects hosted at docs.asciidoctor.org will likely need a space for information about the project itself. We should agree on a shared structure to use so that the experience for the reader is consistent.

Meta docs are those that talk about the project itself, as opposed to how to use the project. These docs should be in a top-level section at the bottom of the navigation tree.

First, we need to agree on a title for this section. Here are some suggestions:

• About Project
• About
• Project
• About {page-component-title}

Please state your preference and why you think it should be chosen.

Second, we need to agree on a name for the module that holds these pages. Here are some suggestions:

• project
• about
• meta

Please state your preference and why you think it should be chosen.

Finally, we need to agree on the scope. If you want, you can just have a single page (e.g., docs/modules/project/index.adoc) that has all the project information. If you want to split it out into more pages, here's a suggested hierarchy:

• About Project
  • Help Resources
  • Development
  • Copyright & License
  • Sponsorship
  • History

These pages are all optional. They are just meant to be ideas to get you started. If I've missed any, please point out what they are.

If you are using more than one page, the About Project page (e.g., docs/modules/project/index.adoc) should state the motivation and goals of the project, from a development perspective. (This is different than the description on the intro page).

The Development page should only contain high level information about how the project is developed (hosted on GitHub, GitHub issues, etc). It should then link to the CONTRIBUTING.adoc document in the project repository for the details about how to develop and contribute. I don't think that information belongs in the documentation. (If you disagree, please make the case for why it should be).

Please keep in mind that there will be a component in the site that has meta information about the Asciidoctor community as a whole. So the project doesn't need to repeat information such as the GitHub org, the discussion list, or the shared chat channel. But if the project has a specific resource, like a dedicated chat channel, then that should be mentioned in the About page / section for the project.

cc: @Mogztter @abelsromero @robertpanzer @ysb33r

Write content for documentation site home page

This repository should store the content for the documentation home page (at home/modules/ROOT/pages/index.adoc). The home page should introduce the documentation site, present a high-level overview of the Asciidoctor community of projects, and suggest some starting points for the reader.

Right now, the page should focus on projects within the ecosystem that are documented, but should leave for new additions in the future.

This page should not talk about the Asciidoctor project or community itself. That information is to be covered by the community (aka about) component.

Add a documentation style guide

A documentation style guide would be a useful tool for writers within this community. The guide would help ensure that documentation within this community remains consistent and uniform. It would also make writing easier as it would save writers from having to reinvent solutions for common scenarios that come up, ranging from how to structure navigation, to how to refer to technical terms, to how to define anchors.

The documentation style guide should be just a set of guidelines. While we encourage each project to adopt it, it's up to that project to decide to do so. And a project is free to extend these guidelines with special cases or overrides. The main purpose to provide a common foundation from which we can all start.