Asciidoctor User Manual
User Manual:
Open the PDF directly: View PDF 
.
Page Count: 315 [warning: Documents this large are best viewed by clicking the View PDF Link!]
12/20/2018 Asciidoctor User Manual
https://asciidoctor.org/docs/user-manual/ 2/315
Table of Contents
Introduction to Asciidoctor
1. What is Asciidoctor?
1.1. The Big Picture
1.2. Asciidoctor on the JVM
1.3. Asciidoctor.js
1.4. Asciidoctor’s Most Notable Benets
1.5. Compared to MarkDown
Quick Starts
2. Using the Command Line Interface
3. Using the Ruby API
Getting Started
4. System Requirements
5. Installing the Asciidoctor Ruby Gem
5.1. Install using gem
5.2. Install using Bundler
5.3. Install on Fedora
5.4. Install on Debian or Ubuntu
5.5. Install on Alpine Linux
6. Upgrading the Asciidoctor Ruby Gem
7. Extensions and Integrations
Terms and Concepts
8. Elements
9. Formatting Marks
9.1. Constrained quotes
9.2. Unconstrained quotes
9.3. When should I use unconstrained quotes?
9.4. Unconstrained formatting edge cases
9.5. Escaping unconstrained quotes
10. Attributes
10.1. Attribute Restrictions
10.2. Attribute Assignment Precedence
10.3. Using Attributes: Set, Assign, and Reference
10.4. Setting Attributes on a Document
10.5. Setting Attributes on an Element
10.6. Assigning Document Attributes Inline
Building a Document
11. Text Editor
12. Document Types
12.1. Inline doctype
13. Basic Document Anatomy
14. Header
14.1. Document Title
14.2. Author and Email
14.3. Revision Number, Date and Remark
14.4. Subtitle Partitioning
14.5. Metadata
14.6. Header Summary
15. Preamble
16. Sections
16.1. Titles as HTML Headings
16.2. Auto-generated IDs
16.3. Custom IDs
16.4. Multiple Anchors
16.5. Links
16.6. Anchors
12/20/2018 Asciidoctor User Manual
https://asciidoctor.org/docs/user-manual/ 3/315
16.7. Numbering
16.8. Discrete Headings (aka Floating Titles)
16.9. Section Styles
16.10. Sections Summary
17. Blocks
17.1. Title
17.2. Metadata
17.3. Delimited blocks
17.4. Built-in blocks summary
18. Paragraph
18.1. Line Breaks
18.2. Lead Style
19. Text Formatting
19.1. Bold and Italic
19.2. Quotation Marks and Apostrophes
19.3. Subscript and Superscript
19.4. Monospace
19.5. Custom Styling With Attributes
20. Unordered Lists
20.1. Nested
20.2. Complex List Content
20.3. Custom Markers
20.4. Checklist
21. Ordered Lists
21.1. Nested
21.2. Numbering Styles
22. Description List
22.1. Question and Answer Style List
23. Tables
23.1. Columns
23.2. Column Formatting
23.3. Cell Formatting
23.4. Header Row
23.5. Footer Row
23.6. Table Width
23.7. Table Borders
23.8. Striping
23.9. Orientation
23.10. Nested Tables
23.11. Table Caption
23.12. Escaping the Cell Separator
23.13. Delimiter-Separated Values
23.14. Summary
24. Horizontal Rules
24.1. Markdown-style horizontal rules
25. Page Break
26. URLs
26.1. Link to Relative Files
26.2. Summary
27. Cross References
27.1. Automatic Anchors
27.2. Dening an Anchor
27.3. Internal Cross References
27.4. Validating Internal Cross References
27.5. Customizing the Cross Reference Text
27.6. Inter-document Cross References
28. Include Directive
28.1. Anatomy
12/20/2018 Asciidoctor User Manual
https://asciidoctor.org/docs/user-manual/ 4/315
28.2. Processing
28.3. File resolution
28.4. Partitioning large documents and using leveloset
28.5. AsciiDoc vs non-AsciiDoc les
28.6. Select Portions of a Document to Include
28.7. Normalize Block Indentation
28.8. Include Content from a URI
28.9. Caching URI Content
28.10. Include a File Multiple Times in the Same Document
29. Images
29.1. Setting the Location of Images
29.2. Putting Images in Their Place
29.3. Sizing Images
29.4. Taming SVGs
29.5. Summary
30. Video
30.1. YouTube and Vimeo videos
30.2. Supported Attributes
31. Audio
32. Admonition
33. Sidebar
34. Example
35. Prose Excerpts, Quotes and Verses
35.1. Quote
35.2. Verse
36. Comments
Controlling Your Content
37. Text Substitutions
37.1. Special Characters
37.2. Quotes
37.3. Attributes
37.4. Replacements
37.5. Macros
37.6. Post Replacements
37.7. Applying Substitutions
37.8. Incremental Substitutions
37.9. Preventing Substitutions
38. Literal Text and Blocks
39. Listing Blocks
39.1. To Wrap or to Scroll
40. Passthroughs
40.1. Passthrough Macros
40.2. Passthrough Blocks
41. Open Blocks
Enriching Your Content
42. Equations and Formulas
43. Activating stem support
43.1. Inline Stem Content
43.2. Block Stem Content
43.3. Using Multiple Stem Interpreters
43.4. Enabling STEM expressions in the DocBook Toolchain
44. User Interface Macros
44.1. Keyboard shortcuts
44.2. Menu selections
44.3. UI buttons
45. Icons
45.1. Admonition Icons
12/20/2018 Asciidoctor User Manual
https://asciidoctor.org/docs/user-manual/ 5/315
45.2. Inline Icons
45.3. Favicon
46. Syntax Highlighting Source Code
46.1. Enabling Source Highlighting
46.2. Available Source Highlighters
46.3. Applying Source Highlighting
46.4. Pygments
46.5. CodeRay
46.6. highlight.js
47. Callouts
47.1. Copy and Paste Friendly Callouts
47.2. Callout Icons
48. Conditional Preprocessor Directives
48.1. Processing
48.2. ifdef Directive
48.3. ifndef Directive
48.4. Checking multiple attributes (ifdef and ifndef only)
48.5. ifeval directive
49. Docinfo Files
49.1. Head docinfo les
49.2. Footer docinfo les
49.3. Naming docinfo les
49.4. Locating docinfo les
49.5. Attribute substitution in docinfo les
50. Counters
Structuring, Navigating, and Referencing Your Content
51. Colophon
52. Table of Contents
52.1. In-Document Placement
52.2. Side Column Placement
52.3. Title
52.4. Levels
52.5. Using a TOC with Embeddable HTML
52.6. Table of Contents Summary
53. Abstract
54. Preface
55. Dedication
56. Book Parts and Chapters
57. Appendix
58. Glossary
59. Bibliography
60. Index
60.1. Index Terms
60.2. Index Catalog
61. Footnotes
Processing Your Content
62. Selecting an Output Format
63. HTML
63.1. Using the Command Line
63.2. Using the Ruby API
63.3. Styling the HTML with CSS
63.4. Managing Images
63.5. CodeRay and Pygments Stylesheets
64. XHTML
65. DocBook
66. Man Pages
67. PDFs
12/20/2018 Asciidoctor User Manual
https://asciidoctor.org/docs/user-manual/ 6/315
68. Preview Your Content
68.1. Guard/Live Viewer
69. CLI Inputs and Outputs
69.1. Process Multiple Source Files from the CLI
69.2. Specifying an Output File
69.3. Piping Content Through the CLI
70. Running Asciidoctor Securely
70.1. Set the Safe Mode in the CLI
70.2. Set the Safe Mode in the API
70.3. Set Attributes Based on the Safe Mode
Customizing Your Output
71. Applying a Theme
72. Stylesheet Factory
72.1. Setting up the Factory
72.2. Creating a Theme
72.3. Applying a Stylesheet
72.4. Generate an HTML Document
72.5. External Preview
73. Slide Decks
74. Custom Backends
74.1. Storing Multiple Templates
75. Using Asciidoctor with Other Languages
75.1. Translating built-in labels
75.2. Translation
Publishing Your Content
76. Static Website Generators
76.1. Front Matter Added for Static Site Generators
Using Asciidoctor’s API
77. Require the Library
78. Load and Convert Files
79. Load and Convert Strings
79.1. Embeddable output
79.2. Convert inline markup only
79.3. Convert to DocBook
80. Provide Custom Templates
Extensions
81. Extension Points
82. Example Extensions
82.1. Preprocessor Example
82.2. Tree Processor Example
82.3. Postprocessor Example
82.4. Docinfo Processor Example
82.5. Block Processor Example
82.6. Block Macro Processor Example
82.7. Inline Macro Processor Example
82.8. Include Processor Example
Build Integrations and Implementations
83. Java
84. Gradle
85. Maven
86. Apache Ant
87. JavaDoc
88. JavaScript
Conversions and Migrations
89. Migrating from AsciiDoc Python
89.1. Command Line Interface
12/20/2018 Asciidoctor User Manual
https://asciidoctor.org/docs/user-manual/ 7/315
89.2. Changed Syntax
89.3. Deleted and Deprecated Syntax and Attributes
89.4. Default HTML Stylesheet
89.5. Mathematical Expressions
89.6. AsciiDoc Python Extensions
89.7. Custom Extensions
89.8. Features Introduced by Asciidoctor
90. Convert DocBook XML to AsciiDoc
91. Convert Markdown to AsciiDoc
92. Convert Conuence XHTML to AsciiDoc
93. Convert MS Word to AsciiDoc
Resources
94. Copyright and License
95. Authors
96. Troubleshooting
Glossary
Appendix A: Catalog of Document Attributes
A.1. Environment Attributes
A.2. Built-in Attributes
A.3. Predened Attributes for Character Replacements
Appendix B: CLI Options
B.1. Security Settings
B.2. Document Settings
B.3. Document Conversion
B.4. Processing Information
B.5. Program Information
Appendix C: Ruby API Options
Appendix D: Application Messages
12/20/2018 Asciidoctor User Manual
https://asciidoctor.org/docs/user-manual/ 8/315
If you find errors or omissions in this document, please don’t hesitate to submit an issue or open a pull request
(https://github.com/asciidoctor/asciidoctor.org/issues) with a fix. We also encourage you to ask questions and discuss
any aspects of the project on the mailing list (http://discuss.asciidoctor.org) or in the chat room
(https://gitter.im/asciidoctor/asciidoctor). New contributors are always welcome!
This manual assumes you are using Asciidoctor to produce and convert your document. Asciidoctor implements more syntax,
attributes and functions than the legacy AsciiDoc.py processor. Migrating from AsciiDoc Python lists which features are available
to the Asciidoctor and AsciiDoc processors.
12/20/2018 Asciidoctor User Manual
https://asciidoctor.org/docs/user-manual/ 10/315
1. What is Asciidoctor?
Asciidoctor is a fast text processor and publishing toolchain for converting AsciiDoc content to HTML5, EPUB3, PDF, DocBook 5 (or
4.5) slidedecks and other formats. Asciidoctor is written in Ruby, packaged as a RubyGem and published to RubyGems.org
(https://rubygems.org/gems/asciidoctor). The gem is also packaged in several Linux distributions, including Fedora, Debian and
Ubuntu. Asciidoctor is open source, hosted on GitHub (https://github.com/asciidoctor/asciidoctor), and released under the MIT license.
1.1. 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 adds a default stylesheet to the HTML5 document, as shown, to provide a pleasant
out-of-the-box experience.
1.2. Asciidoctor on the JVM
You can run Asciidoctor on the JVM using JRuby. You can also use AsciidoctorJ (https://github.com/asciidoctor/asciidoctorj) to invoke
Asciidoctor’s APIs from Java and other JVM languages.
1.3. Asciidoctor.js
Asciidoctor can be used in JavaScript. Opal (https://opalrb.com) is used to transcompile the code from Ruby to JavaScript to make
Asciidoctor.js (https://github.com/asciidoctor/asciidoctor.js), which can be used wherever JavaScript runs, such as in a web browser or
on Node.js.
1.4. Asciidoctor’s Most Notable Benets
While Asciidoctor aims to offer full compliance with the AsciiDoc syntax, it’s more than just a clone.
Built-in and custom templates
Asciidoctor uses a set of built-in ERB templates to generate HTML 5 and DocBook output that is structurally equivalent to what
AsciiDoc produces. Any of these templates can be replaced by a custom template written in any template language available in
the Ruby ecosystem. Custom template rendering is handled by the Tilt (https://github.com/rtomayko/tilt) template abstraction library.
Tilt is one of the most popular gems in the Ruby ecosystem.
Parser and object model
Leveraging the Ruby stack isn’t the only benefit of Asciidoctor. Unlike the AsciiDoc Python implementation, Asciidoctor parses
and converts the source document in discrete steps. This makes conversion optional and gives Ruby programs the opportunity to
extract, add or replace information in the document by interacting with the document object model Asciidoctor assembles.
Developers can use the full power of the Ruby programming language to play with the content in the document.
Performance and security
No coverage of Asciidoctor would be complete without mention of its speed. Despite not being an original goal of the project,
Asciidoctor has proven startlingly fast. It loads, parses, and converts documents a 100 times as fast as the Python
implementation. That’s good news for developer productivity and good news for GitHub or any server-side application that needs
to render AsciiDoc markup. Asciidoctor also offers several levels of security, further justifying its suitability for server-side
deployments.
Beyond Ruby
12/20/2018 Asciidoctor User Manual
https://asciidoctor.org/docs/user-manual/ 11/315
Asciidoctor’s usage is not limited to the Ruby community. Thanks to JRuby (https://www.jruby.org), a port of Ruby to the JVM,
Asciidoctor can be used inside Java applications as well. Plugins are available for Apache Maven
(https://github.com/asciidoctor/asciidoctor-maven-plugin), Gradle (https://github.com/asciidoctor/asciidoctor-gradle-plugin), and Rewrite
(https://github.com/ocpsoft/rewrite/tree/master/transform-markup). These plugins are based on the AsciidoctorJ
(https://github.com/asciidoctor/asciidoctorj) for Asciidoctor.
Asciidoctor also ships with a command line interface (CLI). The Asciidoctor CLI, asciidoctor (https://asciidoctor.org/man/asciidoctor), is
a drop-in replacement for the asciidoc.py script from the AsciiDoc Python distribution.
1.4.1. AsciiDoc Syntax 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, PDF, DocBook 5, etc. You have the option of writing your own converter or providing Tilt
(https://github.com/rtomayko/tilt)-supported templates to customize the generated output or produce alternative formats.
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., btn:[Save] ). Asciidoctor also offers a modern, responsive theme based on
Foundation (https://foundation.zurb.com) to style the HTML5 output.
1.5. Compared to MarkDown
The most compelling reason to choose a lightweight markup language for writing is to minimize the number of technical concepts
an author must grasp in order to be immediately productive. In other words, the goal is to be able to write without friction.
1.5.1. Getting your start with Markdown
The defacto lightweight markup language is Markdown. (At least, that’s what you call it at first). The main advantage of
Markdown lies in its primitive syntax: its manual and cheatsheet are one and the same. But this advantage is also its greatest
weakness.
As soon as authors need something slightly more complex than basic prose (e.g., tables, cross references, footnotes, embedded
YouTube videos, etc.), they find themselves resorting to embedded HTML or seeking out more feature-rich implementations.
Markdown has become a maze of different implementations, termed “flavors”, which make a universal definition evasive.
The IETF has declared “there is no such thing as "invalid" Markdown.” See This Is Markdown! Or: Markup and
Its Discontents (https://tools.ietf.org/html/rfc7763#section-1.1).
Here’s how the story inevitably goes. You start out with Markdown. Then it’s Markdown + X. Then Markdown + X + Y. And down
the rabbit hole you go. What’s worse, X and Y often require you to sprinkle in HTML, unnecessarily coupling content with
presentation and wrecking portability. Your instinct to choose Markdown is good. There are just better options.
1.5.2. Graduating to AsciiDoc
AsciiDoc presents a more sound alternative. The AsciiDoc syntax is more concise than (or at least as concise as) Markdown. At the
same time, AsciiDoc offers power and flexibility without requiring the use of HTML or “flavors” for essential syntax such as
tables, description lists, admonitions (tips, notes, warnings, etc.) and table of contents.
It’s important to understand that AsciiDoc was initially designed as a plain-text alternative to the DocBook XML schema. AsciiDoc
isn’t stuck in a game of whack-a-mole trying to satisfy publishing needs like Markdown. Rather, the AsciiDoc syntax was explicitly
designed with the needs of publishing in mind, both print and web. If the need arises, you can make full use of the huge choice of
tools available for a DocBook workflow using Asciidoctor’s DocBook converter. That’s why mapping to an enterprise
documentation format like DocBook remains a key use case for AsciiDoc.
And yet, AsciiDoc is simple enough to stand in as a better flavor of Markdown. But what truly makes AsciiDoc the right
investment is that its syntax was designed to be extended as a core feature. This extensibility not only means that AsciiDoc has a
more to offer, with room to grow, it also fulfills the objective of ensuring your content is maximally reusable.
1.5.3. Comparison by example
The following table shows the AsciiDoc syntax as it compares to Markdown. Since AsciiDoc supports a broader range of syntax
than Markdown, this side-by-side comparison focuses mainly on areas where the syntax overlaps.
A selection of AsciiDoc language features compared to Markdown
12/20/2018 Asciidoctor User Manual
https://asciidoctor.org/docs/user-manual/ 12/315
Language
Feature
Markdown AsciiDocLanguage
Feature
Markdown AsciiDoc
Bold
(constrained)
Bold
(unconstrained)
Italic
(constrained)
Italic
(unconstrained)
n/a
Monospace
(constrained)
Monospace
(unconstrained)
Link with label
Relative link
File link
Cross reference
Block ID /
anchor
Inline anchor n/a
Inline image w/
alt text
Block image w/
alt text
n/a
Section
heading*
Blockquote*
Literal block Indented (by 1 or more spaces)
Delimited
**bold**
MARKDOWN
*bold*
ASCIIDOC
**b**old
MARKDOWN
**b**old
ASCIIDOC
*italic*
MARKDOWN
_italic_
ASCIIDOC
__i__talic
ASCIIDOC
`monospace`
MARKDOWN
`monospace`
ASCIIDOC
`m`onospace
MARKDOWN
``m``onospace
ASCIIDOC
[AsciiDoc](http://asciidoc.org)
MARKDOWN
http://asciidoc.org[AsciiDoc]
ASCIIDOC
[user guide](user-guide.html)
MARKDOWN
link:user-guide.html[user guide]
xref:user-guide.adoc[user guide]
ASCIIDOC
[get the PDF]({% raw %}{{ site.url }}{% endraw
%}/assets/mydoc.pdf)
MARKDOWN
link:{site-url}/assets/mydoc.pdf[get the PDF]
ASCIIDOC
See link:#_usage[Usage].
<h2 id="_usage">Usage</h2>
MARKDOWN
See <<_usage>>.
== Usage
ASCIIDOC
<h2 id="usage">Usage</h2>
MARKDOWN
[#usage]
== Usage
ASCIIDOC
. [[step-1]]Download the software
ASCIIDOC
MARKDOWN
image:logo.png[Logo]
ASCIIDOC
image::logo.png[Logo]
ASCIIDOC
## Heading 2
MARKDOWN
== Heading 2
ASCIIDOC
> Quoted text.
>
> Another paragraph in quote.
MARKDOWN
____
Quoted text.
Another paragraph in quote.
____
ASCIIDOC
$ gem install asciidoctor
MARKDOWN
$ gem install asciidoctor
ASCIIDOC
....
$ gem install asciidoctor
....
ASCIIDOC
12/20/2018 Asciidoctor User Manual
https://asciidoctor.org/docs/user-manual/ 13/315
Language
Feature
Markdown AsciiDoc
Code block*
Unordered list
Ordered list
Thematic break
(aka horizontal
rule)*
Typographic
quotes (aka
“smart quotes”)
Enabled through an extension switch, but offer little
control in how they are applied.
Document
header
Slapped on as “front matter” Native support!
Admonitions n/a
Sidebars n/a
Lightweight Markup
Writing languages that let you type less and
express more.
Block titles n/a Grocery list
Milk
Eggs
Bread
Includes n/a
```java
public class Person {
private String name;
public Person(String name) {
this.name = name;
}
}
```
MARKDOWN
[source,java]
----
public class Person {
private String name;
public Person(String name) {
this.name = name;
}
}
----
ASCIIDOC
* apples
* orange
* temple
* navel
* bananas
MARKDOWN
* apples
* oranges
** temple
** navel
* bananas
ASCIIDOC
1. first
2. second
3. third
MARKDOWN
. first
. second
. third
ASCIIDOC
***
* * *
---
- - -
___
_ _ _
MARKDOWN
'''
ASCIIDOC
The `'90s popularized a new form of music known
as "`grunge`" rock.
It's influence extended well beyond music.
ASCIIDOC
---
layout: docs
title: Writing posts
prev_section: defining-frontmatter
next_section: creating-pages
permalink: /docs/writing-posts/
---
MARKDOWN
= Writing posts
:awestruct-layout: base
:showtitle:
:prev_section: defining-frontmatter
:next_section: creating-pages
ASCIIDOC
TIP: You can add line numbers to source
listings by adding the word `numbered` in the
attribute list after the language name.
ASCIIDOC
include::intro.adoc[]
ASCIIDOC
12/20/2018 Asciidoctor User Manual
https://asciidoctor.org/docs/user-manual/ 14/315
Language
Feature
Markdown AsciiDoc
URI reference
Custom CSS
classes
n/a
* Asciidoctor also supports the Markdown syntax for this language feature.
You can see that AsciiDoc has the following advantages over Markdown:
AsciiDoc uses the same number of markup characters or less when compared to Markdown in nearly all cases.
AsciiDoc uses a consistent formatting scheme (i.e., it has consistent patterns).
AsciiDoc can handle all permutations of nested inline (and block) formatting, whereas Markdown often falls down.
AsciiDoc handles cases that Markdown doesn’t, such as a proper approach to inner-word markup, source code blocks and
block-level images.
Certain Markdown flavors, such as Markdown Extra, support additional features such as tables and description
lists. However, since these features don’t appear in “plain” Markdown, they’re not included in the comparison
table. But they’re supported natively by AsciiDoc.
Asciidoctor, which is used for converting AsciiDoc on GitHub and GitLab, emulates “the good parts” of the Markdown syntax, like
headings, blockquotes and fenced code blocks, making migration from Markdown to AsciiDoc fairly simple. For details about
migration, see Markdown Compatibility (https://asciidoctor.org/docs/asciidoc-syntax-quick-reference/#markdown-compatibility).
To read more about the shortcomings of Markdown, see these opinion pieces:
Why You Shouldn’t Use “Markdown” for Documentation
(http://ericholscher.com/blog/2016/mar/15/dont-use-markdown-for-technical-docs/)
Markdown Considered Harmful (https://medium.com/@bbirdiman/markdown-considered-harmful-495ccfe24a52)
Sundown on Markdown? (https://www.simple-talk.com/blogs/2014/02/28/sundown-on-markdown/)
[home]: https://example.org "Home"
Go [home].
MARKDOWN
:home: https://example.org
Go {home}[Home].
ASCIIDOC
[.path]_Gemfile_
ASCIIDOC
12/20/2018 Asciidoctor User Manual
https://asciidoctor.org/docs/user-manual/ 16/315
2. Using the Command Line Interface
Asciidoctor’s command line interface (CLI) is a drop-in replacement for the asciidoc.py command from the Python
implementation.
If the Asciidoctor gem installed successfully, the asciidoctor command line interface (CLI) will be available on your PATH. To
confirm that Asciidoctor is available, execute:
$ asciidoctor --version
The following information should be output in your terminal:
Asciidoctor 1.5.6.2 [https://asciidoctor.org]
To invoke Asciidoctor from the CLI and convert an .adoc file, execute:
$ asciidoctor <asciidoc_file>
This will use the built-in defaults for options and create a new file in the same directory as the input file, with the same base
name, but with the .html extension.
There are many other options available, listed in CLI Options.
Full help is provided in the man page (https://asciidoctor.org/man/asciidoctor) or via:
$ asciidoctor --help
There is also an asciidoctor-safe command, which turns on safe mode by default, preventing access to files outside the parent
directory of the source file. This mode is very similar to the safe mode of asciidoc.py .
12/20/2018 Asciidoctor User Manual
https://asciidoctor.org/docs/user-manual/ 17/315
3. Using the Ruby API
In addition to the command line interface, Asciidoctor provides a Ruby API. The API is intended for integration with other
software projects and is suitable for server-side applications, such as Rails, Sinatra and GitHub.
Asciidoctor also has a Java API that mirrors the Ruby API. The Java API calls through to the Ruby API using an embedded JRuby
runtime. See the AsciidoctorJ project for more information.
To use Asciidoctor in your application, you first need to require the gem:
This statement makes all of the public APIs in Asciidoctor (https://www.rubydoc.info/gems/asciidoctor/Asciidoctor) available to your
script or application. You are now ready to start processing AsciiDoc documents.
The main entry points in the Asciidoctor API are the static methods to load or convert AsciiDoc documents, which we’ll cover the
next two chapters.
To parse a file into an Asciidoctor::Document object:
You can get information about the document:
More than likely, you will want to convert the document. To convert a file containing AsciiDoc markup to HTML 5, use:
The command will output to the file mysample.html in the same directory.
You can convert the file to DocBook 5.0 by setting the :backend option to 'docbook' :
The command will output to the file mysample.xml in the same directory. If you’re on Linux, you can view the file using Yelp
(https://wiki.gnome.org/action/show/Apps/Yelp).
You can also use the API to convert strings and load custom templates.
require 'asciidoctor'
RUBY
doc = Asciidoctor.load_file 'mysample.adoc'
RUBY
puts doc.doctitle
puts doc.attributes
RUBY
Asciidoctor.convert_file 'mysample.adoc'
RUBY
Asciidoctor.convert_file 'mysample.adoc', backend: 'docbook'
RUBY
12/20/2018 Asciidoctor User Manual
https://asciidoctor.org/docs/user-manual/ 19/315
4. System Requirements
Asciidoctor works on Linux, macOS and Windows.
Asciidoctor requires one of the following implementations of Ruby:
Ruby 1.8.7
Ruby 1.9.3
Ruby 2 (2.0.0 or better)
JRuby 1.7 (Ruby 1.8 and 1.9 modes)
JRuby 9000
Rubinius 2.0 (Ruby 1.8 and 1.9 modes)
Opal (Javascript)
We expect Asciidoctor to work with other versions of Ruby as well. We welcome your help testing those versions if you are
interested in seeing them supported.
12/20/2018 Asciidoctor User Manual
https://asciidoctor.org/docs/user-manual/ 20/315
5. Installing the Asciidoctor Ruby Gem
Asciidoctor can be installed using the gem command, Bundler or a Linux package manager.
5.1. Install using gem
To install Asciidoctor using the gem command:
1. Open a terminal
2. Type the following gem command
$ gem install asciidoctor
If the Asciidoctor gem installed successfully, the asciidoctor command line interface (CLI) will be available on your PATH. To
confirm that Asciidoctor is available, execute:
$ asciidoctor --version
The following output should appear in your terminal:
Asciidoctor 1.5.6.2 [https://asciidoctor.org]
Runtime Environment (ruby 2.3.0p0 [x86_64-linux]) (lc:UTF-8 fs:UTF-8 in:- ex:UTF-8)
5.2. Install using Bundler
To install Asciidoctor for a project using Bundler:
1. Open your project’s Gemfile
2. Add the asciidoctor gem using:
gem 'asciidoctor'
3. Save the Gemfile
4. Open a terminal
5. Install the gem using the bundle command:
$ bundle
5.3. Install on Fedora
To install Asciidoctor on Fedora (or RHEL via EPEL) using the rubygem-asciidoctor
(https://apps.fedoraproject.org/packages/rubygem-asciidoctor) package:
1. Open a terminal
2. Run the installation command on Fedora:
$ sudo dnf install asciidoctor
The benefit of installing the gem using this method is that the package manager will also install Ruby and RubyGems if not
already on your machine.
5.4. Install on Debian or Ubuntu
To install Asciidoctor on Debian or Ubuntu:
1. Open a terminal
2. Type the following apt-get command using sudo:
$ sudo apt-get install asciidoctor
12/20/2018 Asciidoctor User Manual
https://asciidoctor.org/docs/user-manual/ 21/315
The benefit of installing the gem via apt-get is that the package manager will also install Ruby and RubyGems if not already on
your machine.
5.5. Install on Alpine Linux
To install Asciidoctor on Alpine Linux using the asciidoctor (https://pkgs.alpinelinux.org/packages?name=asciidoctor) package:
1. Open a terminal
2. Type the following apk command using sudo:
$ sudo apk add asciidoctor
The benefit of installing the gem via apk is that the package manager will also install Ruby and RubyGems if not already on your
machine.
12/20/2018 Asciidoctor User Manual
https://asciidoctor.org/docs/user-manual/ 22/315
6. Upgrading the Asciidoctor Ruby Gem
If you have an earlier version of Asciidoctor installed, you can update the gem using the gem command:
$ gem update asciidoctor
If you accidentally use gem install instead of gem update , then you’ll end up with both versions installed.
To remove the older version, use the following gem command:
$ gem cleanup asciidoctor
On Fedora, you can update the package using:
$ sudo dnf update asciidoctor
Your Fedora system may be configured to automatically update packages, in which case no further action is
required by you. Refer to the Fedora docs (https://docs.fedoraproject.org) if you are unsure.
On Debian or Ubuntu, you can update the package using:
$ sudo apt-get upgrade asciidoctor
On Alpine Linux, you can update the package using:
$ sudo apk add --upgrade asciidoctor
The Linux packages may not be available right away after a release of the gem. It may take several weeks for
the packages to be updated. If you need to upgrade to the latest version immediately, use the gem install option
documented above.
12/20/2018 Asciidoctor User Manual
https://asciidoctor.org/docs/user-manual/ 24/315
Terms and Concepts
All of the content in an Asciidoctor document, including lines of text, predefined styles, and processing commands, is classified as
either a block or an inline element. Within each of these elements are an array of styles, options, and functions that can be
applied to your content.
This section will provide you with an overview of what each of these elements and sub-elements are and the basic syntax and
rules for using them.
12/20/2018 Asciidoctor User Manual
https://asciidoctor.org/docs/user-manual/ 25/315
8. Elements
One or more lines of text in a document are defined as a block element. Block elements can be nested within block elements.
A document can include the following block elements:
Header
Title
Author Info
First Name
Middle Name
Last Name
Email Address
Revision Info
Revision Number
Revision Date
Revision Remark
Attribute Entry
Preamble
Section
Title
Section Body
BlockId
Block Title
Block Macro
Block
Paragraph
Delimited Block
Table
List
Bulleted List
Numbered List
Description List
Callout List
List Entry
List Label
List Item
Item Text
List Paragraph
List Continuation
An inline element performs an operation on a subset of the content within a block element.
Inline elements include:
Quotes
Replacements
12/20/2018 Asciidoctor User Manual
https://asciidoctor.org/docs/user-manual/ 26/315
Special characters
Special words
Attribute references
Inline macros
12/20/2018 Asciidoctor User Manual
https://asciidoctor.org/docs/user-manual/ 27/315
9. Formatting Marks
There are two categories of formatting marks for applying styles (i.e., formatting) to text, constrained and unconstrained. These
formatting marks are referred to as quotes in the AsciiDoc syntax. This section covers their purpose, their differences and how to
apply them.
9.1. Constrained quotes
In short, “constrained” means around a word or sequence of words.
Constrained quotes are single characters (often symbols) placed around a word. The “around” is defined by the fact that word
characters do not appear immediately outside the enclosing marks.
You use this form to format a word that stands alone,
When the word stands alone
to format a sequence of words,
When there are multiple words
or to format a word adjacent to punctuation, like an exclamation mark.
When the word is adjacent to punctuation
9.2. Unconstrained quotes
In short, “unconstrained” means anywhere, including within a word.
Unconstrained quotes are repeated characters (often symbols) placed anywhere in the text, including within a word. The “within”
is defined by the fact that a word character may appear directly outside one of the enclosing marks.
Unconstrained formatting
9.3. When should I use unconstrained quotes?
Consider the following questions:
Is there a letter, number, underscore directly outside the formatting marks (on either side)?
Is there a colon, semi-colon, or closing curly bracket directly before the starting formatting mark?
Is there a space directly inside of the formatting mark?
If you answered “yes” to any of these questions, you need to switch to unconstrained (double formatting) quotes.
To help you determine whether a particular syntax pattern requires unconstrained quotes, consider the following scenarios:
Constrained or Unconstrained?
AsciiDoc Result Quote type Reason
Sara__h__ SarahUnconstrained The a is directly adjacent to
(the left of) a formatting
mark.
**B**old Bold Unconstrained The o is directly adjacent to
(the right of) a formatting
mark.
That is *strong* stuff!
ASCIIDOC
That is *really strong* stuff!
ASCIIDOC
This stuff sure is *strong*!
ASCIIDOC
She spells her name with an "`h`", as in Sara**h**.
ASCIIDOC
12/20/2018 Asciidoctor User Manual
https://asciidoctor.org/docs/user-manual/ 28/315
AsciiDoc Result Quote type Reason
–**2016** –2016 Unconstrained ; is directly adjacent to (the
left of) a formatting mark.
** bold ** bold Unconstrained There are spaces directly
inside the formatting marks.
*2016*– 2016– Constrained The adjacent & is not a letter,
number, underscore, colon,
or semi-colon.
*9*-to-*5* 9-to-5Constrained The adjacent hyphen is not a
letter, number, underscore,
colon, or semi-colon.
9.4. Unconstrained formatting edge cases
There are cases when it might seem logical to use constrained quotes, however unconstrained quotes are required. This happens
because of the way the Asciidoctor parser (and the AsciiDoc Python parser) currently handles substitutions.
Substitutions may be applied by the parser before getting to the formatting marks, in which case the characters adjacent to those
marks may not be what you see in the original source.
One such example is enclosing a monospaced phrase (i.e., codespan) inside typographic quotation marks, such as “ endpoints ”.
Here’s how you would enter that:
A monospaced phrase inside typographic quotes
You might start with the following syntax:
That only gives you “endpoints”, thought. The backticks contribute to making the typographic quotes.
Adding another set of backticks isn’t enough because the phrase now calls for unconstrained formatting marks. As a result, the
parser ignores the inner set of backticks and instead interprets them as literal characters.
So you have to unconstrained monospace inside the typographic quotes (three sets of backticks in total) to coerce the parser into
formatting the phrase as monospace.
Although more rare, if what you’re after is to surround the monospaced phrase with normal double quotes, such as " endpoints ",
then you need to interrupt the typographic quote syntax by applying a role to monospaced phrase or escaping the typographic
quote. For example:
A monospaced phase inside normal quotes
Another example is a possessive, monospaced phrase that ends in an “s”. In this case, you must switch the monospaced phrase to
unconstrained formatting.
Rendered possessive, monospaced phrase
"```endpoints```"
ASCIIDOC
"`endpoints`"
ASCIIDOC
"``endpoints``"
ASCIIDOC
"```endpoints```"
ASCIIDOC
"[.code]``endpoints``" or \"``endpoints``"
ASCIIDOC
The ``class```' static methods make it easy to operate on files and directories.
ASCIIDOC
12/20/2018 Asciidoctor User Manual
https://asciidoctor.org/docs/user-manual/ 29/315
The class ’ static methods make it easy to operate on files and directories.
Alternately, you could encode the typographic apostrophe directly in the AsciiDoc source to get the same result without the need
to use unconstrained formatting.
This situation may improve in the future when Asciidoctor is switched to using a parsing expression grammar
for inline formatting instead of the current regular expression-based strategy. For details, follow issue #61
(https://github.com/asciidoctor/asciidoctor/issues/61).
9.5. Escaping unconstrained quotes
Unconstrained quotes are meant to match anywhere in the text, context free. However, that means you catch them formatting
when you don’t intend them to. Admittedly, these symbols are a bit tricky to type literally when the content calls for it. But being
able to do so is just a matter of knowing the tricks, which this section will cover.
Let’s assume you are typing the following two lines:
In the first sentence, you aren’t looking for any text formatting, but you’re certainly going to get it. Double underscore is an
unconstrained formatting mark. In the second sentence, you might expect CB###2 and CB###3 to be formatted in monospace
and highlighted. However, what you get is a scrambled mess. The mix of constrained and unconstrained formatting marks in the
line is ambiguous.
There are two (reliable) solutions for escaping unconstrained formatting marks:
Use an attribute reference to insert the unconstrained formatting mark verbatim
Wrap the text you don’t want formatted in an inline passthrough
The attribute reference is preferred because it’s the easiest to read:
This works because attribute expansion is performed after text formatting (i.e., quotes substitution) under normal substitution
order. (Recall that backticks around text format the text in monospace but permit the use of attribute references).
Here’s how you’d write these lines using the inline passthrough to escape the unconstrained formatting marks instead:
Notice the addition of the plus symbols. That’s the closest thing to a text formatting escape. Everything between the plus symbols
is escaped from interpolation (attribute references, text formatting, etc). However, the text still receives proper output escaping
for HTML (e.g., < becomes < ).
The enclosure `+TEXT+` (text enclosed in pluses surrounded by backticks) is a special formatting combination in Asciidoctor. It
means to format TEXT as monospace, but don’t interpolate formatting marks or attribute references in TEXT. It’s roughly
equivalent to Markdown’s backticks. Since AsciiDoc offers more advanced formatting, the double enclosure is necessary.
The more brute-force solution to the inline passthrough approach is to use the pass:c[] macro, which is a more verbose (and
flexible) version of the plus formatting marks.
The `class`’ static methods make it easy to operate on files and directories.
ASCIIDOC
The __kernel qualifier can be used with the __attribute__ keyword...
#`CB###2`# and #`CB###3`#
:dbl_: __
:3H: ###
The {dbl_}kernel qualifier can be used with the {dbl_}attribute{dbl_} keyword...
#`CB{3H}2`# and #`CB{3H}3`#
The +__kernel+ qualifier can be used with the +__attribute__+ keyword...
#`+CB###2+`# and #`+CB###3+`#
12/20/2018 Asciidoctor User Manual
https://asciidoctor.org/docs/user-manual/ 30/315
As you can see, however, the macro is not quite as elegant or concise. In case you’re wondering, the c in the target slot of the
pass:c[] macro applies output escaping for HTML. Though not always required, it’s best to include this flag so you don’t forget
to when it is needed.
Backslashes for escaping aren’t very reliable in AsciiDoc. While they can be used, they have to be placed so strategically that they
are rather finicky.
The pass:c[__kernel] qualifier can be used with the pass:c[__attribute__] keyword...
#`pass:c[CB###2]`# and #`pass:c[CB###3]`#
12/20/2018 Asciidoctor User Manual
https://asciidoctor.org/docs/user-manual/ 31/315
10. Attributes
Attributes are one of the features that sets Asciidoctor apart from other lightweight markup languages. Attributes can activate
features (behaviors, styles, integrations, etc) or hold replacement (i.e., variable) content.
In Asciidoctor, attributes are classified as:
Environment attributes
Built-in attributes
Predefined attributes
User-defined attributes
API and Command Line Attributes
Element Attributes
10.1. Attribute Restrictions
All attributes have a name and a value (though the value may be implicit).
The attribute name:
must be at least one character long,
must begin with a word character (A-Z, a-z, 0-9 or _) and
must only contain word characters and hyphens.
In other words, the name cannot contain dots or spaces.
Although uppercase characters are permitted in an attribute entry (the place where an attribute is defined), the attribute name is
converted to lowercase before being stored. The attribute name in an attribute reference is also converted to lowercase before the
attribute is resolved. For example, URI , Uri and uRI are all treated as uri . (See issue #509
(https://github.com/asciidoctor/asciidoctor/issues/509) for a proposed change to this restriction). A best practice is to only use lowercase
for letters in the name and avoid starting the name with a number.
The attribute value:
can be any inline content and
can only contain line breaks if an explicit line continuation is used.
Certain attributes have a restricted range of allowable values. See the entries in the Catalog of Document Attributes for details.
10.2. Attribute Assignment Precedence
The attribute assignment precedence, listed from highest to lowest, is as follows:
An attribute defined using the API or CLI
An attribute defined in the document
The default value of the attribute, if applicable
Let’s use the imagesdir attribute to show how precedence works.
The default value for the imagesdir attribute is an empty string. Therefore, if the imagesdir attribute is not assigned a value
(either in the document, API, or CLI), the processor will assign it the default value of empty string. If the imagesdir attribute is
set in the document (meaning assigned a new value, such as images ), that value will override the default value. Finally, if a value
is assigned to the imagesdir attribute via the API or CLI, that value will override both the default value and the value assigned in
the document.
It’s possible to alter this order of precedence using a modifier, covered in the next section.
10.2.1. Altering the Attribute Assignment Precedence
12/20/2018 Asciidoctor User Manual
https://asciidoctor.org/docs/user-manual/ 32/315
You can allow the document to reassign an attribute that is defined via the API or CLI by adding the @ precedence modifier to the
end of the attribute value (or, since 1.5.7, the end of the attribute name). Adding this modifier lowers the precedence so that an
assignment in the document still wins out. We sometimes refer to this as “soft setting” the attribute. This feature can be useful for
assigning default values for attribute, but still letting the document control its own fate.
The @ modifier is removed before the assignment is made.
Here’s an example that shows how to set the imagesdir from the CLI with a lower precedence:
$ asciidoctor -a imagesdir=images@ doc.adoc
Since 1.5.7, you can place the modifier at the end of the attribute name:
$ asciidoctor -a imagesdir@=images doc.adoc
It’s now possible to override the value of the imagesdir attribute from within the document:
Let’s update the attribute assignment precedence list defined earlier to reflect this additional rule:
An attribute passed to the API or CLI
An attribute defined in the document
An attribute passed to the API or CLI whose value (or, since 1.5.7, name) ends in @
The default value of the attribute, if applicable
Regardless of whether the precedence modifier is applied, an attribute assignment always overrides the default value.
10.3. Using Attributes: Set, Assign, and Reference
Before you can use an attribute in your document, it must be set. (Sometimes referred to as “toggling on” the attribute).
Some attributes are automatically set when Asciidoctor processes a document. You can also set (or override) an attribute for a
document by declaring an attribute entry. For example:
:sectnums:
Many attributes can be assigned a value at the same time:
:leveloffset: 3
The value may be empty, a string (of characters) or a number. A string value may include references to other attributes.
Attributes can be unset using the bang symbol ( !). The ! can be placed either before or after the attribute’s name.
For example, both:
:sectnums!:
and
:!sectnums:
mean unset the sectnums attribute. In this case, it tells Asciidoctor to not number the sections.
To soft unset an attribute from the CLI or API, you can use the following syntax:
= Document Title
:imagesdir: new/path/to/images
ASCIIDOC
12/20/2018 Asciidoctor User Manual
https://asciidoctor.org/docs/user-manual/ 33/315
!name=@
The leading ! unsets the attribute while the @ lowers the precedence of the assignment. This assignment is almost always used
to unset a default value while still allowing the document to assign a new one. One such example is sectids , which is enabled by
default. !sectids=@ switches the setting off.
An attribute reference is an inline element composed of the name of the attribute enclosed in curly brackets. For example:
The value of leveloffset is {leveloffset}.
The attribute reference is replaced by the attribute’s value when Asciidoctor processes the document. Referencing an attribute
that is not set is considered an error and is handled specially by the processor.
The following sections will show you how to use attributes on your whole document, individual blocks, and inline elements.
10.4. Setting Attributes on a Document
An attribute entry is the primary mechanism for defining a document attribute in an AsciiDoc document. You can think of an
attribute entry as a global variable assignment for AsciiDoc. The document attribute it creates becomes available from that point
forward in the document. Attribute entries are also frequently used to toggle features.
An attribute entry consists of two parts: an attribute name and an attribute value. The attribute name comes first. It must be at
the start of the line and must be enclosed in colons (e.g., :name: ). If present, the attribute value is offset from the name part by at
least one space (e.g., :name: value ). Be aware that substitutions automatically get applied to the value by default, as described in
Substitutions in an attribute entry.
Anatomy of an attribute entry
The attribute value is optional. A blank value is often used to set (i.e., activate) a boolean attribute (thus making a blank value
implicitly true).
Anatomy of an attribute entry to set a boolean attribute
An exclamation point ( !) before (or after) the attribute name unsets the attribute. In this case, the value is ignored.
Anatomy of an attribue entry to unset an attribute
Attribute entries have the following characteristics:
Attributes entries can:
be assigned to a document:
through the CLI or API
in the document’s header
in the document’s body
be unset (turned off) with a leading (or trailing) ! added to the name
have default values (in the case of a built-in attribute)
have alternate values (in the case of a built-in attribute)
span multiple, contiguous lines
include inline AsciiDoc content
Attribute entries can not:
override locked attributes assigned from the command line
include AsciiDoc block content (such as, bulleted lists or other types of whitespace-dependent markup)
:name: value
ASCIIDOC
:name:
ASCIIDOC
:!name:
ASCIIDOC
12/20/2018 Asciidoctor User Manual
https://asciidoctor.org/docs/user-manual/ 34/315
Attributes are typically defined in the document header, though they may also be defined in the body of the document. Once set,
an attribute (and its value) are available for use for the remainder of the document. Unless locked by the API, attributes may be
reassigned at any subsequent point in the document.
10.4.1. Attribute entry use cases
Attributes entries serve three main purposes:
1. Toggle or configure built-in features
2. Set built-in asset locations
3. Content reuse
Setting built-in attributes
Numerous attribute are reserved for special purposes. These built-in attributes can be used to toggle behavior, such as the table of
contents, or control the generated output, such as selecting or configuring a converter. Many built-in attributes only take effect
when defined in the document header.
For example, to enable the built-in table of contents, you can define (i.e., set) the toc attribute using an attribute entry in the
document header as follows:
When the value following an attribute is left empty, as it is in the example above, the default value will be assigned (if any). The
default value for toc is auto . Therefore, the table of contents will be placed in the default location (below the document’s title)
when the document is converted.
If you want the table of contents to be placed on the right side of the document, you must assign the attribute a new value.
The right value will override the default value of auto . The value assigned to an attribute in the document header replaces the
intrinsic value (assuming the attribute is not locked).
Setting asset locations
You can also use attributes to set the base path to images (default: empty), icons (default: ./images/icons ), and stylesheets
(default: ./stylesheets ).
Base asset path configuration example
Content reuse
If you’re familiar with writing in XML, you might recognize a document attribute as a user-defined entity. When you find yourself
typing the same text repeatedly, or text that often needs to be updated, consider assigning it to a document attribute and use that
instead.
A prime use case for attribute entries is to promote frequently used URLs and links to the top of the document.
URL attribute entry
Now you can refer to this attribute entry anywhere in the document (where attribute substitution is performed) by surrounding
its name in curly braces.
Instead of having to type the URL out longhand in the link macro, as follows:
A case for using an attribute reference
:toc:
ASCIIDOC
:toc: right
ASCIIDOC
:imagesdir: ./images
:iconsdir: ./icons
:stylesdir: ./styles
ASCIIDOC
:url-fedpkg: https://apps.fedoraproject.org/packages/rubygem-asciidoctor
ASCIIDOC
Did you know there's an https://apps.fedoraproject.org/packages/rubygem-asciidoctor[Asciidoctor package for Fedora]?
ASCIIDOC
12/20/2018 Asciidoctor User Manual
https://asciidoctor.org/docs/user-manual/ 35/315
We can replace the target side of the link macro with a reference to our attribute.
url-fedpkg attribute usage example
To save even more typing, you can store the whole link in an attribute value.
Link attribute entry
Now you insert this link anywhere in the document using an attribute reference.
link-fedpkg attribute usage example
Note that the link substitution occurs after the attribute reference is resolved. This works thanks to the default order of
substitutions on a paragraph. If you want the link macro to be resolved eagerly at the time the attribute is assigned, you need to
enclose it in a pass macro.
Link attribute entry resolved eagerly
Now you can use this link in a section title (where the order of substitutions is different). Let’s dive deeper into which
substitutions are applied to an attribute entry and how to alter them.
10.4.2. Substitutions in an attribute entry
The AsciiDoc processor automatically applies substitutions from the header substitution group to the value of an attribute entry
prior to the assignment (regardless of where the attribute entry is declared in the document). The header substitution group
replaces special characters and attribute references. This is the same group that gets applied to metadata lines (author and
revision information) in the document header. To learn about how these substitutions work, refer to the Substitutions chapter.
10.4.3. Altering attribute entry substitutions
If you want the value of an attribute entry to be used as is (not subject to substitutions), or you want to alter the substitutions that
are applied, you can enclose the value in the inline pass macro (i.e., pass:[] ). The inline pass macro accepts a list of zero or
more substitutions in the target slot, which can be used to control which substitutions are applied to the value. If no substitutions
are specified, no substitutions will be applied.
In order for the inline macro to work in this context, it must completely surround the attribute value. If it’s used anywhere else in
the value, it is ignored.
Here’s how to prevent substitutions from being applied to the value of an attribute entry:
This might be useful if you’re referencing the attribute in a place that depends on the unaltered text, such as the value of the
cols attribute on a table.
Here’s how to apply the quotes substitution to the value of an attribute entry:
Internally, the value is stored as MyApp<sup>2</sup> . You can inspect the value stored in an attribute using this trick:
You can also specify the substitution using the single-character alias, q.
Did you know there's an {url-fedpkg}[Asciidoctor package for Fedora]?
ASCIIDOC
:link-fedpkg: https://apps.fedoraproject.org/packages/rubygem-asciidoctor[Asciidoctor package for Fedora]
ASCIIDOC
Did you know there's an {link-fedpkg}?
ASCIIDOC
:link-fedpkg: pass:m[https://apps.fedoraproject.org/packages/rubygem-asciidoctor[Asciidoctor package for Fedora]]
ASCIIDOC
:cols: pass:[.>2,.>4]
ASCIIDOC
:app-name: pass:quotes[MyApp^2^]
ASCIIDOC
[subs=attributes+]
----
{app-name}
----
12/20/2018 Asciidoctor User Manual
https://asciidoctor.org/docs/user-manual/ 36/315
The inline pass macro kind of works like an attribute value preprocessor. If the processor detects that an inline pass macro
completely surrounds the attribute value, it:
1. reads the list of substitutions from the target slot of the macro
2. unwraps the value from the macro
3. applies the substitutions to the value
If the macro is absent, the value is processed with the header substitution group.
You can also change the substitutions that are applied to an attribute at the time it is resolved. This is done by manipulating the
substitutions applied to the text where it is referenced. For example, here’s how we could get the processor to apply quote
substitutions to the value of an attribute:
Notice that we’ve swapped the order of the attributes and quotes substitutions. This strategy is akin to postprocessing the
attribute value.
10.4.4. Splitting attribute values over multiple lines
When an attribute value is very long, it’s possible to split it (i.e., soft-wrap) across multiple lines.
Let’s assume we are working with the following attribute entry:
A long, single-line attribute
You can split the value over multiple lines to make it more readable by inserting a space followed by a backslash (i.e., \) at the
end of each continuing line.
A long, multiline attribute (soft wrapped)
The backslash and the newline that follows will be removed from the attribute value when the attribute entry is parsed, making
this second example effectively the same as the first. The space before the backslash is preserved, so you have to use this
technique at a natural break point in the content.
You can force an attribute value to hard wrap by adding a plus surrounded by spaces before the backslash.
An attribute value with hard line breaks
This syntax ensures that the newlines are preserved in the output document as hard line breaks.
10.4.5. Attribute limitations
Attributes let you do a surprising amount of formatting for what is fundamentally a text replacement tool.
It may be tempting to try and extend attributes to be used for complex replaceable markup.
Supported
Basic in-line AsciiDoc markup is permitted in attribute values, such as:
:app-name: pass:q[MyApp^2^]
ASCIIDOC
:app-name: MyApp^2^
[subs="specialchars,attributes,quotes,replacements,macros,post_replacements"]
The application is called {app-name}.
ASCIIDOC
:long-value: If you have a very long line of text that you need to substitute regularly in a document, you may find it easi
ASCIIDOC
:long-value: If you have a very long line of text \
that you need to substitute regularly in a document, \
you may find it easier to split it neatly in the header \
so it remains readable to folks reading your docs code.
ASCIIDOC
:haiku: Write your docs in text, + \
AsciiDoc makes it easy, + \
Now get back to work!
ASCIIDOC
12/20/2018 Asciidoctor User Manual
https://asciidoctor.org/docs/user-manual/ 37/315
attribute references
text formatting (usually wrapped in a pass macro)
inline macros (usually wrapped in a pass macro)
Unsupported
Complex AsciiDoc markup is not permitted in attribute values, such as:
lists
multiple paragraphs
other whitespace-dependent markup types
10.5. Setting Attributes on an Element
An attribute list can apply to blocks, inline quotes text, and macros. The attributes and their values contained in the list will take
precedence over attribute entries.
Anatomy of an attribute list
[positional_attribute1,positional_attribute2,name_attribute1="value"]
Attribute lists:
1. apply to blocks as well as macros and inline quoted text
2. can contain positional and named attributes
3. take precedence over global attributes
10.5.1. Positional Attribute
Positional attributes are un-named values at the start of the attribute list. The attribute that they are assigned to depends on the
type of the element:
icon: (1) size
image: and image:: (1) alt text, (2) width, (3) height
Delimited blocks: (1) block name (aka style)
Other inline quoted text: (1) role
For example, the following two image macros are equivalent.
The second macro is just a duplicate of the first macro written out longhand.
10.5.2. Named Attribute
A named attribute consists of a name and a value separated by an = character (e.g., name=value ).
If the value contains a space, comma, or quote character, it must be enclosed in double or single quotes (e.g., name="value with
space" ). In all other cases, the surrounding quotes are optional. If present, the enclosing quotes are dropped from the parsed
value.
To undefine a named attribute, set the value to None (case sensitive).
10.5.3. Attribute List Substitutions
Attribute references are expanded before the block attribute list is processed. Therefore, it’s not necessary to force substitutions to
be applied if you simply want to use a document attribute reference in a block attributes.
If the attribute name (for a positional attribute) or value (for a named attribute) is enclosed in single quotes (e.g.,
title='Processed by https://asciidoctor.org[Asciidoctor]' ), normal substitutions are applied to the value at
assignment time (with some exceptions). No special processing is performed if the value is not enclosed in quotes or is enclosed in
double quotes.
image::sunset.jpg[Sunset,300,400]
image::sunset.jpg[alt=Sunset,width=300,height=400]
ASCIIDOC
12/20/2018 Asciidoctor User Manual
https://asciidoctor.org/docs/user-manual/ 38/315
If the attribute value contains the same quote character being used to enclose the value, escape the quote character in the value
by prefixing it with a backslash (e.g., title="\"Dark Horse\" is a song by George Harrison" ).
10.5.4. Style
The style attribute is the first positional attribute in an attribute list. It specifies a predefined set of characteristics that should
apply to a block element or macro.
For example, a paragraph block can be assigned one of the following built-in style attributes:
normal (default, so does not need to be set)
literal
verse
quote
listing
TIP
NOTE
IMPORTANT
WARNING
CAUTION
abstract
partintro
comment
example
sidebar
source
10.5.5. Id
The id attribute specifies a unique name for an element. That name can only be used once in a document.
An id has two purposes:
1. to provide an internal link or cross reference anchor for the element
2. to reference a style or script used by the output processor
Block Assignment
In an attribute list, there are two ways to assign an id attribute to a block element.
1. Prefixing the name with a hash ( #).
2. Specifying the name with id=<name> .
Let’s say you want to create a blockquote from an open block and assign it an ID and role. You add quote (the block style) in
front of the # (the ID) in the first attribute position, as this example shows:
The order of ID and role values in the shorthand syntax does not matter.
Inline Assignment
[#goals]
* Goal 1
* Goal 2
ASCIIDOC
[quote#roads, Dr. Emmett Brown]
____
Roads? Where we're going, we don't need roads.
____
ASCIIDOC
12/20/2018 Asciidoctor User Manual
https://asciidoctor.org/docs/user-manual/ 39/315
The id ( #) shorthand can be used on inline quoted text.
Quoted text block with id assignment using Asciidoctor shorthand
10.5.6. Role
An element can be assigned numerous roles.
Block Assignment
In an attribute list, there are two ways to assign a role attribute to a block element.
1. Prefixing the name with a dot ( .).
2. Specifying the name with role=<name> .
To specify multiple roles using the shorthand syntax, separate them by dots.
Inline Assignment
The role ( .) shorthand can be used on inline quoted text.
Quoted text with role assignments using traditional AsciiDoc syntax
Quoted text with role assignments using Asciidoctor shorthand
The attribute list preceding formatted text can be escaped using a backslash (e.g., \[role]*bold* ). In this
case, the text will still be formatted, but the attribute list will be unescaped and output verbatim.
Role-playing for text enclosed in backticks
To align with other formatted (i.e., quoted) text in AsciiDoc, roles can now be assigned to text enclosed in backticks.
Given:
the following HTML is produced:
Using the shorthand notation, an id (i.e., anchor) can also be specified:
[#free_the_world]*free the world*
[.summary]
* Review 1
* Review 2
ASCIIDOC
[role="summary"]
* Review 1
* Review 2
ASCIIDOC
[.summary.incremental]
* Review 1
* Review 2
ASCIIDOC
[role="summary,incremental"]
* Review 1
* Review 2
ASCIIDOC
[big goal]*free the world*
ASCIIDOC
[.big.goal]*free the world*
ASCIIDOC
[.rolename]`monospace text`
ASCIIDOC
<code class="rolename">monospace text</code>
HTML
12/20/2018 Asciidoctor User Manual
https://asciidoctor.org/docs/user-manual/ 40/315
which produces:
10.5.7. Options
The options attribute is a versatile named attribute that can contain a comma separated list of values.
It can also be defined globally with an attribute entry.
Block Assignment
In an attribute list, there are three ways to assign an options attribute to a block element.
1. Prefixing the value with a percent sign ( %).
2. Specifying the value with opts=<name>
3. Specifying the value with options=<name> .
Consider a table block with the three option values header , footer , and autowidth .
Here’s how the options are assigned to the table using the shorthand notation ( %).
Shorthand Asciidoctor syntax
Here’s how the options are assigned to the table using options .
Traditional AsciiDoc syntax
Let’s consider the options when combined with other attributes.
Shorthand Asciidoctor block syntax
Traditional AsciiDoc block syntax
10.6. Assigning Document Attributes Inline
Document attributes can be assigned using the following syntax:
{set:<attrname>[!][:<value>]}
For example:
is effectively the same as:
[#idname.rolename]`monospace text`
ASCIIDOC
<a id="idname"></a><code class="rolename">monospace text</code>
HTML
[%header%footer%autowidth]
|===
| Cell A | Cell B
|===
ASCIIDOC
[options="header,footer,autowidth"]
|===
| Cell A | Cell B
|===
ASCIIDOC
[horizontal.properties%step]
property 1:: does stuff
property 2:: does different stuff
ASCIIDOC
[horizontal, role="properties", options="step"]
property 1:: does stuff
property 2:: does different stuff
ASCIIDOC
{set:sourcedir:src/main/java}
ASCIIDOC
12/20/2018 Asciidoctor User Manual
https://asciidoctor.org/docs/user-manual/ 41/315
:sourcedir: src/main/java
This is important for being able to assign document attributes in places where attribute entry lines are not normally processed,
such as in a table cell.
10.6.1. Handle Missing or Undened Attributes
As a result of a misconfigured document or inadvertent substitution, an attribute reference may point to a non-existent attribute
(e.g., {does-not-exist} ). It could be that the attribute reference itself undefines the attribute (e.g., {set:attribute-no-
more!} ). You’ll want to think about how you want the processor to handle these situations and configure it accordingly.
AsciiDoc Python simply drops any line that contains a reference to a missing attribute. This “feature” was designed with AsciiDoc
Python’s own template language in mind, which is also based on the AsciiDoc syntax. However, this behavior was never really
intended for use in regular AsciiDoc documents. The behavior is frustrating for the author, editor, or reader because it’s not
immediately obvious when a line goes missing. Discovering the absence of certain line often requires a painstaking read-through
of the document or section, if it’s even noticed at all.
Asciidoctor offers two attributes to alleviate this inconvenience: attribute-missing and attribute-undefined .
Missing attribute
The attribute-missing attribute controls how missing (i.e., unresolved) references are handled. By default, missing references
are left intact so the integrity of the document is preserved ( skip ). However, that mode doesn’t help the author track down these
references.
To help with that task, Asciidoctor can be configured to warn when a missing reference is encountered ( warn ). Asciidoctor can
also emulate the behavior of AsciiDoc Python ( drop-line ), or offer something in between ( drop ).
Here are the four possible values of the attribute-missing attribute:
skip
leaves the reference intact without issuing a warning (default setting)
drop
drops the reference, but not the whole line
drop-line
drops the whole line on which the reference occurs (matches behavior of AsciiDoc Python)
warn
leaves the reference intact, but also prints a warning about the missing attribute (recommended)
Consider the following line of AsciiDoc:
Here’s how the line is handled in each case, assuming the name attribute is not defined:
skip Hello, {name}!
drop Hello, !
drop-line
warn
If you want the processor to fail when the document contains a missing attribute, set the attribute-missing attribute to warn
and pass the --failure-level=WARN option to the processor.
$ asciidoctor -a attribute-missing=warn --failure-level=WARN doc.adoc
Hello, {name}!
ASCIIDOC
asciidoctor: WARNING: skipping reference to missing attribute: name
12/20/2018 Asciidoctor User Manual
https://asciidoctor.org/docs/user-manual/ 42/315
When using the API, you can consult the logger for the max severity of all messages reported or look for specific messages in the
stack.
There are several exceptions when the attribute-missing attribute is not strictly honored. One of those cases is the include
directive. If a missing attribute is found in the target of an include directive, the processor will issue a warning about the missing
attribute and drop the include directive. This behavior was chosen because showing the unresolved include directive to the
reader is messy.
Another case is the block image macro. If a missing attribute is found in the target of an include directive, the processor will issue
a warning about the missing attribute, but leave the image macro unresolved so as to show it as alt text.
A missing attribute reference can safely be used in an ifeval clause without any side effects (i.e., drop ) since often the purpose of
that statement is to determine whether an attribute resolves to a value.
Undened attribute
The attribute attribute-undefined controls how expressions that undefine an attribute are handled. By default, the line is dropped
since the expression is a statement, not content.
This attribute has two possible values:
drop
substitute the expression with an empty string after processing it
drop-line
drop the line that contains this expression (default setting; matches behavior of AsciiDoc Python)
The option skip doesn’t make sense here since the statement is not intended to produce content.
Consider the following declaration:
Depending on whether attribute-undefined is drop or drop-line , either the statement or the line that contains it will be
discarded. It’s reasonable to stick with the compliant behavior, drop-line, in this case.
We recommend putting any statement that undefines an attribute on a line by itself.
{set:name!}
ASCIIDOC
12/20/2018 Asciidoctor User Manual
https://asciidoctor.org/docs/user-manual/ 44/315
11. Text Editor
Since AsciiDoc syntax is just plain text , you can write an AsciiDoc document using any text editor. You don’t need complex
word processing programs like Microsoft Word, OpenOffice Writer or Google Docs. In fact, you shouldn’t use these programs
because they add cruft to your document that you can’t see that makes conversion tedious.
While it’s true any text editor will do, an editor that supports syntax highlighting for AsciiDoc may be more helpful. The color
brings contrast to the text, making it easier to read. The highlighting also confirms when you’ve entered the correct syntax for an
inline or block element.
The most popular application for editing plain text on macOS is TextMate. A similar choice on Linux is GEdit. On Windows, stay
away from Notepad and Wordpad because they produce plain text which is not cross-platform friendly. Opt instead for a
competent text editor like Notepad++. If you’re a programmer (or a writer with an inner geek), you’ll likely prefer Vim, Emacs, or
Sublime Text, all of which are available cross-platform. For those that work on multiple platforms, Atom is a consistent choice
with many add-on packages for working with AsciiDoc files. The key feature all these editors share is syntax highlighting for
AsciiDoc (http://asciidoc.org/#_editor_support).
Previewing the output of the document while editing can be helpful. To learn how to setup instant preview,
check out the Editing AsciiDoc with Live Preview tutorial.
12/20/2018 Asciidoctor User Manual
https://asciidoctor.org/docs/user-manual/ 45/315
12. Document Types
Article (keyword: article )
The default doctype. In DocBook, includes the appendix, abstract, bibliography, glossary, and index sections.
Book (keyword: book )
Builds on the article doctype with the additional ability to use a top-level title as part titles, includes the appendix, dedication,
preface, bibliography, glossary, index, and colophon. There’s also the concept of a multi-part book, but the distinction from a
regular book is determined by the content. A book only has chapters and special sections, whereas a multi-part book is divided
by parts that each contain one or more chapters or special sections.
Man page (keyword: manpage )
Used for producing a roff or HTML-formatted man page (https://en.wikipedia.org/wiki/Man_page) (short for manual page) for Unix
and Unix-like operating systems. This doctype instructs the parser to recognize a special document header and section naming
conventions for organizing the AsciiDoc content as a manual page. Refer to Man Pages for details on how to compose AsciiDoc
for this purpose.
Inline (keyword: inline )
Asciidoctor only. There may be cases when you only want to apply inline AsciiDoc formatting to input text without wrapping it
in a block element. For example, in the Asciidoclet project (AsciiDoc in Javadoc), only the inline formatting is needed for the
text in Javadoc tags.
12.1. Inline doctype
The rules for the inline doctype are as follows:
Only a single paragraph is read from the AsciiDoc source.
Inline formatting is applied.
The output is not wrapped in the normal paragraph tags.
Given the following input:
Processing it with the options doctype=inline and backend=html5 produces:
The inline doctype allows the Asciidoctor processor to cover the full range of applications, from unstructured (inline) text to full,
standalone documents!
http://asciidoc.org[AsciiDoc] is a _lightweight_ markup language...
ASCIIDOC
<a href="http://asciidoc.org">AsciiDoc</a> is a <em>lightweight</em> markup language…
HTML
12/20/2018 Asciidoctor User Manual
https://asciidoctor.org/docs/user-manual/ 47/315
14. Header
The document header is a special set of contiguous lines at the start of the document that encapsulates the document title, author
and revision information, and document-wide attributes (either built-in or user-defined).
The header typically begins with a document title, though this element is optional. If a document title is specified, it may be
immediately followed by two optional lines of text to set the author and revision information. Finally, the header may declare
document-wide attributes (built-in or user-defined) using attribute entries. Attribute entries can be placed anywhere in the
header, including above the document title, though the preferred placement is below the document title, if present. Since the
document title is optional, it’s possible for the header to only consist of attribute entries.
The first block content (e.g., a paragraph) or a blank line in the document marks the end of the header. Any attributes defined
below the document header will not be scoped to the document.
The document header must not contain any blank lines or block content!
Line comments may be used in the header, but only if those lines are directly adjacent to other lines in the header.
The header is optional when the doctype is article or book . However, a header is required when the document type is
manpage . The requirements for a manual page (man page) are described in the man pages section.
The header (document title, author, and revision information) is included by default when converting to a standalone document.
If you do not want the header of a document to be displayed, set the noheader attribute in the document’s header (or set the
attribute using the API or CLI).
Front matter
Many static site generators, such as Jekyll and Middleman, rely on front matter added to the top of the document to
determine how to convert the content. Asciidoctor has a number of attributes available to correctly handle front matter. See
the static website generators section to learn how Asciidoctor integrates with static website generators.
Now let’s explore the document title in detail.
14.1. Document Title
The document title resembles a level-0 section title, which is written using a single equal sign followed by at least one space (i.e., =
), then the text of the title. The document title must be the first level-0 section title in the document. The only content permitted
above the document title are blank lines, comment lines and document-wide attribute entries.
Here’s an example of a document title followed by a short paragraph. Notice the blank line between the document title and the
first line of prose. That blank line is what offsets the document header from the body.
Document with a title
Result: Rendered document title
= The Dangerous and Thrilling Documentation Chronicles
This journey begins on a bleary Monday morning.
ASCIIDOC
12/20/2018 Asciidoctor User Manual
https://asciidoctor.org/docs/user-manual/ 48/315
When the doctype is article or manpage , the document can only have one level-0 section title. In contrast, the book
document type permits multiple level-0 section titles. When the doctype is book , the first level-0 section title, located in the
header, is the document’s title and subsequent level-0 section titles are the part titles.
14.1.1. doctitle attribute
A document’s title is assigned to the built-in doctitle attribute. The doctitle attribute can be referenced anywhere in a
document and resolves to the document’s title when displayed.
Referencing the doctitle attribute
Result: doctitle output
The doctitle attribute can also be used to set the document title instead of using a level-0 section title. However, the attribute
must still be set in the document header.
14.1.2. Document subtitle
Asciidoctor recognizes a subtitle in the primary level-0 heading. If the primary title contains at least one colon followed by a space
(i.e, : ), Asciidoctor treats the text after the final colon-space sequence as the subtitle.
The subtitle is not distinguished from the main title in the html5 output. It’s only distinguished from the main
title when using the docbook , epub3 , and pdf converters.
Document with a subtitle
In this example, the following is true:
Main title The Dangerous and Thrilling Documentation Chronicles
Subtitle A Tale of Caffeine and Words
Document with a subtitle and multiple colons
In this example, the following is true:
Main title A Cautionary Tale: The Dangerous and Thrilling Documentation Chronicles
Subtitle A Tale of Caffeine and Words
Instead of using a colon followed by a space as the separator characters between the main title and the subtitle, you can specify a
custom separator using the title-separator attribute.
= The Dangerous and Thrilling Documentation Chronicles
{doctitle} begins on a bleary Monday morning.
ASCIIDOC
= The Dangerous and Thrilling Documentation Chronicles: A Tale of Caffeine and Words
It began on a bleary Monday morning.
ASCIIDOC
= A Cautionary Tale: The Dangerous and Thrilling Documentation Chronicles: A Tale of Caffeine and Words
It began on a bleary Monday morning.
ASCIIDOC
12/20/2018 Asciidoctor User Manual
https://asciidoctor.org/docs/user-manual/ 49/315
Document with a subtitle using a custom separator
Note that a space is always appended to the value of the title-separator (making the default value of the title-separator
effectively a single colon).
Asciidoctor also provides an API for extracting the title and subtitle. See the API docs for the Document::Title
(https://www.rubydoc.info/gems/asciidoctor/Asciidoctor/Document/Title) for more information. Support for subtitle functionality for other
sections is being considered. Refer to issue #1493 (https://github.com/asciidoctor/asciidoctor/issues/1493).
14.1.3. Document title visibility
You can control whether or not the document title appears in the converted document using the showtitle attribute.
When converting a standalone document, the document title is shown by default. If you don’t want the title to be shown in this
case, unset the showtitle attribute using showtitle! in the document header or via the CLI or API.
When converted to an embeddable document, the document title is not shown by default. If you want the title to be shown, set the
showtitle attribute in the document header or via the CLI or API. The author and revision information is not shown below the
document title in the embeddable version of the document like it is in the standalone document, even when the showtitle
attribute is set.
Let’s look at how to add additional metadata to the document header, including an author and her email address.
14.2. Author and Email
The author of a document is listed on the line beneath the document’s title. An optional email address or URL can follow an
author’s name inside angle brackets.
Let’s add an author with her email address to the document below.
Result: Rendered author and email information displayed on the byline and referenced in the document’s body
:title-separator: {sp}|
= The Dangerous and Thrilling Documentation Chronicles | A Tale of Caffeine and Words
It began on a bleary Monday morning.
ASCIIDOC
= The Dangerous and Thrilling Documentation Chronicles
Kismet Rainbow Chameleon <kismet@asciidoctor.org>
This journey begins...
== About the Author
You can contact {author} at {email}.
{firstname} loves to hear from other chroniclers.
P.S. And yes, my middle name really is {middlename}.
What else would you expect from a member of the Rocky Mountain {lastname} Clan?
{authorinitials}
ASCIIDOC
12/20/2018 Asciidoctor User Manual
https://asciidoctor.org/docs/user-manual/ 50/315
As you can see in the example above, Asciidoctor uses the author’s name and email to assign values to a number of built-in
attributes that can be used throughout the document’s body. These attributes include:
author
The author’s full name, which includes all of the characters or words prior to a semicolon ( ;), angle bracket ( <) or the end of
the line.
firstname
The first word in the author attribute.
lastname
The last word in the author attribute.
middlename
If a firstname and lastname are present, any remaining words or characters found between these attributes are assigned to the
middlename attribute.
authorinitials
The first character of the firstname, middlename, and lastname attributes.
email
An email address, delimited by angle brackets ( <> ).
If one or more of the author’s names consists of more than one word, use an underscore ( _) between the words you want to
adjoin. For example, the author of the following document has a compound last name.
Result: Rendered author information when author has a compound name
= The Unbearable Lightness of Nomenclature
Jan Hendrik van_den_Berg
My first name is {firstname}.
My middle name is {middlename}.
My last name is {lastname}.
My initials are {authorinitials}.
ASCIIDOC
12/20/2018 Asciidoctor User Manual
https://asciidoctor.org/docs/user-manual/ 51/315
Alternatively, the author and email attributes can be set explicitly in the header.
Result: Rendered author information when author and email attributes are explicitly set
The html5 and docbook converters can convert documents with multiple authors. Multiple authors and their emails are
separated by semicolons ( ;) when they’re listed on the same line.
= The Dangerous and Thrilling Documentation Chronicles
:author: Kismet Rainbow Chameleon
:email: kismet@asciidoctor.org
This journey begins...
== About the Author
You can contact {author} at {email}.
{firstname} loves to hear from other chroniclers.
P.S. And yes, my middle name really is {middlename}.
What else would you expect from a member of the Rocky Mountain {lastname} Clan?
{authorinitials}
ASCIIDOC
12/20/2018 Asciidoctor User Manual
https://asciidoctor.org/docs/user-manual/ 52/315
1To reference the additional authors in the document body, the author attributes are appended with an underscore ( _)
followed by the position of the author in the author information list (i.e. Lazarus het Draeke is the second author in the
list so his author attributes are appended with a 2).
Result: Rendered author information when document has multiple authors
14.2.1. Attribute references in the author line
The implicit author line was not intended to support arbitrary placement of attribute references. While attribute references are
replaced in the author line (as part of the header substitution group), they aren’t substituted until after the line is parsed. This
ordering can sometimes produce undesirable or surprising results. It’s best to use the author line strictly as a shorthand for
defining a fixed author and email.
If you do need to use attribute references in the author or email value, you should revert to defining the attributes explicitly using
attribute entries.
Using attribute references to set author and email
Just remember that the author line is for static text. Once you graduate beyond static text, you should switch to using attribute
entries to define the built-in author attributes, which will give you much more power.
= The Dangerous and Thrilling Documentation Chronicles
Kismet Rainbow Chameleon <kismet@asciidoctor.org>; Lazarus het_Draeke <lazarus@asciidoctor.org>
This journey begins...
== About the Authors
You can contact {author} at {email}.
{firstname} loves to hear from other chroniclers.
{author_2} specializes in burning down automation obstacles.
Email {lastname_2} at {email_2}.
Until our next adventure!
{authorinitials} & {authorinitials_2}
ASCIIDOC
1
= Document Title
:author_name: ACME Industries
:author_email: info@acme.com
:author: {author_name}
:email: {author_email}
ASCIIDOC
12/20/2018 Asciidoctor User Manual
https://asciidoctor.org/docs/user-manual/ 53/315
14.3. Revision Number, Date and Remark
The revision information is read from the third (non-attribute) line of the header, beneath the author information line. A
document’s revision information has slots for three implicit attributes.
revnumber The document’s version number. In order to be recognized, the version number must contain at least one
numeric character. Any letters or symbols preceding the numeric character are ignored. If the implicit
revnumber is on a line by itself, it must begin with the “v” character (e.g., v1.0 ) or be followed by a comma
(e.g., 1.0, ) If the implicit revdate is present, it must be separated from the revnumber by a comma (e.g.,
2020-10-10, v78.1 ).
revdate The date the document version was completed. When the revnumber or revremark attributes are set, but
revdate is not, then revdate will be assigned the docdate value.
revremark Information about this version of the document.
Here’s an example of a revision line.
1revnumber and revdate must be separated by a comma ( ,).
2revdate can contain words, letters, numbers, and symbols.
3The revremark attribute must be preceded by a colon ( :), regardless of whether revnumber or revdate are set.
Result: Rendered revision information displayed on the byline and referenced in the document’s body
The revnumber in the byline is prefixed by the word Version; however, when referenced in the body of the document, only the
numerical value is displayed. The version-label attribute controls the version number label in the byline. The revision
information attributes can also be explicitly set in the header.
= The Dangerous and Thrilling Documentation Chronicles
Kismet Chameleon <kismet@asciidoctor.org>
v1.0, October 2, 2013: First incarnation
This journey begins...
== Colophon
Version: {revnumber}
Version Date: {revdate}
Version Notes: {revremark}
ASCIIDOC
123
12/20/2018 Asciidoctor User Manual
https://asciidoctor.org/docs/user-manual/ 54/315
1When explicitly set, any characters preceding the version number are not dropped.
2The revremark can contain attribute references.
3The version-label attribute is unset so that the word Version does not precede the revnumber in the byline.
Result: Rendered revision information when revision attributes are explicitly set
In the converted document, notice that the V preceding the revnumber is capitalized in the byline but not when the attribute is
referenced in the body of the document.
Revision extraction information and an extraction example are pending.
14.4. Subtitle Partitioning
By default, the document title is separated into a main title and subtitle using the industry standard, a colon followed by a space.
As of Asciidoctor 1.5.2, subtitle partitioning is not implemented in the HTML 5 backend.
A document title that contains a subtitle
The separator is searched from the end of the text. Therefore, only the last occurrence of the separator is used for partitioning the
title.
A document title that contains a subtitle and more than one separator
= The Dangerous and Thrilling Documentation Chronicles
Kismet Chameleon <kismet@asciidoctor.org>
:revnumber: 1.0
:revdate: 10-02-2013
:revremark: The first incarnation of {doctitle}
:version-label!:
This journey begins...
== Colophon
Version: {revnumber}
Version Date: {revdate}
Version Notes: {revremark}
ASCIIDOC
1
2
3
= Main Title: Subtitle
ASCIIDOC
= Main Title: Main Title Continued: Subtitle
ASCIIDOC
12/20/2018 Asciidoctor User Manual
https://asciidoctor.org/docs/user-manual/ 55/315
You can modify the title separator by specifying the separator block attribute explicitly above the document title (since
Asciidoctor 1.5.3). Note that a space will automatically be appended to the separator value.
A document title with an explicit title separator
You can also set the separator using a document attribute, either in the document:
A document title with an explicit title separator
or from the API or CLI (shown here):
$ asciidoctor -a title-separator=:: document.adoc
You can partition the title from the API when calling the doctitle method on Document:
Retrieving a partitioned document title
You can partition the title in an arbitrary way by passing the separator as a value to the partition option. In this case, the partition
option both activates subtitle partitioning and passes in a custom separator.
Retrieving a partitioned document title with a custom separator
14.5. Metadata
Document metadata, such as a description of the document, keywords, and the title, can be assigned to attributes in the header.
When converted to HTML, the values of these attributes will correspond to tags contained in the <head> section of an HTML
document.
14.5.1. Description
You can include a description of the document using the description attribute.
1If the document’s description is long, you can break the attribute’s value across several lines by ending each line with a
backslash \ that is preceded by a space.
When converted to HTML, the document description value is assigned to the HTML <meta> tag.
HTML output
[separator=::]
= Main Title:: Subtitle
ASCIIDOC
= Main Title:: Subtitle
:title-separator: ::
ASCIIDOC
title_parts = document.doctitle partition: true
puts title_parts.title
puts title_parts.subtitle
RUBY
title_parts = document.doctitle partition: '::'
puts title_parts.title
puts title_parts.subtitle
RUBY
= The Dangerous and Thrilling Documentation Chronicles
Kismet Rainbow Chameleon <kismet@asciidoctor.org>; Lazarus het_Draeke <lazarus@asciidoctor.org>
:description: A story chronicling the inexplicable hazards and vicious beasts a \
documentation team must surmount and vanquish on their journey to finding an \
open source project's true power.
This journey begins on a bleary Monday morning.
ASCIIDOC
1
12/20/2018 Asciidoctor User Manual
https://asciidoctor.org/docs/user-manual/ 56/315
14.5.2. Keywords
The keywords attribute contains a list of comma separated values that are assigned to the HTML <meta> tag.
HTML output
14.5.3. Alternate Title
By default, Asciidoctor uses the text of the document title as the value of the HTML <title> tag. You can override this behavior
by setting the title attribute in the document header.
14.5.4. Custom Metadata, Styles and Functions
You can add content, such as custom metadata, stylesheet, and script information, to the header of the output document using
docinfo (“document information”) files. The docinfo file section details what these files can contain and how to use them.
14.6. Header Summary
Header attributes and values
Attribute Values Description Notes Converters
author Author’s full name all
authorinitials First character of each word in
the author attribute
all
description Text describing the document html
docinfo ,
docinfo1 ,
docinfo2
Adds content from a docinfo file
to header
html, docbook
doctitle Text entered
by user
Title of document Identical to the value returned by
Document#doctitle
all
email Email address all
firstname First word of author attribute all
<!DOCTYPE html>
<html lang="en">
<head>
<meta http-equiv="Content-Type" content="text/html; charset=UTF-8">
<meta name="generator" content="Asciidoctor 1.5.6.2">
<meta name="viewport" content="width=device-width, initial-scale=1.0">
<meta name="description" content="A story chronicling the inexplicable hazards and vicious beasts a documentation team
<title>The Dangerous and Thrilling Documentation Chronicles</title>
<style>
XML
= The Dangerous and Thrilling Documentation Chronicles
Kismet Rainbow Chameleon <kismet@asciidoctor.org>; Lazarus het_Draeke <lazarus@asciidoctor.org>
:keywords: documentation, team, obstacles, journey, victory
This journey begins on a bleary Monday morning.
ASCIIDOC
<!DOCTYPE html>
<html lang="en">
<head>
<meta http-equiv="Content-Type" content="text/html; charset=UTF-8">
<meta name="generator" content="Asciidoctor 1.5.6.1">
<meta name="viewport" content="width=device-width, initial-scale=1.0">
<meta name="keywords" content="documentation, team, obstacles, journey, victory">
<title>The Dangerous and Thrilling Documentation Chronicles</title>
<style>
XML
12/20/2018 Asciidoctor User Manual
https://asciidoctor.org/docs/user-manual/ 57/315
Attribute Values Description Notes Converters
keywords A list of comma-separated values
that describe the document
html
lastname Last word of author attribute all
middlename Middle word of author attribute all
no-header-
footer , -s
Generate an embeddable
document; exclude the document
frame
all
noheader Suppresses the output of the
header
all
nofooter Suppresses the output of the
footer
all
notitle Toggles the display of a
document’s title
all
revdate Date of document version all
revnumber Version number of the document all
revremark Version comments all
showtitle Toggles the display of an
embedded document’s title
all
title Alternative title of the document html
version-label Version, User
defined
The label preceding the
revnumber in a converted
document’s byline
html
12/20/2018 Asciidoctor User Manual
https://asciidoctor.org/docs/user-manual/ 58/315
15. Preamble
Content between the document header and the first section title is called the preamble. The preamble is optional.
Preamble
When using the default Asciidoctor stylesheet, the lead attribute is applied to the first paragraph of the preamble.
Result: Rendered preamble
= The Dangerous and Thrilling Documentation Chronicles
Kismet Chameleon
This journey begins on a bleary Monday morning.
Our intrepid team is in desperate need of double shot mochas, but the milk expired eight days ago.
A trip to the dairy was out of the question.
On Friday night, a mutant, script-injecting warlock had infected the Shetland cattle herd with a ravenous craving for tags
The security wolves were at a trust building retreat in Katchanga, and no one in the village could locate their defensive o
Weak daylight trickled across the stripped pasture, chased by distant bovine screams...
== Cavern Glow
The river rages through the cavern, rattling its content...
ASCIIDOC
12/20/2018 Asciidoctor User Manual
https://asciidoctor.org/docs/user-manual/ 59/315
16. Sections
Sections partition the document into a content hierarchy. In AsciiDoc, sections are defined using section titles.
A section title represents the heading for a section. Section title levels are specified by two to six equal signs. The number of equal
signs in front of the title represents the nesting level (using a 0-based index) of the section.
Section titles available in an article doctype
Render section titles
Document Title (Level 0)
Level 1 Section Title
Level 2 Section Title
Level 3 Section Title
Level 4 Section Title
Level 5 Section Title
Another Level 1 Section Title
In addition to the equals sign marker used for defining single-line section titles, Asciidoctor recognizes the hash
symbol ( #) from Markdown. That means the outline of a Markdown document will be converted just fine as
an AsciiDoc document.
Section levels must be nested logically. There are two rules you must follow:
1. A document can only have multiple level 0 sections if the doctype is set to book .
The first level 0 section is the document title; subsequent level 0 sections represent parts.
2. Section levels cannot be skipped when nesting sections (e.g., you can’t nest a level 5 section directly inside a level 3 section; an
intermediary level 4 section is required).
For example, the following syntax is illegal:
Content above the first section title is designated as the document’s preamble. Once the first section title is reached, content is
associated with the section it is nested in.
= Document Title (Level 0)
== Level 1 Section Title
=== Level 2 Section Title
==== Level 3 Section Title
===== Level 4 Section Title
====== Level 5 Section Title
== Another Level 1 Section Title
ASCIIDOC
= Document Title
= Illegal Level 0 Section (violates rule #1)
== First Section
==== Illegal Nested Section (violates rule #2)
ASCIIDOC
12/20/2018 Asciidoctor User Manual
https://asciidoctor.org/docs/user-manual/ 60/315
16.1. Titles as HTML Headings
When the document is converted to HTML 5 (using the built-in html5 backend), each section title becomes a heading element
where the heading level matches the number of equal signs. For example, a level 1 section ( == ) maps to an <h2> element.
16.2. Auto-generated IDs
If you don’t specify a custom ID for a section, the processor automatically generates an ID from the section’s title and assigns it to
the section by default.
The ID is derived from the section title as follows:
Inline formatting is applied (in title substitution order).
All characters are converted to lowercase.
The value of the idprefix attribute ( _ by default) is prepended.
Character references, HTML/XML tags, and invalid ID characters are removed.
Refer to the NT-Name (https://www.w3.org/TR/REC-xml/#NT-Name) section of the XML specification for a list of valid ID
characters.
Prior to 1.5.7, HTML/XML tags were not removed and character references and invalid ID characters were replaced with the
value of the idseparator attribute ( _ by default).
Spaces, hyphens, and periods are replaced with the value of the idseparator attribute ( _ by default)
Repeating separator characters are condensed.
If necessary, a sequence number is appended until the ID is unique within the document.
For example, the section title Wiley & Sons, Inc. produces the ID _wiley_sons_inc . You can customize the replacement
characters or toggle ID auto-generation using document attributes.
You can change the ID prefix by setting the idprefix attribute. The value of the idprefix attribute must begin with a valid ID
start character and can have any number of additional valid ID characters.
If you want to remove the prefix, set the attribute to an empty value.
If you set the idprefix to blank, you could end up generating IDs that are invalid in DocBook output (e.g., an
ID that begins with a number) or that match a built-in ID in the HTML output (e.g., header ). In this case, we
recommend either using a non-empty value of idprefix or assigning explicit IDs to your sections.
You can change the word separator using the idseparator attribute. Unless empty, the value of the idseparator must be
exactly one valid ID character.
If you don’t want to use a separator, set the attribute to an empty value.
== First Section
Content of first section
=== Nested Section
Content of nested section
== Second Section
Content of second section
ASCIIDOC
:idprefix: id_
ASCIIDOC
:idprefix:
ASCIIDOC
:idseparator: -
ASCIIDOC
12/20/2018 Asciidoctor User Manual
https://asciidoctor.org/docs/user-manual/ 61/315
When a document is rendered on GitHub, the idprefix is set to an empty value and the idseparator is set
to -. These settings are used to ensure that the IDs generated by GitHub match the IDs generated by
Asciidoctor.
To disable the auto-generation of section IDs, unset the sectids attribute.
Custom IDs, covered next, are used even if auto-generation of section IDs is disabled.
If you disable auto-generated section IDs, and you don’t assign a custom ID to a section, you won’t be able to
link to (i.e., reference) that section.
16.3. Custom IDs
You can assign a custom ID and optional reference text (i.e., label) to a section (see Defining an Anchor). The custom ID is used in
place of the auto-generated ID. This can be useful when you want to define a stable anchor for linking to a section using a cross
reference. The reference text is used when referencing the ID without specifying explicit text. This is a good way to centrally
manage the automatic reference text that is used to refer to a section.
Here’s an example of a section with a custom ID:
Here’s an example of a section with a custom ID and reference text:
The ID can be written using the following shorthand (though there’s no shorthand yet for the reference text):
The value of the reftext attribute must be quoted if it contains spaces or commas.
Asciidoctor permits all valid UTF-8 characters in section IDs. If you’re generating a PDF from AsciiDoc using
a2x and dblatex, see Using UTF-8 titles with a2x (https://aerostitch.github.io/misc/asciidoc/asciidoc-title_uft8.html) to
learn about the required latex.encoding=utf8 switch.
16.4. Multiple Anchors
While a section title can only have a single primary ID, as of Asciidoctor 1.5.7, it’s possible to register additional anchor points on a
section title using inline anchors. This feature works regardless of whether you assign a custom ID.
Here’s how to register additional anchor points when using an auto-generated ID:
Register additional leading anchor points
Register additional trailing anchor points
You can place the anchors anywhere you want within the section title line. Where you place them is where the anchor will end up
in the output, so it’s best to put them either at the beginning or the end. The beginning is the preferred location.
:idseparator:
ASCIIDOC
:sectids!:
ASCIIDOC
[#tiger-subspecies]
=== Subspecies of Tiger
ASCIIDOC
[[tiger-subspecies,Tigers]]
=== Subspecies of Tiger
ASCIIDOC
[#tiger-subspecies,reftext=Tigers]
=== Subspecies of Tiger
ASCIIDOC
== [[secondary-id]][[tertiary-id]]Section Title
ASCIIDOC
== Section Title[[secondary-id]][[tertiary-id]]
ASCIIDOC
12/20/2018 Asciidoctor User Manual
https://asciidoctor.org/docs/user-manual/ 62/315
These additional anchor points don’t interfere with defining a custom ID.
Register additional leading anchor points on a section title with a custom ID
Alternately, you can move the primary ID inline by placing it after the section title, offset by a single space.
Set the custom ID within the section title
However, we don’t recommend defining the primary ID inline as it’s more difficult to read.
16.5. Links
To turn section titles into links, enable the sectlinks attribute. The default Asciidoctor stylesheet displays linked section titles
with the same color and styles as unlinked section titles.
16.6. Anchors
When the sectanchors attribute is enabled on a document, an anchor (empty link) is added before the section title. The default
Asciidoctor stylesheet renders the anchor as a section entity ( §) that floats to the left of the section title.
16.7. Numbering
Asciidoctor allows section numbering to be toggled on and off throughout a document. You can enable section numbers using the
sectnums attribute.
Asciidoctor still supports the attribute name numbered to number sections for backward compatibility with
AsciiDoc Python, but the name sectnums is preferred.
You can also use this attribute entry above any section title in the document to toggle the auto-numbering setting. When you want
to turn off the numbering, add an exclamation point to the end of the attribute name:
For regions of the document where section numbering is turned off, the section numbering will not be incremented.
Given:
The sections will be numbered as follows:
[#primary-id]
== [[secondary-id]][[tertiary-id]]Section Title
ASCIIDOC
== Section Title[[secondary-id]][[tertiary-id]] [[primary-id]]
ASCIIDOC
:sectnums:
ASCIIDOC
:sectnums!:
== Unnumbered Section
ASCIIDOC
= Document Title
:sectnums!:
== Colophon Section
== Another Colophon Section
== Last Colophon Section
:sectnums:
== Section One
== Section Two
== Section Three
ASCIIDOC
12/20/2018 Asciidoctor User Manual
https://asciidoctor.org/docs/user-manual/ 63/315
Asciidoctor will always curtail incrementing the section number in regions of the document where section numbers are off.
If sectnums is set on the command line (or API), that overrides the value set in the document header, but it does not prevent the
document from toggling the value for regions of the document.
If sectnums! is set on the command line (or API), then the numbers are disabled regardless of the setting within the document.
Flexible attributes
The sectnums attribute is referred to as a “flexible attribute”, which means it can always be changed
midstream in the document, even if it is enabled through the API or CLI. At the time of writing, sectnums is
unique in this way, though other attributes may receive this special status in the future.
16.7.1. Numbering depth
You can restrict section numbering depth by defining the sectnumlevels (document header-only) attribute.
1When the sectnumlevels attribute is assigned a value of 2, section titles with levels 3 through 5 are not numbered (i.e.,
not prefixed with a number).
When the doctype is book , recall that level-1 sections become chapters. Therefore, a sectnumlevels of 4 translates to 3 levels
of numbered sections inside each chapter.
Assigning sectnumlevels a value of 0 is effectively the same as disabling section numbering (i.e., sectnums! ).
16.8. Discrete Headings (aka Floating Titles)
To make a discrete heading, you add the discrete attribute to any section title. A discrete heading is styled in a manner similar
to a section title, but is not part of the section hierarchy (i.e., and thus excluded from section nesting requirements), it does not
enclose subsequent blocks, and it is not included in the table of contents. The discrete style effectively demotes the section title
to a normal heading.
Alternately, you may use the float attribute to identify a discrete heading. In this context, the term “float”
does not imply layout, meaning it does not float to the left or right of other content blocks. It just means it’s not
anchored to the section hierarchy.
Here’s an example of a discrete heading in use.
1A delimiter line that indicates the start of a sidebar block.
2Set the discrete attribute above the section title to demote it to a discrete heading.
3The discrete heading title is designated by one to six equal signs, just like a section title.
16.9. Section Styles
Colophon Section
Another Colophon Section
Last Colophon Section
1. Section One
2. Section Two
3. Section Three
ASCIIDOC
:sectnumlevels: 2
ASCIIDOC
1
****
Discrete headings are useful for making headings inside of other blocks, like this sidebar.
[discrete]
== Discrete Heading
Discrete headings can be used where sections are not permitted.
****
ASCIIDOC
1
2
3
12/20/2018 Asciidoctor User Manual
https://asciidoctor.org/docs/user-manual/ 64/315
Asciidoctor provides styles for the frontmatter and backmatter sections commonly found in journal articles, academic papers,
and books. The styles are:
colophon
abstract
preface
dedication
part introduction
appendix
glossary
bibliography
index
These styles are available to the article and book document types, with the exception of the part introduction style which is
exclusive to books.
In general, the section style attribute is set above a level 1 section title or block of text. For instance, the example below shows
how to label a section as an abstract.
The structure and usage rules for each section style is explained in Structuring, Navigating, and Referencing Your Content.
16.10. Sections Summary
Section attributes and values
Attribute Value(s) Example Syntax Comments
sectids n/a :sectids!: Set to auto-generate section IDs by
default.
idprefix _, or user defined
text
:idprefix: id_ Set to prepend string to generated
section ID.
idseparator _, or user defined
character
:idseparator: - Set to insert character between words in
generated section ID.
sectanchors n/a :sectanchors: Asciidoctor only
sectlinks n/a :sectlinks: Asciidoctor only
sectnums n/a :sectnums: Section numbering is off by default. Can
be toggled on or off in the flow of the
document.
sectnumlevels 0-5 :sectnumlevels: 3 Set to autogenerate section numbers up
to level three by default. Setting a value
of 0 has the same effect as setting
sectnums! .
[abstract]
== Documentation Abstract
Documentation is a distillation of many long, squiggly adventures.
ASCIIDOC
12/20/2018 Asciidoctor User Manual
https://asciidoctor.org/docs/user-manual/ 65/315
17. Blocks
Section Pending
17.1. Title
You can assign a title to any paragraph, list, delimited block, or block macro. In most cases, the title is displayed immediately
above the content. If the content is a figure or image, the title is displayed below the content.
A block title is defined on a line above the element. The line must begin with a dot ( .) and be followed immediately by the title
text.
Here’s an example of a list with a title:
17.2. Metadata
In addition to a title, a block can be assigned additional metadata including:
Id (i.e., anchor)
Block name (first positional attribute)
Block attributes
Here’s an example of a quote block with metadata:
1Title: Gettysburg Address
2ID: gettysburg, see Defining an Anchor
3Block name: quote
4attribution: Abraham Lincoln (Named block attribute)
5citetitle: Address delivered at the dedication of the Cemetery at Gettysburg (Named block attribute)
A block can have multiple block attribute lines. The attributes will be aggregated. If there is a name conflict, the
last attribute defined wins.
Some metadata is used as supplementary content, such as the title, whereas other metadata controls how the block is converted,
such as the block name.
17.3. Delimited blocks
The AsciiDoc syntax provides a set of components for including non-paragraph text, such as block quotes, source code listings,
sidebars and tables, in your document. These components are referred to as delimited blocks because they are surrounded by
delimiter lines (e.g., **** ).
Here’s an example of a sidebar block:
.TODO list
- Learn the AsciiDoc syntax
- Install Asciidoctor
- Write my document
ASCIIDOC
.Gettysburg Address
[#gettysburg]
[quote, Abraham Lincoln, Address delivered at the dedication of the Cemetery at Gettysburg]
____
Four score and seven years ago our fathers brought forth
on this continent a new nation...
Now we are engaged in a great civil war, testing whether
that nation, or any nation so conceived and so dedicated,
can long endure. ...
____
ASCIIDOC
1
2
345
12/20/2018 Asciidoctor User Manual
https://asciidoctor.org/docs/user-manual/ 66/315
Within the boundaries of a delimited block, you can enter any content or blank lines. The block doesn’t end until the ending
delimiter is found. The delimiters around the block determine the type of block, how the content is processed and converted, and
what elements are used to wrap the content in the output.
17.3.1. Delimiter lines
The boundaries of a delimited block must be balanced. In other words, the opening delimiter line must be the same length as the
closing delimiter line.
For example, the following delimited block is not balanced and therefore invalid:
When the processor encounters the previous example, it will put the remainder of the content in the document inside the
delimited block (without warning, currently). As far as the processor is concerned, the closing delimiter is just a line of content. If
you want the closing delimiter to be matched, it must be the same length as the opening delimiter.
The AsciiDoc Python processor did not require the delimiters to be balanced, but also never documented that this was
permissible. We view AsciiDoc Python’s behavior of matching unbalanced delimited blocks to be a bug and therefore do not allow
it in Asciidoctor.
17.3.2. Optional delimiters
If the content is contiguous (not interrupted by blank lines), you can forgo the use of the block delimiters and instead use the
block name above a paragraph to repurpose it as one of the delimited block types.
This format is often used for single-line listings:
or single-line quotes:
17.3.3. Masquerading blocks
Some blocks can masquerade as other blocks, a feature which is controlled by the block name.
17.3.4. Nesting blocks
You can nest blocks inside each other. To nest blocks of the same type, add a pair of extra symbols to the delimiter. For example:
17.4. Built-in blocks summary
The following table identifies the built-in block names and delimited blocks syntax, their purposes, and the substitutions
performed on their contents.
****
sidebar block
****
********
invalid sidebar block
****
****
valid sidebar block
****
[listing]
sudo dnf install asciidoc
ASCIIDOC
[quote]
Never do today what you can put off `'til tomorrow.
ASCIIDOC
====
This is an example
======
This is an example inside an example
======
====
12/20/2018 Asciidoctor User Manual
https://asciidoctor.org/docs/user-manual/ 67/315
Block Block Name Delimiter Purpose Substitutions
Block Block Name Delimiter Purpose Substitutions
Admonition [<LABEL>] ==== Aside content that demands special attention; often
labeled with a tag or icon
Normal
Comment N/A //// Private notes that are not displayed in the output None
Example [example] ==== Designates example content or defines an
admonition block
Normal
Fenced N/A ``` Source code or keyboard input is displayed as
entered
Verbatim
Listing [listing] ---- Source code or keyboard input is displayed as
entered
Verbatim
Literal [literal] .... Output text is displayed exactly as entered Verbatim
Open Most block
names
-- Anonymous block that can act as any block except
passthrough or table blocks
Varies
Passthrough [pass] ++++ Unprocessed content that is sent directly to the
output
None
Quote [quote] ____ A quotation with optional attribution Normal
Sidebar [sidebar] **** Aside text and content displayed outside the flow of
the document
Normal
Source [source] ---- Source code or keyboard input to be displayed as
entered
Verbatim
Stem [stem] ++++ Unprocessed content that is sent directly to an
interpreter (such as AsciiMath or LaTeX math)
None
Table N/A |=== Displays tabular content Varies
Verse [verse] ____ A verse with optional attribution Normal
This table shows the substitutions performed by each substitution group referenced in the previous table.
Substitution groups
Group Special
characters
Quotes Attributes Replacements Macros Post
replacements
Header
None
Normal
Pass
Verbatim
Surround an attribute value with single quotes in order to apply normal substitutions.
12/20/2018 Asciidoctor User Manual
https://asciidoctor.org/docs/user-manual/ 68/315
18. Paragraph
The bulk of the content in a document is paragraph text. This is why Asciidoctor doesn’t require any special markup or attributes
to specify paragraph content. You can just start typing.
In Asciidoctor, adjacent or consecutive lines of text form a paragraph element. To start a new paragraph after another element,
such as a section title or table, hit the key twice to insert a blank line, and then continue typing your content.
Two paragraphs in an AsciiDoc document
The two paragraphs rendered using the default (html5) converter and stylesheet (asciidoctor.css)
This journey begins one late Monday afternoon in Antwerp. Our team desperately needs coffee, but none of us dare open
the office door.
To leave means code dismemberment and certain death.
18.1. Line Breaks
Since adjacent lines of text are combined into a single paragraph when Asciidoctor converts a document, that means you can
wrap paragraph text or put each sentence or phrase on a separate line. The line breaks won’t appear in the output.
However, if you want the line breaks in a paragraph to be preserved, you can either use a space followed by a plus sign ( +) or the
hardbreaks attribute. This results in a visible line break (e.g., <br> ) following each line.
Line breaks preserved using a space followed by the plus sign (+)
Rubies are red,
Topazes are blue.
Line breaks preserved using the hardbreaks attribute
Ruby is red.
Java is black.
Alternatively, you can preserve line breaks throughout your whole document by adding the hardbreaks attribute to the
document’s header.
Line breaks preserved throughout the document using the hardbreaks attribute
You can also preserve line breaks using literal blocks, listing blocks, and verses.
18.2. Lead Style
RETURN
This journey begins one late Monday afternoon in Antwerp.
Our team desperately needs coffee, but none of us dare open the office door.
To leave means code dismemberment and certain death.
ASCIIDOC
Rubies are red, +
Topazes are blue.
ASCIIDOC
[%hardbreaks]
Ruby is red.
Java is black.
ASCIIDOC
= Line Break Doc Title
:hardbreaks:
Rubies are red,
Topazes are blue.
ASCIIDOC
12/20/2018 Asciidoctor User Manual
https://asciidoctor.org/docs/user-manual/ 69/315
Apply the lead style to any paragraph, and it will render using a larger font size. The lead style is assigned to the role attribute.
You can set role using the long- or shorthand method.
Setting role using shorthand ( .) and assigning it the lead value
Rendered lead paragraph
This is the ultimate paragraph.
When you convert a document to HTML and view it using the default stylesheet, the first paragraph of the preamble is
automatically styled as a lead paragraph.
[.lead]
This is the ultimate paragraph.
ASCIIDOC
12/20/2018 Asciidoctor User Manual
https://asciidoctor.org/docs/user-manual/ 70/315
19. Text Formatting
Just as we emphasize certain words and phrases when we speak, we can emphasize them in text with formatting. This formatting,
such as bold or monospace, is indicated by surrounding letters, words, or phrases with simple markup. When Asciidoctor
processes text enclosed by formatting markup, the markup is replaced by the corresponding HTML or XML tags, depending on
your backend, during the quotes substitution phase.
Text formatting versus quotes
The original AsciiDoc processor calls this markup and its related features quotes, quotes substitutions, and quoted text.
However, in the Asciidoctor documentation, we refer to the text formatting markup as, you guessed it, text formatting.
When you need to control when text formatting is applied to certain blocks, the substitution attribute is still named
quotes , but we’re considering changing this to a more semantic name in a future Asciidoctor version.
Continue reading to learn how to format letters, words or phrases with the following styles:
bold
italic
curved (smart) quotation marks and apostrophes
subscript and superscript
monospace
highlighted, built-in and custom CSS styles
You may not always want these symbols to indicate text formatting. In those cases, you’ll need to use additional
markup to escape the text formatting markup.
19.1. Bold and Italic
The two most common ways of emphasizing a word is to format it as bold or italic. To apply bold styling to a word or phrase,
place an asterisk ( *) at the beginning and end of the text you wish to format. To bold a letter or letters in a string of text, place
two asterisks ( ** ) before and after the letter or letters.
Letters and words are italicized using one ( _) or two ( __ ) underscores. When you want to bold and italicize a letter or word, the
bold markup must be the outermost markup.
Bold and italic text formatting syntax
Result: bold and italic text
To tame the wild wolpertingers we needed to build a charm. But ultimate victory could only be won if we divined the true
name of the warlock.
19.2. Quotation Marks and Apostrophes
Single and double quotation marks are not rendered as curved quotation marks (also known as smart, curly, typographic or book
quotation marks). When entered using the and key, Asciidoctor outputs straight (dumb, vertical, typewriter) quotation
marks. However, by creating a set of backticks ( `) contained within a set of single quotes ( ') or double quotes ( "), you can tell
Asciidoctor where to output curved quotation marks.
Single and double curved quotation marks syntax
_To tame_ the wild wolpertingers we needed to build a *charm*.
But **u**ltimate victory could only be won if we divined the *_true name_* of the __war__lock.
ASCIIDOC
' "
"`What kind of charm?`" Lazarus asked. "`An odoriferous one or a mineral one?`"
Kizmet shrugged. "`The note from Olaf's desk says '`wormwood and licorice,`' but these could be normal groceries for werewo
ASCIIDOC
1
2
12/20/2018 Asciidoctor User Manual
https://asciidoctor.org/docs/user-manual/ 71/315
1To output double curved quotes, enclose a word or phrase in a set of double quotes ( ") and a set of backticks ( `).
2To output single curved quotes, enclose a word or phrase in a set of single quotes ( ') and a set of backticks ( `). In this
example, the phrase wormwood and licorice should be enclosed in curved single quotes when the document is rendered.
Rendered curved quotation marks
“What kind of charm?” Lazarus asked. “An odoriferous one or a mineral one?”
Kizmet shrugged. “The note from Olaf’s desk says ‘wormwood and licorice,’ but these could be normal groceries for
werewolves.”
When entered with the key, Asciidoctor renders an apostrophe that is directly preceded and followed by a character, such as
in contractions and possessive singular forms, as a curved apostrophe. This inconsistent handling of apostrophes and quotation
marks is a hold over from the original AsciiDoc processor. An apostrophe directly bounded by two characters is processed during
the replacements substitution phase, not the quotes phase. This is why an apostrophe directly followed by white space, such as
the possessive plural form, is not curved by default.
To render an apostrophe as curved when it is not bound by two characters, mark it as you would a single curved quote.
Curved apostrophe syntax
In the rendered output, note that the plural possessive apostrophe, seen trailing werewolves, is curved, as is the omission
apostrophe before 60s.
Rendered apostrophes
Olaf had been with the company since the ’60s. His desk overflowed with heaps of paper, apple cores and squeaky toys. We
couldn’t find Olaf’s keyboard. The state of his desk was replicated, in triplicate, across all of the werewolves’ desks.
If you don’t want an apostrophe that is bound by two characters to be rendered as curved, escape it by preceding it with a
backslash ( \). The preventing substitutions and passthrough sections detail additional ways to prevent punctuation
substitutions.
Rendered escaped apostrophe
Olaf's desk …
In order to make a possessive, monospaced phrase, you need to switch to unconstrained formatting and use an explicit
typographic apostrophe.
Rendered possessive, monospaced phrase
npm ’s job is to manage the dependencies for your application.
The same goes if the monospaced phrase ends in an “s”.
Rendered possessive, monospaced phrase that ends in an “s”
'
Olaf had been with the company since the `'60s.
His desk overflowed with heaps of paper, apple cores and squeaky toys.
We couldn't find Olaf's keyboard.
The state of his desk was replicated, in triplicate, across all of the werewolves`' desks.
ASCIIDOC
Olaf\'s desk ...
ASCIIDOC
``npm```'s job is to manage the dependencies for your application.
ASCIIDOC
This ``class```' static methods make it easy to operate on files and directories.
ASCIIDOC
12/20/2018 Asciidoctor User Manual
https://asciidoctor.org/docs/user-manual/ 72/315
This class ’ static methods make it easy to operate on files and directories.
Alternately, you could encode the typographic apostrophe directly in the AsciiDoc source to get the same result without the need
to use unconstrained formatting.
19.3. Subscript and Superscript
Subscript and superscript text is common in mathematical expressions and chemical formulas. When rendered, the size of
subscripted and superscripted text is reduced. Subscripted text is placed at the baseline and superscripted text above the baseline.
The size and precise placement of the text depends on the font and other stylesheet parameters applied to the converted
document.
Text is subscripted when you enclose it in a set of tildes ( ~) and superscripted with a set of carets ( ^)
Subscript
One tilde ( ~) on either side of a word or phrase makes it subscript.
Superscript
One caret ( ^) on either side of a word or phrase makes it superscript.
“Well the H O formula written on their whiteboard could be part of a shopping list, but I don’t think the local bodega sells
E=mc ,” Lazarus replied.
You can write and render equations and formulas in AsciiDoc documents using MathJax.
19.4. Monospace
In AsciiDoc, a span of text enclosed in a single set of backtick ( `) characters is displayed using a fixed-width (i.e., monospaced)
font. Monospace text formatting is typically used to represent text shown in computer terminals or code editors (often referred to
as a codespan).
Monospaced text can be bold and italicized, as long as the markup sets are entered in the right order. The monospace markup
must be the outermost set, then the bold set, and the italic markup must always be the innermost set.
As with other types of text formatting, if the text is bounded by characters on either side, it must be enclosed in a double set of
backtick characters ( `` ) in order for the formatting to be applied.
Here’s an example:
Rendered monospace formatted text
“Wait!” Indigo plucked a small vial from her desk’s top drawer and held it toward us. The vial’s label read: E=mc ; the
E
represents energy, but also pure genius!
19.4.1. Literal Monospace
Unlike other markup languages, monospaced text in AsciiDoc is not synonymous with literal text. Instead, it get interpretted just
like normal text. In other words, it’s subject to text substitutions.
The `class`’ static methods make it easy to operate on files and directories.
ASCIIDOC
"`Well the H~2~O formula written on their whiteboard could be part of a shopping list, but I don't think the local bodega s
ASCIIDOC
2
2
"`Wait!`" Indigo plucked a small vial from her desk's top drawer and held it toward us.
The vial's label read: `E=mc^2^`; the `_E_` represents _energy_, but also pure _genius!_
ASCIIDOC
2
12/20/2018 Asciidoctor User Manual
https://asciidoctor.org/docs/user-manual/ 73/315
This might be surprising at first. But there’s good reason for this difference. In AsciiDoc, you can take advantage of attribute
references and inline macros inside of monospaced text span. The drawback, of course, is that you have to be careful to escape
these special characters if you intend to output them literally.
One way to prevent the processor from interpretting special characters in monospaced text is to escape them using backslash
characters, just as you would with normal text. However, escaping individual occurrences that way can be tedious. That’s why
AsciiDoc offers a special type of monospace formatting called the literal monospace.
To make a true literal codespan in AsciiDoc, you must enclose the monospaced text in a passthrough. Rather than using a single
set of backtick characters, you’ll use the combination of the backtick and plus characters, where the plus characters fall on the
inside of the backtick characters (e.g., `+text+` ).
Here’s an example that contains literal, monospaced text.
This shorthand syntax can accomodate most of the literal monospace cases. The main exception is when the text itself contains
plus characters. To avoid confusing the processor, you’ll need to switch to using the more formal passthrough macro to handle
these cases.
Here’s an example of literal, monospaced text that contains plus characters.
Passthroughs are a general purpose utility in AsciiDoc. You can learn about the various passthrough options in Passthrough
Macros.
19.5. Custom Styling With Attributes
When text is enclosed in a set of single or double hash symbols ( #), and no style is assigned to it, the text will be rendered as
highlighted text (text wrapped in <mark> ).
Highlighted style syntax
Highlighted text HTML output
Rendered highlighted text
Werewolves are allergic to cinnamon.
Additionally, text marked with hash symbols can be assigned built-in styles, such as big and green .
Built-in CSS class syntax
1The first positional attribute is treated as a role. You can assign it a custom or built-in CSS class.
Rendered CSS class styled text
Do werewolves believe in small print?
Once upon an infinite loop.
You can format text with custom styles that you define as well.
Custom CSS class syntax
You can reference the value of a document attribute using the syntax `+{name}+`, where `name` is the attribute name.
ASCIIDOC
`pass:[++]` is the increment operator in C.
ASCIIDOC
Werewolves are #allergic to cinnamon#.
ASCIIDOC
<mark>mark element</mark>
HTML
Do werewolves believe in [small]#small print#?
[big]##O##nce upon an infinite loop.
ASCIIDOC
1
12/20/2018 Asciidoctor User Manual
https://asciidoctor.org/docs/user-manual/ 74/315
When converted to HTML, the word asciidoctor is wrapped in <span> tags and the role userinput is used as the element’s CSS
class.
HTML output
Type the word [.userinput]#asciidoctor# into the search bar.
ASCIIDOC
<span class="userinput">asciidoctor</span>
HTML
12/20/2018 Asciidoctor User Manual
https://asciidoctor.org/docs/user-manual/ 75/315
20. Unordered Lists
If you were to create a list in an e-mail, how would you do it? Chances are, you’d mark list items using the same characters that
Asciidoctor uses to find list items.
In the example below, each list item is marked using an asterisk ( *), the AsciiDoc syntax specifying an unordered list item.
A list item’s first line of text must be offset from the marker ( *) by at least one space. If you prefer, you can indent list items.
Blank lines are required before and after a list. Additionally, blank lines are permitted, but not required, between list items.
Rendered unordered list
Edgar Allen Poe
Sheri S. Tepper
Bill Bryson
You can add a title to a list by prefixing the title with a period ( .).
Rendered unordered list with a title
Kizmet’s Favorite Authors
Edgar Allen Poe
Sheri S. Tepper
Bill Bryson
Was your instinct to use a hyphen ( -) instead of an asterisk to mark list items? Guess what? That works too!
You should reserve the hyphen for lists that only have a single level because the hyphen marker ( -) doesn’t work for nested lists.
Now that we’ve mentioned nested lists, let’s go to the next section and learn how to create lists with multiple levels.
Separating Lists
If you have adjacent lists, they have the tendency to want to fuse together. To force lists apart, insert a line comment ( // )
surrounded by blank lines between the two lists. Here’s an example, where the - text in the line comment indicates the line
serves as an “end of list” marker:
20.1. Nested
* Edgar Allen Poe
* Sheri S. Tepper
* Bill Bryson
ASCIIDOC
.Kizmet's Favorite Authors
* Edgar Allen Poe
* Sheri S. Tepper
* Bill Bryson
ASCIIDOC
- Edgar Allen Poe
- Sheri S. Tepper
- Bill Bryson
ASCIIDOC
* Apples
* Oranges
//-
* Walnuts
* Almonds
ASCIIDOC
12/20/2018 Asciidoctor User Manual
https://asciidoctor.org/docs/user-manual/ 76/315
To nest an item, just add another asterisk ( *) to the marker, and another for each subsequent level.
Rendered nested, unordered list
Possible DefOps manual locations
West wood maze
Maze heart
Reflection pool
Secret exit
Untracked file in git repository
In Asciidoctor 1.5.7 and earlier you could only have up to six (6) levels of nesting (assuming one level uses the hyphen marker).
Since Asciidoctor 1.5.8, you can nest unordered lists to any depth. Keep in mind, however, that some interfaces will begin flatting
lists after a certain depth. GitHub starts flattening list after 10 levels of nesting.
level 1
level 2
level 3
level 4
level 5
level 1
While it would seem as though the number of asterisks represents the nesting level, that’s not how depth is determined. A new
level is created for each unique marker encountered. However, it’s much more intuitive to follow the convention that the number
of asterisks equals the level of nesting. After all, we’re shooting for plain text markup that is readable as is.
20.2. Complex List Content
Aside from nested lists, all of the list items you’ve seen only have one line of text. But like with regular paragraph text, the text in a
list item can wrap across any number of lines, as long as all the lines are adjacent. The wrapped lines can be indented and they
will still be treated as normal paragraph text. For example:
The header in AsciiDoc is optional, but if it is used it must start with a document title.
.Possible DefOps manual locations
* West wood maze
** Maze heart
*** Reflection pool
** Secret exit
* Untracked file in git repository
ASCIIDOC
* level 1
** level 2
*** level 3
**** level 4
***** level 5
* level 1
ASCIIDOC
* The header in AsciiDoc is optional, but if
it is used it must start with a document title.
* Optional Author and Revision information
immediately follows the header title.
* The document header must be separated from
the remainder of the document by one or more
blank lines and cannot contain blank lines.
ASCIIDOC
12/20/2018 Asciidoctor User Manual
https://asciidoctor.org/docs/user-manual/ 77/315
Optional Author and Revision information immediately follows the header title.
The document header must be separated from the remainder of the document by one or more blank lines and cannot
contain blank lines.
When items contain more than one line of text, leave a blank line before the next item to make the list easier to
read.
A list item may contain any type of AsciiDoc content, including paragraphs, delimited blocks, and block macros. You just need to
attach them to the list item.
20.2.1. List continuation
To add additional paragraphs or other block elements to a list item, you must “attach” them (in a series) using a list continuation.
A list continuation is a + symbol on a line by itself, immediately adjacent to the block being attached.
Here’s an example:
The header in AsciiDoc must start with a document title.
The header is optional.
Using the list continuation, you can attach any number of block elements to a list item. Each block must be preceded by a list
continuation to form a chain of blocks.
Here’s an example that attaches both a listing block and an admonition paragraph to the first item:
Here’s how the source is rendered:
A list with complex content
The header in AsciiDoc must start with a document title.
Keep in mind that the header is optional.
Optional Author and Revision information immediately follows the header title.
* The header in AsciiDoc must start with a document title.
+
The header is optional.
ASCIIDOC
* The header in AsciiDoc must start with a document title.
+
----
= Document Title
----
+
Keep in mind that the header is optional.
* Optional Author and Revision information immediately follows the header title.
+
----
= Document Title
Doc Writer <doc.writer@asciidoc.org>
v1.0, 2013-01-01
----
ASCIIDOC
= Document Title
= Document Title
Doc Writer <doc.writer@asciidoc.org>
v1.0, 2013-01-01
12/20/2018 Asciidoctor User Manual
https://asciidoctor.org/docs/user-manual/ 78/315
If you’re attaching more than one block to a list item, you’re strongly encouraged to wrap the content inside an open block. That
way, you only need a single list continuation line to attach the open block to the list item. Within the open block, you write like
you normally would, no longer having to worry about adding list continuations between the blocks to keep them attached to the
list item.
Here’s an example of wrapping complex list content in an open block:
Here’s how that content is rendered:
A list with complex content wrapped in an open block
The header in AsciiDoc must start with a document title.
Here’s an example of a document title:
The header is optional.
The open block wrapper is also useful if you’re including content from a shared file into a list item. For example:
By wrapping the include directive in an open block, the content can be used unmodified.
The only limitation of this technique is that the content itself may not contain an open block (since open blocks cannot be nested).
20.2.2. Dropping the principal text
If the principal text of a list item is blank, the node for the principal text is dropped. This is how you can get the first block (such as
a listing block) to line up with the list marker. You can make the principal text blank by using the {blank} attribute reference.
Here’s an example of a list that has items with only complex content.
Here’s how the source is rendered:
A list with complex content
* The header in AsciiDoc must start with a document title.
+
--
Here's an example of a document title:
----
= Document Title
----
NOTE: The header is optional.
--
ASCIIDOC
= Document Title
* list item
+
--
include::shared-content.adoc[]
--
ASCIIDOC
. {blank}
+
----
print("one")
----
. {blank}
+
----
print("one")
----
ASCIIDOC
12/20/2018 Asciidoctor User Manual
https://asciidoctor.org/docs/user-manual/ 79/315
20.2.3. Attaching to an ancestor list
You may find that you need to attach block content to a parent list item instead of the current one. In other words, you want to
attach the block content to the parent list item so it becomes a sibling of the child list. To do this, you add a blank line before the
list continuation. The blank line signals to the list continuation to move out of the current list so it attaches the block to the last
item of the parent list.
Here’s an example of a paragraph that’s attached to the parent list item, placing it adjacent to the child list (instead of inside of it).
Here’s how the source is rendered:
A block attached to the parent list item
parent list item
child list item
paragraph attached to parent list item
Each blank line that precedes the list continuation signals a move up one level of nesting. Here’s an example that shows how to
attach a paragraph to a grandparent list item using two leading blank lines:
Here’s how the source is rendered:
A block attached to the grandparent list item
grandparent list item
parent list item
child list item
paragraph attached to grandparent list item
Using blank lines to back out of the nesting may feel fragile. A more robust way to accomplish the same thing is to enclose the
nested lists in an open block. That way, it’s clear where the nested list ends and the enclosing list continues.
1. print("one")
2. print("one")
* parent list item
** child list item
+
paragraph attached to parent list item
ASCIIDOC
* grandparent list item
** parent list item
*** child list item
+
paragraph attached to grandparent list item
ASCIIDOC
* grandparent list item
+
--
** parent list item
*** child list item
--
+
paragraph attached to grandparent list item
ASCIIDOC
12/20/2018 Asciidoctor User Manual
https://asciidoctor.org/docs/user-manual/ 80/315
Here’s how the source is rendered:
A nested block enclosed in an open block
grandparent list item
parent list item
child list item
paragraph attached to grandparent list item
As you’ve learned in this section, the primary text of a list item can wrap to any number of adjacent lines. You can also attach any
type of content to a list item using the list continuation. Combining those features with the open block makes it even easier to
create lists with complex content.
20.3. Custom Markers
Asciidoctor offers numerous bullet styles for lists. The list marker (bullet) is set using the list’s block style.
The unordered list marker can be set using any of the following block styles:
square
circle
disc
none or no-bullet (indented, but no bullet)
unstyled (no indentation or bullet) (HTML only)
These styles are supported by the default Asciidoctor stylesheet.
When present, the style name is assigned to the unordered list element as follows:
For HTML
the style name is assigned to the class attribute on the <ul> element.
For DocBook
the style name is assigned to the mark attribute on the <itemizedlist> element.
Here’s an unordered list that has square bullets:
one
two
three
20.4. Checklist
List items can be marked complete using checklists.
Checklists (i.e., task lists) are unordered lists that have items marked as checked ( [*] or [x] ) or unchecked ( [ ] ). Here’s an
example:
Checklist syntax
[square]
* one
* two
* three
ASCIIDOC
12/20/2018 Asciidoctor User Manual
https://asciidoctor.org/docs/user-manual/ 81/315
Rendered checklist
checked
also checked
not checked
normal list item
Not all items in the list have to be checklist items, as the previous example shows.
When checklists are converted to HTML, the checkbox markup is transformed into an HTML checkbox with the appropriate
checked state. The data-item-complete attribute on the checkbox is set to 1 if the item is checked, 0 if not. The checkbox is used
in place of the item’s bullet.
Since HTML generated by Asciidoctor is usually static, the checkbox is set as disabled to make it appear as a simple mark. If you
want to make the checkbox interactive (i.e., clickable), add the interactive option to the checklist (shown here using the
shorthand syntax for Options):
Checklist with interactive checkboxes
Rendered checklist with interactive checkboxes
checked
also checked
not checked
normal list item
As a bonus, if you enable font-based icons, the checkbox markup (in non-interactive lists) is transformed into a font-based icon!
Checklist with font-based checkboxes
* [*] checked
* [x] also checked
* [ ] not checked
* normal list item
ASCIIDOC
[%interactive]
* [*] checked
* [x] also checked
* [ ] not checked
* normal list item
ASCIIDOC
[%interactive]
* [*] checked
* [x] also checked
* [ ] not checked
* normal list item
ASCIIDOC
12/20/2018 Asciidoctor User Manual
https://asciidoctor.org/docs/user-manual/ 82/315
21. Ordered Lists
Sometimes, we need to number the items in a list. Instinct might tell you to prefix each item with a number, like in this next list:
The above works, but since the numbering is obvious, the AsciiDoc processor will insert the numbers for you if you omit them:
1. Protons
2. Electrons
3. Neutrons
If you decide to use number for your ordered list, you have to keep them sequential. This differs from other lightweight markup
languages. It’s one way to adjust the numbering offset of a list. For instance, you can type:
However, in general the best practice is to use the start attribute to configure this sort of thing:
To present the items in reverse order, add the reversed option:
Parts of an atom
3. Protons
2. Electrons
1. Neutrons
You can give a list a title by prefixing the line with a dot immediately followed by the text (without leaving any space after the
dot).
Here’s an example of a list with a title:
Parts of an atom
1. Protons
1. Protons
2. Electrons
3. Neutrons
ASCIIDOC
. Protons
. Electrons
. Neutrons
ASCIIDOC
4. Step four
5. Step five
6. Step six
ASCIIDOC
[start=4]
. Step four
. Step five
. Step six
ASCIIDOC
[%reversed]
.Parts of an atom
. Protons
. Electrons
. Neutrons
ASCIIDOC
.Parts of an atom
. Protons
. Electrons
. Neutrons
ASCIIDOC
12/20/2018 Asciidoctor User Manual
https://asciidoctor.org/docs/user-manual/ 83/315
““
“
2. Electrons
3. Neutrons
21.1. Nested
You create a nested item by using one or more dots in front of each the item.
AsciiDoc selects a different number scheme for each level of nesting. Here’s how the previous list renders:
A nested ordered list
1. Step 1
2. Step 2
a. Step 2a
b. Step 2b
3. Step 3
Like with the asterisks in an unordered list, the number of dots in an ordered list doesn’t represent the nesting
level. However, it’s much more intuitive to follow this convention:
# of dots = level of nesting
Again, we are shooting for plain text markup that is readable as is.
You can mix and match the three list types, ordered, unordered, and description, within a single hybrid list. Asciidoctor works
hard to infer the relationships between the items that are most intuitive to us humans.
Here’s an example of nesting an unordered list inside of an ordered list:
1. Linux
Fedora
Ubuntu
Slackware
2. BSD
FreeBSD
NetBSD
You can spread the items out and indent the nested lists if that makes it more readable for you:
. Step 1
. Step 2
.. Step 2a
.. Step 2b
. Step 3
ASCIIDOC
. Linux
* Fedora
* Ubuntu
* Slackware
. BSD
* FreeBSD
* NetBSD
ASCIIDOC
12/20/2018 Asciidoctor User Manual
https://asciidoctor.org/docs/user-manual/ 84/315
The description list section demonstrates how to combine all three list types.
21.2. Numbering Styles
For ordered lists, Asciidoctor supports the numeration styles such as lowergreek and decimal-leading-zero.
The full list of numeration styles that can be applied to an ordered list are as follows:
Asciidoctor ordered list numeration styles
Block style CSS list-style-type
arabic decimal
decimal* decimal-leading-zero
loweralpha lower-alpha
upperalpha upper-alpha
lowerroman lower-roman
upperroman upper-roman
lowergreek* lower-greek
* These styles are only supported by the HTML converters.
Here are a few examples showing various numeration styles as defined by the block style shown in the header row:
[arabic]* [decimal] [loweralpha] [lowergreek]
1. one
2. two
3. three
01. one
02. two
03. three
a. one
b. two
c. three
α. one
β. two
γ. three
* Default numeration if block style is not specified
Custom numeration styles can be implemented using a custom role. Define a new class selector (e.g., .custom )
in your stylesheet that sets the list-style-type property to the value of your choice. Then, assign the name
of that class as a role on any list to which you want that numeration applied.
When the role shorthand ( .custom ) is used on an ordered list, the numeration style is no longer omitted.
You can override the number scheme for any level by setting its style (the first positional entry in a block attribute list). You can
also set the starting number using the start attribute:
. Linux
* Fedora
* Ubuntu
* Slackware
. BSD
* FreeBSD
* NetBSD
ASCIIDOC
["lowerroman", start=5]
. Five
. Six
[loweralpha]
.. a
.. b
.. c
. Seven
ASCIIDOC
12/20/2018 Asciidoctor User Manual
https://asciidoctor.org/docs/user-manual/ 85/315
v. Five
vi. Six
a. a
b. b
c. c
vii. Seven
The start attribute must be a number, even when using a different numeration style. For instance, to start an
alphabetic list at letter "c", set the numeration style to loweralpha and the start attribute to 3.
12/20/2018 Asciidoctor User Manual
https://asciidoctor.org/docs/user-manual/ 86/315
22. Description List
A description list (often abbreviate as dlist) is useful when you need to include a description or supporting text for one or more
terms. Each item in a description list consists of:
one or more terms
a separator following each term (typically a double colon, :: )
at least one space or endline
the supporting content (either text, attached blocks, or both)
Here’s an example of a description list that identifies parts of a computer:
By default, the content of each item is displayed below the description when rendered. Here’s a preview of how this list is
rendered:
A basic description list
CPU
The brain of the computer.
Hard drive
Permanent storage for operating system and/or user files.
RAM
Temporarily stores information the CPU uses during operation.
Keyboard
Used to enter text or control items on the screen.
Mouse
Used to point to and select items on your computer screen.
Monitor
Displays information in visual form using text and graphics.
If you want the description and content to appear on the same line, add the horizontal style to the list.
CPU The brain of the computer.
Hard drive Permanent storage for operating system and/or user files.
RAM Temporarily stores information the CPU uses during operation.
The content of a description list can be any AsciiDoc element. For instance, we could rewrite the grocery list from above so that
each aisle is a description rather than a parent outline list item.
CPU:: The brain of the computer.
Hard drive:: Permanent storage for operating system and/or user files.
RAM:: Temporarily stores information the CPU uses during operation.
Keyboard:: Used to enter text or control items on the screen.
Mouse:: Used to point to and select items on your computer screen.
Monitor:: Displays information in visual form using text and graphics.
ASCIIDOC
[horizontal]
CPU:: The brain of the computer.
Hard drive:: Permanent storage for operating system and/or user files.
RAM:: Temporarily stores information the CPU uses during operation.
ASCIIDOC
12/20/2018 Asciidoctor User Manual
https://asciidoctor.org/docs/user-manual/ 87/315
Dairy
Milk
Eggs
Bakery
Bread
Produce
Bananas
Description lists are quite lenient about whitespace, so you can spread the items out and even indent the content if that makes it
more readable for you:
Finally, you can mix and match the three list types within a single hybrid list. Asciidoctor works hard to infer the relationships
between the items that are most intuitive to us humans.
Here’s a list that mixes description, ordered, and unordered list items:
Here’s how the list is rendered:
A hybrid list
Operating Systems
Linux
1. Fedora
Dairy::
* Milk
* Eggs
Bakery::
* Bread
Produce::
* Bananas
ASCIIDOC
Dairy::
* Milk
* Eggs
Bakery::
* Bread
Produce::
* Bananas
ASCIIDOC
Operating Systems::
Linux:::
. Fedora
* Desktop
. Ubuntu
* Desktop
* Server
BSD:::
. FreeBSD
. NetBSD
Cloud Providers::
PaaS:::
. OpenShift
. CloudBees
IaaS:::
. Amazon EC2
. Rackspace
ASCIIDOC
12/20/2018 Asciidoctor User Manual
https://asciidoctor.org/docs/user-manual/ 88/315
Desktop
2. Ubuntu
Desktop
Server
BSD
1. FreeBSD
2. NetBSD
Cloud Providers
PaaS
1. OpenShift
2. CloudBees
IaaS
1. Amazon EC2
2. Rackspace
You can include more complex content in a list item as well.
22.1. Question and Answer Style List
Q&A
1. What is Asciidoctor?
An implementation of the AsciiDoc processor in Ruby.
2. What is the answer to the Ultimate Question?
42
[qanda]
What is Asciidoctor?::
An implementation of the AsciiDoc processor in Ruby.
What is the answer to the Ultimate Question?:: 42
ASCIIDOC
12/20/2018 Asciidoctor User Manual
https://asciidoctor.org/docs/user-manual/ 89/315
23. Tables
Tables are one of the most intricate, yet refined areas of the AsciiDoc syntax. Armed with a bit of knowledge, you should discover
that they are both easy to create and easy to read in raw form. Yet, under all that simplicity, they are remarkably sophisticated.
Tables are delimited by |=== and made up of cells. The default table data format is PSV (Prefix Separated Values), which means
that the processor creates a new cell each time it encounters a vertical bar ( |). Cells are grouped into rows. Each row must share
the same number of cells, taking into account any column or row spans. Then, each consecutive cell in a row is placed in a
separate column.
The simple table example below consists of two columns and three rows.
Simple table
1The table’s content boundaries are defined by a vertical bar followed by three equal signs ( |=== ).
2Inserting a blank line before the first row is a trick to ensure the first row is not treated as the table header.
3The new cell is marked by a vertical bar ( |).
4Rows can optionally be separated by any number of blank lines.
Result: Rendered simple table
Cell in column 1, row 1 Cell in column 2, row 1
Cell in column 1, row 2 Cell in column 2, row 2
Cell in column 1, row 3 Cell in column 2, row 3
Like with all blocks, you can add a role to a table using the role attribute. The role attribute becomes a CSS class when converted
to HTML. The preferred shorthand for assigning the role attribute is to put the role name in the first position of the block attribute
list prefixed with a . character, as shown here:
Leading and trailing spaces around cell content is stripped and, therefore, don’t affect the table’s layout when rendered. The two
examples below illustrate how leading and trailing spaces don’t change the rendered table’s layout.
Cell content adjacent to the |
Result: Rendered table when cell content was entered adjacent to the |
Cell in column 1, row 1 Cell in column 2, row 1
Cell content with varying leading and trailing spaces
|===
| Cell in column 1, row 1 | Cell in column 2, row 1
| Cell in column 1, row 2 | Cell in column 2, row 2
| Cell in column 1, row 3 | Cell in column 2, row 3
|===
ASCIIDOC
1
2
3
4
1
[.rolename]
|===
| Cell in column 1, row 1 | Cell in column 2, row 1 | Cell in column 3, row 1
| Cell in column 1, row 2 | Cell in column 2, row 2 | Cell in column 3, row 2
|===
ASCIIDOC
|===
|Cell in column 1, row 1|Cell in column 2, row 1
|===
ASCIIDOC
12/20/2018 Asciidoctor User Manual
https://asciidoctor.org/docs/user-manual/ 90/315
Result: Rendered table when cell content was bounded by varying leading and trailing spaces
Cell in column 1, row 1 Cell in column 2, row 1
There are multiple ways to group cells into a row. The cells in a row can be placed on:
a. the same line
b. consecutive, individual lines
c. a combination of a and b
Cells on the same line
Result: Rendered table when multiple cells where entered on the same line
Cell in column 1, row 1 Cell in column 2, row 1 Cell in column 3, row 1
Cell in column 1, row 2 Cell in column 2, row 2 Cell in column 3, row 2
When the cells of a row are individually entered on consecutive lines, the cols attribute is needed to specify the number of
columns in the table. If the cols attribute is not set, the first non-blank line inside the block delimiter ( |=== ) determines the
number of columns.
Cells on consecutive, individual lines
1The cols attribute states that this table has three columns. The * is a repeat operator which is explained in the column
specifiers section.
Result: Rendered table when cells where listed on consecutive, individual lines
Cell in column 1, row 1 Cell in column 2, row 1 Cell in column 3, row 1
Cell in column 1, row 2 Cell in column 2, row 2 Cell in column 3, row 2
Rows can be formed from adjacent lines of individual cells and cells listed on the same line.
Cells on the same line and individual lines
|===
| Cell in column 1, row 1 | Cell in column 2, row 1
|===
ASCIIDOC
|===
|Cell in column 1, row 1 |Cell in column 2, row 1 |Cell in column 3, row 1
|Cell in column 1, row 2 |Cell in column 2, row 2 |Cell in column 3, row 2
|===
ASCIIDOC
[cols="3*"]
|===
|Cell in column 1, row 1
|Cell in column 2, row 1
|Cell in column 3, row 1
|Cell in column 1, row 2
|Cell in column 2, row 2
|Cell in column 3, row 2
|===
ASCIIDOC
1
[cols="3*"]
|===
|Cell in column 1, row 1 |Cell in column 2, row 1
|Cell in column 3, row 1
|Cell in column 1, row 2
|Cell in column 2, row 2 |Cell in column 3, row 2
|===
ASCIIDOC
12/20/2018 Asciidoctor User Manual
https://asciidoctor.org/docs/user-manual/ 91/315
Result: Cells on the same line and individual lines
Cell in column 1, row 1 Cell in column 2, row 1 Cell in column 3, row 1
Cell in column 1, row 2 Cell in column 2, row 2 Cell in column 3, row 2
The next sections describe and demonstrate the variety of ways you can customize table cells, rows and columns.
23.1. Columns
The number of columns in a table is determined by the number of cells found in the first non-blank line after the table delimiter
(|=== ) or by the values assigned to the cols attribute.
For example, the syntax in the two examples below will both converted to a table with two columns.
Result: Rendered table with two columns as defined by the number of cells in the first row
Cell in column 1, row 1 Cell in column 2, row 1
Cell in column 1, row 2 Cell in column 2, row 2
Result: Rendered table with two columns as defined by the cols attribute
Cell in column 1, row 1 Cell in column 2, row 1
Cell in column 1, row 2 Cell in column 2, row 2
When a single number is assigned to the cols attribute, its value indicates the number of columns. Each column will be the same
width. However, the number of columns can also be assigned as a comma delimited list. The number of entries in the list
determines the number of columns.
The comma delimited list below creates a table with four columns of equal width.
This syntax provides that same result:
Now, let’s talk about that asterisk in the syntax above.
23.2. Column Formatting
The AsciiDoc syntax provides a variety of ways to control the size, style and layout of content within columns. These specifiers
can be applied to whole columns.
|===
|Cell in column 1, row 1 |Cell in column 2, row 1
|Cell in column 1, row 2
|Cell in column 2, row 2
|===
ASCIIDOC
[cols="2*"]
|===
|Cell in column 1, row 1
|Cell in column 2, row 1
|Cell in column 1, row 2
|Cell in column 2, row 2
|===
ASCIIDOC
[cols="1,1,1,1"]
ASCIIDOC
[cols="4*"]
ASCIIDOC
12/20/2018 Asciidoctor User Manual
https://asciidoctor.org/docs/user-manual/ 92/315
To apply a specifier to a column, you must set the cols attribute and assign it a value. A column specifier can contain any of the
following components:
multiplier
align
width
style
Each component is optional.
The multiplier operator ( *) is used when you want a specifier to apply to more than one consecutive column. If used, the
multiplier must always be placed at the beginning of the specifier.
For example:
1The table will consist of three columns, as indicated by the 3. The * operator ensures that the default layout and style
will be applied to all of the columns.
Result: Rendered table with multiplier applied
Cell in column 1, row 1 Cell in column 2, row 1 Cell in column 3, row 1
Cell in column 1, row 2 Cell in column 2, row 2 Cell in column 3, row 2
The alignment component allows you to horizontally or vertically align a column’s content. Content can be horizontally aligned
left ( <), center ( ^), or right ( >).
To horizontally center the content in all of the columns, add the ^ operator after the multiplier.
Result: Rendered table with horizontal, center alignment applied to all columns
Cell in column 1, row 1 Cell in column 2, row 1 Cell in column 3, row 1
Cell in column 1, row 2 Cell in column 2, row 2 Cell in column 3, row 2
What if you only want to center the content in the last column? Assign the default styles to the preceding columns, and ^ to the
last column in a comma separated list.
[cols="3*"]
|===
|Cell in column 1, row 1
|Cell in column 2, row 1
|Cell in column 3, row 1
|Cell in column 1, row 2
|Cell in column 2, row 2
|Cell in column 3, row 2
|===
ASCIIDOC
1
[cols="3*^"]
|===
|Cell in column 1, row 1
|Cell in column 2, row 1
|Cell in column 3, row 1
|Cell in column 1, row 2
|Cell in column 2, row 2
|Cell in column 3, row 2
|===
ASCIIDOC
12/20/2018 Asciidoctor User Manual
https://asciidoctor.org/docs/user-manual/ 93/315
Result: Rendered table with horizontal, center alignment applied to last column
Cell in column 1, row 1 Cell in column 2, row 1 Cell in column 3, row 1
Cell in column 1, row 2 Cell in column 2, row 2 Cell in column 3, row 2
Let’s specify a different horizontal alignment for each column.
Result: Rendered table with a different horizontal alignment for each column
Cell in column 1, row 1 Cell in column 2, row 1 Cell in column 3, row 1
Cell in column 1, row 2 Cell in column 2, row 2 Cell in column 3, row 2
You’ll notice that the content in the examples above is only centered on the horizontal. It can also be aligned vertically when the
alignment operator is prefixed with a dot ( .). Content can be vertically aligned to the top ( <), middle ( ^), or bottom ( >) of a cell.
To vertically align the content to the middle of the cells in all of the columns, add a . and then the ^ operator after the
multiplier.
Result: Rendered table with vertical, middle alignment applied to all columns
Cell in column 1, row 1 Cell in column 2, row 1 Cell in column 3, row 1
Cell in column 1, row 2 Cell in column 2, row 2 Cell in column 3, row 2
If you only want to align the content to the bottom of each cell in the last column, you’d assign the default styles to the preceding
columns, and > to the last column in a comma separated list.
[cols="2*,^"]
|===
|Cell in column 1, row 1
|Cell in column 2, row 1
|Cell in column 3, row 1
|Cell in column 1, row 2
|Cell in column 2, row 2
|Cell in column 3, row 2
|===
ASCIIDOC
[cols="<,^,>"]
|===
|Cell in column 1, row 1
|Cell in column 2, row 1
|Cell in column 3, row 1
|Cell in column 1, row 2
|Cell in column 2, row 2
|Cell in column 3, row 2
|===
ASCIIDOC
[cols="3*.^"]
|===
|Cell in column 1, row 1
|Cell in column 2, row 1
|Cell in column 3, row 1
|Cell in column 1, row 2
|Cell in column 2, row 2
|Cell in column 3, row 2
|===
ASCIIDOC
12/20/2018 Asciidoctor User Manual
https://asciidoctor.org/docs/user-manual/ 94/315
Result: Rendered table with vertical, bottom alignment applied to last column
Cell in column 1, row 1 Cell in column 2, row 1 Cell in column 3, row 1
Cell in column 1, row 2 Cell in column 2, row 2 Cell in column 3, row 2
Let’s specify a different vertical alignment for each column.
Result: Rendered table with a different vertical alignment for each column
Cell in column 1, row 1 Cell in column 2, row 1 Cell in column 3, row 1
Cell in column 1, row 2 Cell in column 2, row 2 Cell in column 3, row 2
Finally, we’ll also horizontally center the content in the last column.
Result: Rendered table with a different vertical alignment for each column and horizontal, center alignment in the
last column
Cell in column 1, row 1 Cell in column 2, row 1 Cell in column 3, row 1
Cell in column 1, row 2 Cell in column 2, row 2 Cell in column 3, row 2
When both a horizontal and vertical alignment is assigned to a column, the horizontal alignment operator must precede the
vertical operator.
The width component sets the width of a column. Its value can be a proportional integer (the default is 1) or a percentage (1 to 99).
[cols="2*,.>"]
|===
|Cell in column 1, row 1
|Cell in column 2, row 1
|Cell in column 3, row 1
|Cell in column 1, row 2
|Cell in column 2, row 2
|Cell in column 3, row 2
|===
ASCIIDOC
[cols=".<,.^,.>"]
|===
|Cell in column 1, row 1
|Cell in column 2, row 1
|Cell in column 3, row 1
|Cell in column 1, row 2
|Cell in column 2, row 2
|Cell in column 3, row 2
|===
ASCIIDOC
[cols=".<,.^,^.>"]
|===
|Cell in column 1, row 1
|Cell in column 2, row 1
|Cell in column 3, row 1
|Cell in column 1, row 2
|Cell in column 2, row 2
|Cell in column 3, row 2
|===
ASCIIDOC
12/20/2018 Asciidoctor User Manual
https://asciidoctor.org/docs/user-manual/ 95/315
Result: Table rendered with column sizes adjusted by a proportional integer
Cell in
column 1,
row 1
Cell in column 2, row 1 Cell in column 3, row 1
Cell in
column 1,
row 2
Cell in column 2, row 2 Cell in column 3, row 2
When assigning percentage values to the cols attribute, you do not need to include the percent sign ( %).
Result: Table rendered with column sizes adjusted by a percentage
Cell in column 1, row 1 Cell in column 2, row 1 Cell in column 3, row 1
Cell in column 1, row 2 Cell in column 2, row 2 Cell in column 3, row 2
Let’s create a table with custom widths and alignments.
Result: Rendered table with variable widths and alignments
Cell in column 1, row 1
with lots and lots and
lots and lots of content
Cell in column 2, row 1
Cell in column 3, row 1
Cell in column 1, row 2
Cell in column 2, row 2
Cell in column 3, row 2 and another
bucket of content, and then a jelly
roll of content
The style component must always be located at the end of the specifier. When no style name is provided column contents will be
processed as regular inline text.
The column styles are described in the table below.
[cols="1,2,6"]
|===
|Cell in column 1, row 1
|Cell in column 2, row 1
|Cell in column 3, row 1
|Cell in column 1, row 2
|Cell in column 2, row 2
|Cell in column 3, row 2
|===
ASCIIDOC
[cols="50,20,30"]
|===
|Cell in column 1, row 1
|Cell in column 2, row 1
|Cell in column 3, row 1
|Cell in column 1, row 2
|Cell in column 2, row 2
|Cell in column 3, row 2
|===
ASCIIDOC
[cols=".<2,.^5,^.>3"]
|===
|Cell in column 1, row 1 with lots and lots and lots and lots of content
|Cell in column 2, row 1
|Cell in column 3, row 1
|Cell in column 1, row 2
|Cell in column 2, row 2
|Cell in column 3, row 2 and another bucket of content, and then a jelly roll of content
|===
ASCIIDOC
12/20/2018 Asciidoctor User Manual
https://asciidoctor.org/docs/user-manual/ 96/315
Style Name Value Description
Style Name Value Description
AsciiDoc aSupports block-level elements (paragraphs, delimited blocks,
and block macros). This style effectively creates a nested,
standalone AsciiDoc document. Implicit attributes such as
doctitle from the parent document will be shadowed. Custom
attributes are inherited.
Emphasis eText is italicized
Header hHeader styles are applied to the column
Literal lColumn content is treated as if it were inside a literal block
Monospaced mText is rendered in monospaced font
None (default style) dText is handled like a normal paragraph. Supports all markup
(i.e., inline formatting, inline macros) that is permitted in a
paragraph.
Strong sText is bolded
Verse vColumn content is treated as if it were inside a verse block
Let’s apply the header style to the first column, the monospaced style to the second, the strong style to the third, and the emphasis
style to the fourth.
Result: Rendered table with a header, monospaced, and strong styled column
Cell in column 1, row 1 Cell in column 2, row 1 Cell in column 3, row 1 Cell in column 4, row 1
Cell in column 1, row 2 Cell in column 2, row 2 Cell in column 3, row 2 Cell in column 4, row 2
Specifiers can also be applied to individual cells.
23.3. Cell Formatting
In addition to sharing many of the column specifier capabilities, cell specifiers allow cells to span rows and columns. Like a
column specifier, a cell specifier is made up of components. These components, listed and defined below, are all optional.
span
align
style
A cell specifier is prefixed directly to the cell delimiter ( |) preceding the content you want to customize.
The span component can duplicate a cell or have it span multiple rows or columns.
To duplicate a cell in multiple, consecutive columns, prefix the | with the multiplication factor and the * operator.
Cell duplicated across three columns
[cols="h,m,s,e"]
|===
|Cell in column 1, row 1
|Cell in column 2, row 1
|Cell in column 3, row 1
|Cell in column 4, row 1
|Cell in column 1, row 2
|Cell in column 2, row 2
|Cell in column 3, row 2
|Cell in column 4, row 2
|===
ASCIIDOC
12/20/2018 Asciidoctor User Manual
https://asciidoctor.org/docs/user-manual/ 97/315
Result: Rendered table where cell was duplicated across three columns
Cell in column 1, row 1 Cell in column 2, row 1 Cell in column 3, row 1
Same cell content in columns 1, 2,
and 3
Same cell content in columns 1, 2,
and 3
Same cell content in columns 1, 2,
and 3
Cell in column 1, row 3 Cell in column 2, row 3 Cell in column 3, row 3
To have a cell span multiple, consecutive columns, prefix the | with the span factor and the + operator.
Cell spanning three columns
Result: Rendered table where cell spans three columns
Cell in column 1, row 1 Cell in column 2, row 1 Cell in column 3, row 1
Content in a single cell that spans columns 1, 2, and 3
Cell in column 1, row 3 Cell in column 2, row 3 Cell in column 3, row 3
If you want to have a cell span multiple, consecutive rows, prefix the span factor with a dot ( .).
Cell spanning two rows
Result: Rendered table where a cell spans two rows
Cell in column 1, row 1 Cell in column 2, row 1 Cell in column 3, row 1
Content in a single cell that spans
rows 2 and 3
Cell in column 2, row 2 Cell in column 3, row 2
Cell in column 2, row 3 Cell in column 3, row 3
Of course you can combine spanning over columns and rows. The number before the dot ( .) is the number of columns to span
and the number after the dot ( .) is the number of rows to span.
|===
|Cell in column 1, row 1 |Cell in column 2, row 1 |Cell in column 3, row 1
3*|Same cell content in columns 1, 2, and 3
|Cell in column 1, row 3
|Cell in column 2, row 3
|Cell in column 3, row 3
|===
ASCIIDOC
|===
|Cell in column 1, row 1 |Cell in column 2, row 1 |Cell in column 3, row 1
3+|Content in a single cell that spans columns 1, 2, and 3
|Cell in column 1, row 3
|Cell in column 2, row 3
|Cell in column 3, row 3
|===
ASCIIDOC
|===
|Cell in column 1, row 1 |Cell in column 2, row 1 |Cell in column 3, row 1
.2+|Content in a single cell that spans rows 2 and 3
|Cell in column 2, row 2
|Cell in column 3, row 2
|Cell in column 2, row 3
|Cell in column 3, row 3
|===
ASCIIDOC
12/20/2018 Asciidoctor User Manual
https://asciidoctor.org/docs/user-manual/ 98/315
Cell spanning columns and rows
Result: Rendered table where a cell spans over columns and rows
Column 1, row 1 Column 2, row 1 Column 3, row 1 Column 4, row 1
Column 1, row 2 Content in a single cell that spans over rows and
columns
Column 4, row 2
Column 1, row 3 Column 4, row 3
Column 1, row 4 Column 4, row 4
The alignment component for cells works the same as the column specifier alignment component.
Cells aligned horizontally, vertically, and across a span of three columns
Result: Rendered cells aligned horizontally, vertically, and across a span of three columns
Prefix the | with ^ to center
content horizontally
Prefix the | with < to align the
content to the left horizontally
Prefix the | with > to align the
content to the right horizontally
Prefix the | with a . and ^ to
center the content in the cell
vertically
Prefix the | with a . and < to
align the content to the top of the
cell
Prefix the | with a . and > to
align the content to the bottom of
the cell
This content spans three columns ( 3+ ) and is centered horizontally ( ^) and vertically ( .^ ) within the cell.
To use a pipe ( |) within the content of a cell without creating a new cell, you must use the {vbar} attribute.
The style component can also be applied to individual cells. For example, you can apply the AsciiDoc element styles to an
individual cell by prefixing the vertical bar with an a.
Comparing cells using AsciiDoc styles and no AsciiDoc styles
|===
|Column 1, row 1 |Column 2, row 1 |Column 3, row 1 |Column 4, row 1
|Column 1, row 2
2.3+|Content in a single cell that spans over rows and columns
|Column 4, row 2
|Column 1, row 3
|Column 4, row 3
|Column 1, row 4
|Column 4, row 4
|===
ASCIIDOC
[cols="3"]
|===
^|Prefix the `{vbar}` with `{caret}` to center content horizontally
<|Prefix the `{vbar}` with `<` to align the content to the left horizontally
>|Prefix the `{vbar}` with `>` to align the content to the right horizontally
.^|Prefix the `{vbar}` with a `.` and `{caret}` to center the content in the cell vertically
.<|Prefix the `{vbar}` with a `.` and `<` to align the content to the top of the cell
.>|Prefix the `{vbar}` with a `.` and `>` to align the content to the bottom of the cell
3+^.^|This content spans three columns (`3{plus}`) and is centered horizontally (`{caret}`) and vertically (`.{caret}`) wit
|===
ASCIIDOC
12/20/2018 Asciidoctor User Manual
https://asciidoctor.org/docs/user-manual/ 99/315
Result: Rendered table comparing cells using AsciiDoc styles and no AsciiDoc styles
This cell is prefixed with an a, so the processor
interpets the following lines as an AsciiDoc list.
List item 1
List item 2
List item 3
This cell is not prefixed with an a, so the processor
does not interpret the following lines as an AsciiDoc
list.
* List item 1 * List item 2 * List item 3
This cell is prefixed with an a, so the processor honors
the lead style on the following paragraph.
I am a paragraph styled with the lead
attribute.
This cell is not prefixed with an a, so the processor
does not honor the lead style on the following
paragraph.
[.lead] I am a paragraph styled with the lead attribute.
Source code listing can be placed inside cells by using the listing syntax.
Cells with source code listing
|===
|Source Code 1 |Source Code 2
a|
[source,python]
----
import os
print "%s" %(os.uname())
----
a|
[source,python]
----
import os
print ("%s" %(os.uname()))
----
|===
Result: Rendered table with cells containing source code listing
Source Code 1 Source Code 2
For the grand finale, let’s apply a variety of specifiers to individual cells.
[cols="2"]
|===
a|This cell is prefixed with an `a`, so the processor interpets the following lines as an AsciiDoc list.
* List item 1
* List item 2
* List item 3
|This cell *is not* prefixed with an `a`, so the processor does not interpret the following lines as an AsciiDoc list.
* List item 1
* List item 2
* List item 3
a|This cell is prefixed with an `a`, so the processor honors the `lead` style on the following paragraph.
[.lead]
I am a paragraph styled with the lead attribute.
|This cell *is not* prefixed with an `a`, so the processor does not honor the `lead` style on the following paragraph.
[.lead]
I am a paragraph styled with the lead attribute.
|===
ASCIIDOC
importimport os
printprint "%s" %(os.uname())
PYTHON
importimport os
printprint ("%s" %(os.uname()))
PYTHON
12/20/2018 Asciidoctor User Manual
https://asciidoctor.org/docs/user-manual/ 100/315
Building a variety of cell specifiers
Result: Rendered table featuring a variety of cell specifiers
This content is duplicated across two columns.
It is aligned right horizontally.
And it is monospaced.
This content is duplicated across two columns.
It is aligned right horizontally.
And it is monospaced.
This cell spans 3 rows. The content is centered
horizontally, aligned to the bottom of the cell, and
strong.
This content is emphasized.
This content is aligned to the top of the
cell and literal.
This cell contains a verse
that may one day expound on the
wonders of tables in an
epic sonnet.
23.4. Header Row
The first row of a table is promoted to a header row if the header option is set (either explicitly or implicitly).
You can enable the header option by adding the header keyword to the comma-separated list of values in the options attribute
on the table. You can also enable the header option by adding the %header directive to the table style (the first positional
attribute).
In the example below, the table has an attribute list containing an options attribute that includes the header option.
Table with the header value assigned to the options attribute
Result: Rendered table when the header value is assigned to the options attribute
Name of Column 1 Name of Column 2
Cell in column 1, row 1 Cell in column 2, row 1
Cell in column 1, row 2 Cell in column 2, row 2
|===
2*>m|This content is duplicated across two columns.
It is aligned right horizontally.
And it is monospaced.
.3+^.>s|This cell spans 3 rows. The content is centered horizontally, aligned to the bottom of the cell, and strong.
e|This content is emphasized.
.^l|This content is aligned to the top of the cell and literal.
v|This cell contains a verse
that may one day expound on the
wonders of tables in an
epic sonnet.
|===
ASCIIDOC
[cols=2*,options="header"]
|===
|Name of Column 1
|Name of Column 2
|Cell in column 1, row 1
|Cell in column 2, row 1
|Cell in column 1, row 2
|Cell in column 2, row 2
|===
ASCIIDOC
12/20/2018 Asciidoctor User Manual
https://asciidoctor.org/docs/user-manual/ 101/315
Alternately, you can define the header row based on how you layout the table. Asciidoctor use the following conventions to
determine when the first row should become the header row:
1. The first line of content inside the table block delimiters is not empty.
2. The second line of content inside the table block delimiters is empty.
3. The options attribute has not been specified in the block attributes (prior to 1.5.5).
As seen in the result of the example below, if all of these rules hold, then the first row of the table is treated as a header.
Table that has an implicit header row
Result: Rendered table when the header row was assigned implicitly
Name of Column 1 Name of Column 2
Cell in column 1, row 1 Cell in column 2, row 1
Cell in column 1, row 2 Cell in column 2, row 2
If you want to suppress this implicit behavior of promoting the first row to a header row, set the option value noheader (or add
the %noheader directive to the table style).
Notice that when the implicit method of assigning the header row is used, it’s not necessary to set the cols attribute. That’s
because the number of columns are determined by the number of cells in the first line if the cols attribute is absent.
We’re considering using a similar convention for enabling the footer in the future. Thus, if you rely on this
convention to enable the header row, it’s advised that you not put all the cells in the last row on the same line
unless you intend on making it the footer row.
23.5. Footer Row
The last row of a table can be styled as a footer by adding the footer keyword to the options attribute.
Result: Table rendered with a footer
Name of Column 1 Name of Column 2
Cell in column 1, row 1 Cell in column 2, row 1
Cell in column 1, row 2 Cell in column 2, row 2
Footer in column 1, row 3 Footer in column 2, row 3
23.6. Table Width
|===
|Name of Column 1 |Name of Column 2
|Cell in column 1, row 1
|Cell in column 2, row 1
|Cell in column 1, row 2
|Cell in column 2, row 2
|===
ASCIIDOC
[options="footer"]
|===
|Name of Column 1 |Name of Column 2
|Cell in column 1, row 1
|Cell in column 2, row 1
|Cell in column 1, row 2
|Cell in column 2, row 2
|Footer in column 1, row 3
|Footer in column 2, row 3
|===
ASCIIDOC
12/20/2018 Asciidoctor User Manual
https://asciidoctor.org/docs/user-manual/ 102/315
By default, a table will span the width of the content area. To constrain the width of the table to a fixed value, set the width
attribute in the table’s attribute list. The width is an integer percentage value ranging from 1 to 100. The % sign is optional.
Table with width set to 75%
Result: Table rendered with a width of 75%
Name of Column 1 Name of Column 2 Name of Column 3
Cell in column 1, row 1 Cell in column 2, row 1 Cell in column 3, row 1
Cell in column 1, row 2 Cell in column 2, row 2 Cell in column 3, row 2
Alternately, you can make the width fit the content by setting the autowidth option. The columns inherit this setting, so
individual columns will also be sized according to the content.
Table using autowidth
Result: The width of the table is sized to accomodate the automatic column widths
Name of Column 1 Name of Column 2 Name of Column 3
Cell in column 1, row 1 Cell in column 2, row 1 Cell in column 3, row 1
Cell in column 1, row 2 Cell in column 2, row 2 Cell in column 3, row 2
If you want each column to have an automatic width, but want the table to span the width of the content area, add the stretch
role to the table or set the width attribute to 100% .
Full-width table with autowidth columns
Result: Columns are sized to the content, but table spans the width of the page
Name of Column 1 Name of Column 2 Name of Column 3
[width=75%]
|===
|Name of Column 1 |Name of Column 2 |Name of Column 3
|Cell in column 1, row 1
|Cell in column 2, row 1
|Cell in column 3, row 1
|Cell in column 1, row 2
|Cell in column 2, row 2
|Cell in column 3, row 2
|===
ASCIIDOC
[%autowidth]
|===
|Name of Column 1 |Name of Column 2 |Name of Column 3
|Cell in column 1, row 1
|Cell in column 2, row 1
|Cell in column 3, row 1
|Cell in column 1, row 2
|Cell in column 2, row 2
|Cell in column 3, row 2
|===
ASCIIDOC
[%autowidth.stretch]
|===
|Name of Column 1 |Name of Column 2 |Name of Column 3
|Cell in column 1, row 1
|Cell in column 2, row 1
|Cell in column 3, row 1
|Cell in column 1, row 2
|Cell in column 2, row 2
|Cell in column 3, row 2
|===
ASCIIDOC
12/20/2018 Asciidoctor User Manual
https://asciidoctor.org/docs/user-manual/ 103/315
Name of Column 1 Name of Column 2 Name of Column 3
Cell in column 1, row 1 Cell in column 2, row 1 Cell in column 3, row 1
Cell in column 1, row 2 Cell in column 2, row 2 Cell in column 3, row 2
The autowidth option is not recognized by the DocBook converter.
If you want to apply autowidth only to certain columns, use the special value ~ as the width of the column. In this case, width
values are assumed to be a percentage value (i.e., 100-based).
Table with both fixed and autowidth columns
23.7. Table Borders
The borders on a table are controlled using the frame and grid attributes. You can combine these two attributes to achieve a
variety of border styles for your tables.
23.7.1. Frame
The border around a table is controlled using the frame attribute. By default, the frame attribute is assigned the all value,
which draws a border on each side of the table. If you set the frame attribute, you can override the default value with the values
topbot , sides or none .
The topbot value draws a border on the top and bottom of the table.
Result: Table rendered with frame=topbot
Name of Column 1 Name of Column 2 Name of Column 3
Cell in column 1, row 1 Cell in column 2, row 1 Cell in column 3, row 1
Cell in column 1, row 2 Cell in column 2, row 2 Cell in column 3, row 2
The sides value draws a border on the right and left side of the table.
Result: Table rendered with frame=sides
[cols="25h,~,~"]
|===
|small |as big as the column needs to be |the rest
|===
ASCIIDOC
[frame=topbot]
|===
|Name of Column 1 |Name of Column 2 |Name of Column 3
|Cell in column 1, row 1
|Cell in column 2, row 1
|Cell in column 3, row 1
|Cell in column 1, row 2
|Cell in column 2, row 2
|Cell in column 3, row 2
|===
ASCIIDOC
[frame=sides]
|===
|Name of Column 1 |Name of Column 2 |Name of Column 3
|Cell in column 1, row 1
|Cell in column 2, row 1
|Cell in column 3, row 1
|Cell in column 1, row 2
|Cell in column 2, row 2
|Cell in column 3, row 2
|===
ASCIIDOC
12/20/2018 Asciidoctor User Manual
https://asciidoctor.org/docs/user-manual/ 104/315
Name of Column 1 Name of Column 2 Name of Column 3
Name of Column 1 Name of Column 2 Name of Column 3
Cell in column 1, row 1 Cell in column 2, row 1 Cell in column 3, row 1
Cell in column 1, row 2 Cell in column 2, row 2 Cell in column 3, row 2
The none value removes the borders around the table.
Result: Table rendered with frame=none
Name of Column 1 Name of Column 2 Name of Column 3
Cell in column 1, row 1 Cell in column 2, row 1 Cell in column 3, row 1
Cell in column 1, row 2 Cell in column 2, row 2 Cell in column 3, row 2
23.7.2. Grid
The borders between the cells in a table are controlled using the grid attribute. By default, the grid attribute is assigned the all
value, which draws a border between all cells. If you set the grid attribute, you can override the default value with the values
rows , cols or none .
The rows value draws a border between the rows of the table.
Result: Table rendered with grid=rows
Name of Column 1 Name of Column 2 Name of Column 3
Cell in column 1, row 1 Cell in column 2, row 1 Cell in column 3, row 1
Cell in column 1, row 2 Cell in column 2, row 2 Cell in column 3, row 2
The cols value draws borders between the columns.
[frame=none]
|===
|Name of Column 1 |Name of Column 2 |Name of Column 3
|Cell in column 1, row 1
|Cell in column 2, row 1
|Cell in column 3, row 1
|Cell in column 1, row 2
|Cell in column 2, row 2
|Cell in column 3, row 2
|===
ASCIIDOC
[grid=rows]
|===
|Name of Column 1 |Name of Column 2 |Name of Column 3
|Cell in column 1, row 1
|Cell in column 2, row 1
|Cell in column 3, row 1
|Cell in column 1, row 2
|Cell in column 2, row 2
|Cell in column 3, row 2
|===
ASCIIDOC
12/20/2018 Asciidoctor User Manual
https://asciidoctor.org/docs/user-manual/ 105/315
Result: Table rendered with grid=cols
Name of Column 1 Name of Column 2 Name of Column 3
Cell in column 1, row 1 Cell in column 2, row 1 Cell in column 3, row 1
Cell in column 1, row 2 Cell in column 2, row 2 Cell in column 3, row 2
The none value removes all borders between the cells.
Result: Table rendered with grid=none
Name of Column 1 Name of Column 2 Name of Column 3
Cell in column 1, row 1 Cell in column 2, row 1 Cell in column 3, row 1
Cell in column 1, row 2 Cell in column 2, row 2 Cell in column 3, row 2
23.8. Striping
By default, the body rows are stripped (like a zebra). You can control this behavior using the stripes attribute on the table.
By default, the stripes attribute is assigned the even value, which shades even rows in the table body. The stripes attribute
accepts the following values:
even - even rows are shaded (default)
odd - odd rows are shaded
all - all rows are shaded
none - no rows are shaded
In the following example, the stripes are disabled.
[grid=cols]
|===
|Name of Column 1 |Name of Column 2 |Name of Column 3
|Cell in column 1, row 1
|Cell in column 2, row 1
|Cell in column 3, row 1
|Cell in column 1, row 2
|Cell in column 2, row 2
|Cell in column 3, row 2
|===
ASCIIDOC
[grid=none]
|===
|Name of Column 1 |Name of Column 2 |Name of Column 3
|Cell in column 1, row 1
|Cell in column 2, row 1
|Cell in column 3, row 1
|Cell in column 1, row 2
|Cell in column 2, row 2
|Cell in column 3, row 2
|===
ASCIIDOC
12/20/2018 Asciidoctor User Manual
https://asciidoctor.org/docs/user-manual/ 106/315
Under the covers, the stripes attribute applies the CSS class stripes-<value> (e.g., stripes-none ) to the table tag. As a
shorthand, you can simply apply the CSS class to the table directly using a role.
This feature relies on the necessary styles to be set in the stylesheet. The default stylesheet provides these styles.
23.9. Orientation
A table can be displayed in landscape (rotated 90 degrees counterclockwise) using the rotate option (preferred):
or the orientation attribute:
Currently, this is only implemented by the DocBook backend (it sets the attribute orient="land" ).
23.10. Nested Tables
Table cells marked with the AsciiDoc table style ( a) support nested tables in addition to normal block content. To distinguish the
inner table from the enclosing one, you need to use !=== as the table delimiter and a cell separator that differs from that used for
the enclosing table. The default cell separator for a nested table is !, though you can choose another character by defining the
separator attribute on the table.
Although nested tables are not technically valid in DocBook 5.0, the DocBook toolchain processes them anyway.
The following example contains a nested table in the last cell. Notice the nested table has its own format, independent of that of
the outer table:
[cols=3*, stripes=none]
|===
| A1
| B1
| C1
| A2
| B2
| C2
| A3
| B3
| C3
|===
ASCIIDOC
[.stripes-none,cols=3*]
|===
| A1
| B1
| C1
| A2
| B2
| C2
| A3
| B3
| C3
|===
ASCIIDOC
[%rotate]
|===
|a |b
|c |d
|===
ASCIIDOC
[orientation=landscape]
|===
|a |b
|c |d
|===
ASCIIDOC
12/20/2018 Asciidoctor User Manual
https://asciidoctor.org/docs/user-manual/ 107/315
Result: A nested table
Col 1 Col 2
Cell 1.1 Cell 1.2
Cell 2.1 Cell 2.2
Col1 Col2
C11 C12
We recommend using nested tables sparingly. There’s usually a better way to present the information.
23.11. Table Caption
If you specify a title on a table, the title will be used as part of the table’s caption. Adding a title also designates the table as a
formal table.
By default, the title of a formal table is prefixed with the label Table <n>. followed by a space, where <n> is the 1-based index
of all formal tables in the document.
Table 1. A table with a title
Name of Column 1 Name of Column 2
Cell in column 1, row 1 Cell in column 2, row 1
Cell in column 1, row 2 Cell in column 2, row 2
You can customize the caption label by specifying the caption attribute. If you want a space between the label and the title, you
must add a trailing space to the value of the caption attribute. (Don’t let the name of the attribute mislead you. The caption
attribute only sets the caption’s label, not the whole caption line).
[cols="1,2a"]
|===
| Col 1 | Col 2
| Cell 1.1
| Cell 1.2
| Cell 2.1
| Cell 2.2
[cols="2,1"]
!===
! Col1 ! Col2
! C11
! C12
!===
|===
ASCIIDOC
.A formal table
|===
|Name of Column 1 |Name of Column 2
|Cell in column 1, row 1
|Cell in column 2, row 1
|Cell in column 1, row 2
|Cell in column 2, row 2
|===
ASCIIDOC
12/20/2018 Asciidoctor User Manual
https://asciidoctor.org/docs/user-manual/ 108/315
Table A. A formal table
Name of Column 1 Name of Column 2
Cell in column 1, row 1 Cell in column 2, row 1
Cell in column 1, row 2 Cell in column 2, row 2
If you want to exclude the caption label altogether, simply assign a blank value to the caption attribute.
A formal table
Name of Column 1 Name of Column 2
Cell in column 1, row 1 Cell in column 2, row 1
Cell in column 1, row 2 Cell in column 2, row 2
Alternatively, you can disable the caption label for tables globally by undefining the table-caption document attribute.
23.12. Escaping the Cell Separator
The parser scans for the cell separator to divide the cells before it processes the cell text (no matter what that text contains, even
passthroughs). If your content includes the cell separator, you must escape that character using a leading backslash. Otherwise, it
will be interpreted as a cell separator. The backslash will be removed from the converted output.
Consider the following example:
This table will render as follows:
Result: Converted PSV table that contains pipe characters
The default separator in PSV tables is the | character. The | character is often referred to as a “pipe”.
Notice that the pipe character appears unescaped in the rendered result.
[caption="Table A. "]
.A formal table
|===
|Name of Column 1 |Name of Column 2
|Cell in column 1, row 1
|Cell in column 2, row 1
|Cell in column 1, row 2
|Cell in column 2, row 2
|===
ASCIIDOC
[caption=]
.A formal table
|===
|Name of Column 1 |Name of Column 2
|Cell in column 1, row 1
|Cell in column 2, row 1
|Cell in column 1, row 2
|Cell in column 2, row 2
|===
ASCIIDOC
:table-caption!:
ASCIIDOC
[cols=2*]
|====
|The default separator in PSV tables is the \| character.
|The \| character is often referred to as a "`pipe`".
|====
ASCIIDOC
12/20/2018 Asciidoctor User Manual
https://asciidoctor.org/docs/user-manual/ 109/315
Escaping the cell separator character can be tedious. There are also times when you can’t or don’t want to modify the content in
the table cell. To handle those cases, AsciiDoc allows you to override the cell separator. The cell separator is controlled using the
separator attribute on the table block. You’ll want to select a character that will never be used for content. A good candidate is the
broken bar, or ¦.
Here’s the previous example rewritten using a custom separator.
Notice that it’s no longer necessary to escape the pipe character in the content of the table cells.
23.13. Delimiter-Separated Values
Tables can also be populated from data formatted as delimiter-separated values (i.e., data tables). In contrast with the PSV format,
in which the delimiter is placed in front of each cell value, the delimiter in a delimiter-separated format (CSV, TSV, DSV) is placed
between the cell values (called a separator) and does not accept a cell formatting spec. Each line of data is assumed to represent a
single row, though you’ll learn that’s not a strict rule. How the table data gets interpreted is controlled by the format and
separator attributes on the table.
What the delimiter?
Aren’t comma-separated values a subset of delimiter-separated values (https://en.wikipedia.org/wiki/Delimiter-separated_values)? It
really depends on who you consult.
The term “delimiter-separated values” in this text refers to the family of data formats that use a delimiter, including comma-
separated values (CSV), tab-separated values (TSV) and delimited data (DSV), all of which are supported in AsciiDoc tables.
CSV is the data format used most often.
“Comma-separated values” is really a misleading term since CSV can use delimiters other than , as the field separator
(which, in this context, separates cells). What we’re really talking about is how the data is interpreted.
CSV and TSV both use a delimiter and an optional enclosing character, loosely based on RFC 4180
(https://tools.ietf.org/html/rfc4180). DSV (i.e., delimited data) only uses a delimiter, which can be escaped using a backslash; an
enclosing character is not recognized. These parsing rules are described in detail in Data Table Formats.
Let’s consider an example of using comma-separated values (CSV) to populate an AsciiDoc table with data. To instruct the
processor to read the data as CSV, set the value of the format attribute on the table to csv . When the format attribute is set to
csv , the default data separator is a comma ( ,), as seen in the table below.
Result: Rendered CSV table
Artist Track Genre
Baauer Harlem Shake Hip Hop
The Lumineers Ho Hey Folk Rock
This feature is particularly useful when you want to populate a table in your manuscript from data stored in a separate file. You
can do so using the include directive between the table delimiters, as shown here:
[cols=2*,separator=¦]
|====
¦The default separator in PSV tables is the | character.
¦The | character is often referred to as a "`pipe`".
|====
ASCIIDOC
[%header,format=csv]
|===
Artist,Track,Genre
Baauer,Harlem Shake,Hip Hop
The Lumineers,Ho Hey,Folk Rock
|===
ASCIIDOC
12/20/2018 Asciidoctor User Manual
https://asciidoctor.org/docs/user-manual/ 110/315
If your data is separated by tabs instead of commas, set the format to tsv (tab-separated values) instead.
Now let’s consider an example of using delimited data (DSV) to populate an AsciiDoc table with data. To instruct the processor to
read the data as DSV, set the value of the format attribute on the table to dsv . When the format attribute is set to dsv , the
default data separator is a colon ( :), as seen in the table below.
Result: Rendered DSV table
Artist Track Genre
Robyn Indestructable Dance
The Piano Guys Code Name Vivaldi Classical
23.13.1. Data Table Formats
The CSV and TSV data formats are parsed differently from the DSV data format. The following two sections outline those
differences.
CSV and TSV
Table data in either CSV or TSV format is parsed according to the following rules, loosely based on RFC 4180
(https://tools.ietf.org/html/rfc4180):
The default delimiter for CSV is a comma ( ,) while the default delimiter for TSV is a tab character.
Blank lines are skipped (unless enclosed in a quoted value).
Whitespace surrounding each value is stripped.
Values can be enclosed in double quotes ( ").
A quoted value may contain zero or more separator or newline characters.
A newline begins a new row unless the newline is enclosed in double quotes.
A quoted value may include the double quote character if escaped using another double quote ( "" ).
Newlines in quoted values are retained (as of 1.5.7).
If rows do not have the same number of cells (“ragged” tables), cells are shuffled to fully fill the rows.
This is different behavior than Excel, which pads short rows with empty cells.
Extra cells at the end of the last row get dropped.
As a rule of thumb, data for a single row should be on the same line.
DSV
Table data in DSV format is parsed according to the following rules:
The default delimiter for DSV is a colon ( :).
Blank lines are skipped.
Whitespace surrounding each value is stripped.
The delimiter character can be included in the value if escaped using a single backslash ( \: ).
If rows do not have the same number of cells (“ragged” tables), cells are shuffled to fully fill the rows.
23.13.2. Custom Delimiters
[%header,format=csv]
|===
include::tracks.csv[]
|===
ASCIIDOC
[%header,format=dsv]
|===
Artist:Track:Genre
Robyn:Indestructable:Dance
The Piano Guys:Code Name Vivaldi:Classical
|===
ASCIIDOC
12/20/2018 Asciidoctor User Manual
https://asciidoctor.org/docs/user-manual/ 111/315
Each data format has a default separator associated with it (csv = comma, tsv = tab, dsv = colon), but the separator can be changed
to any character (or even a string of characters) by setting the separator attribute on the table.
Here’s an example of a DSV table that uses a custom separator character (i.e., delimiter):
A DSV table with a custom separator
To make a TSV table, you can set the format attribute to csv and the separator to \t . Though the tsv
format is preferred.
The separator is independent of the processing rules for the format. If you set format=dsv and separator=, , the data will be
processed using the DSV rules, even though the data looks like CSV.
23.13.3. Shorthand Notation for Data Tables
Asciidoctor provides shorthand notation for specifying the data format of a table. The first position of the table block delimiter
(i.e., |=== ) can be replaced by a built-in delimiter to set the table format (e.g., ,=== for CSV).
To make a CSV table, you can use ,=== as the table block delimiter:
Result: Rendered CSV table using shorthand syntax
Artist Track Genre
Baauer Harlem Shake Hip Hop
To make a DSV table, you can use :=== as the table block delimiter:
Result: Rendered DSV table using shorthand syntax
Artist Track Genre
Robyn Indestructable Dance
When using either the CSV or DSV shorthand, you do not need to set the format attribute as it’s implied.
To make a TSV table, you can set the format attribute to tsv instead of having to set the format to csv and the separator to
\t . In this case, you can use either |=== or ,=== as the table block delimiter. There is no special delimited block notation for a
TSV table.
23.13.4. Formatting Cells in a Data Table
The delimited formats do not provide a way to express formatting of individual table cells. Instead, you can apply cell formatting
to all cells in a given column using the cols spec on the table:
[format=dsv,separator=;]
|===
a;b;c
d;e;f
|===
ASCIIDOC
,===
Artist,Track,Genre
Baauer,Harlem Shake,Hip Hop
,===
ASCIIDOC
:===
Artist:Track:Genre
Robyn:Indestructable:Dance
:===
ASCIIDOC
[format=csv,cols="1h,1a"]
|===
Sky,image::sky.jpg[]
Forest,image::forest.jpg[]
|===
ASCIIDOC
12/20/2018 Asciidoctor User Manual
https://asciidoctor.org/docs/user-manual/ 112/315
Data tables do not support cells that span multiple rows or columns, since that information can only be expressed at the cell level.
You are advised to use the PSV format if you need that functionality.
23.14. Summary
Table attributes and values
Attribute Description Value Description Notes
cols comma-separated list of
column specifiers
specifiers see Columns for details
format data format of the table’s
contents
psv cells are delimited by
separator (default |) (aka
prefix-separated values)
dsv cells are delimited by a colon
(:) (aka delimiter-separated
values)
csv cells are delimited by a
comma (,) (aka comma-
separated values)
tsv cells are delimited by a tab
character (aka tab-separated
values)
separator character used to separate
cells
|default for top-level tables
!default for nested tables
user-defined any sequence of literal
characters (e.g., ¦ or ][ ).
Ideally a pattern not found in
the cell content.
frame draws a border around the
table
all border on all sides (default)
topbot border on top and bottom
none no borders
sides border on left and right sides
grid draws boundary lines
between rows and columns
all draws boundary lines
around each cell (default)
cols draws boundary lines
between columns
rows draws boundary lines
between rows
none no boundary lines
align horizontally aligns table
within page width
left aligns to left side of page
(default)
Not yet implemented in
Asciidoctor. Applies to HTML
output only. The align and
float attributes are
mutually exclusive.
right aligns to right side of page
center horizontally aligns to center
of page
float floats the table to the
specified side of the page
left floats the table to the left side
of the page (default)
Applies to HTML output only.
Must be used in conjunction
with the table’s width
12/20/2018 Asciidoctor User Manual
https://asciidoctor.org/docs/user-manual/ 113/315
Attribute Description Value Description Notes
attribute to take effect. The
float and align attributes
are mutually exclusive.
right floats the table to the right
side of the page
halign horizontally aligns all of the
cell contents in a table
left aligns the contents of the
cells to the left (default)
Not implemented in
Asciidoctor. Define instead
using column or cell
specifiers (e.g., 3*>), which
take precedence over this
value.
right aligns the contents of the
cells to the right
center aligns the contents to the cell
centers
valign vertically aligns all of the cell
contents in a table
top aligns the cell contents to the
top of the cell (default)
Define instead using column
or cell specifiers (e.g., 3*.>),
which take precedence over
this value.
bottom aligns the cell contents to the
bottom of the cell
middle aligns the cell contents to the
middle of the cell
orientation rotates the table landscape rotated 90 degrees
counterclockwise
Equivalent to setting the
rotate option, which is
preferred. DocBook only.
options comma separated list of
option names
header promotes first row to the
table header
header and footer rows are
omitted by default
footer promotes last row to the
table footer
breakable allows the table to split
across a page (default)
Mutually exclusive. DocBook
only (specifically for
generating PDF output).
unbreakable prevents the table from
being split across a page
autowidth disables explicit column
widths (ignores cols
attribute)
rotate Prints the table in landscape Equivalent to setting the
orientation to landscape.
DocBook only.
width the table width relative to
the available page width
user defined
value
a percentage value between
0% and 100%
12/20/2018 Asciidoctor User Manual
https://asciidoctor.org/docs/user-manual/ 114/315
24. Horizontal Rules
Horizontal rule syntax
Result: Horizontal rule
24.1. Markdown-style horizontal rules
Asciidoctor recognizes Markdown horizontal rules. The motivation here is to ease migration of Markdown documents to AsciiDoc
documents.
To avoid conflicts with AsciiDoc’s block delimiter syntax, only 3 repeating characters ( - or *) are recognized. As with
Markdown, whitespace between the characters is optional.
Markdown-style horizontal rule syntax
Result: Markdown-style horizontal rules
A macro definition for the Markdown horizontal rules is included in the AsciiDoc compatibility file so they can be recognized by
the asciidoc command as well.
'''
ASCIIDOC
---
- - -
***
* * *
MARKDOWN
12/20/2018 Asciidoctor User Manual
https://asciidoctor.org/docs/user-manual/ 116/315
26. URLs
A Uniform Resource Link (URL) represents the location of a resource on the web. Typical URLs contain a scheme, domain name,
file name, and extension.
Asciidoctor recognizes the following common schemes without the help of any markup.
http
https
ftp
irc
mailto
email@email.com
You can think of these like implicit macro names. Since the URL in the example below begins with a protocol (in this case https
followed by a colon), Asciidoctor will automatically turn it into a hyperlink when it is processed.
1The trailing period will not get caught up in the link.
To prevent automatic linking of an URL, prepend it with a backslash ( \).
If you prefer URLs to be shown without a visible scheme, set the hide-uri-scheme attribute in the document’s header.
When the hide-uri-scheme attribute is set, the above URL will render as follows:
Note the absence of https inside the <a> element.
To attach a URL to text, enclose the text in square brackets at the end of the URL.
Additionally, you can format the linked text.
Rendered URLs
The homepage for the Asciidoctor Project is https://asciidoctor.org.
Chat with other Fedora users in the Fedora IRC channel.
Ask questions on the mailing list (http://discuss.asciidoctor.org/).
The homepage for the Asciidoctor Project is https://asciidoctor.org.
ASCIIDOC
1
:hide-uri-scheme:
https://asciidoctor.org
ASCIIDOC
<a href="https://asciidoctor.org">asciidoctor.org</a>
XML
Chat with other Fedora users in the irc://irc.freenode.org/#fedora[Fedora IRC channel].
ASCIIDOC
Ask questions on the http://discuss.asciidoctor.org/[*mailing list*].
ASCIIDOC
12/20/2018 Asciidoctor User Manual
https://asciidoctor.org/docs/user-manual/ 117/315
When a URL does not start with one of the common schemes, or the URL is not surrounded by word boundaries, you must use the
link macro. The link macro is a stronger version of a URI macro, which you can think of like an unconstrained macro. The
URL is preceded by link: and followed by square brackets. The square brackets may include optional link text. The URL is used
for the text of the link if link text is not specified. If the linkattrs document attribute is set, the square brackets also accepts
attributes, which allows a window name or role to be specified.
Anatomy of a link macro
Let’s consider a case where we need to use the link macro (instead of just a URI macro) to expand a link when it’s not adjacent to a
word boundary (i.e., unconstrained).
search/Ecosia (https://ecosia.org)
If we didn’t use the link: prefix in this case, the URL macro would not be detected by the parser.
Troubleshooting Complex URLs
A URL may not display correctly when it contains characters such as underscores ( _) or carets ( ^). This problem occurs
because the markup parser interprets parts of the URL (i.e., the link target) as valid text formatting markup. Most
lightweight markup languages have this issue because they don’t use a grammar-based parser. Asciidoctor plans to handle
URLs more carefully in the future (see issue #281 (https://github.com/asciidoctor/asciidoctor/issues/281)), which may be solved by
moving to a grammar-based parser (see issue #61 (https://github.com/asciidoctor/asciidoctor/issues/61)). Thankfully, there are
many ways to include URLs of arbitrary complexity using the AsciiDoc passthrough mechanisms.
Solution A
The simplest way to get a link to behave is to assign it to an attribute.
Asciidoctor won’t break links with underscores when they are assigned to an attribute because inline formatting
markup is substituted before attributes. The URL remains hidden while the rest of the document is being formatted
(strong, emphasis, monospace, etc).
Solution B
Another way to solve formatting glitches is to explicitly specify the formatting you want to have applied to a span of
text. This can be done by using the inline pass macro. If you want to display a URL, and have it preserved, put it inside
the pass macro and enable the macros substitution, which is what substitutes links.
The pass macro removes the URL from the document, applies the macros substitution to the URL, and then restores
the processed URL to its original location once the substitutions are complete on the whole document.
Alternatively, you can use ++ around the URL only. However, when you use this approach, Asciidoctor won’t
recognize it as a URL any more, so you have to use the explicit link prefix.
For more information, see issue #625 (https://github.com/asciidoctor/asciidoctor/issues/625).
link:url[optional link text, optional target attribute, optional role attribute]
ASCIIDOC
search/link:https://ecosia.org[Ecosia]
ASCIIDOC
= Document Title
:link-with-underscores: https://asciidoctor.org/now_this__link_works.html
This URL has repeating underscores {link-with-underscores}.
ASCIIDOC
This URL has repeating underscores pass:macros[https://asciidoctor.org/now_this__link_works.html].
ASCIIDOC
This URL has repeating underscores link:++https://asciidoctor.org/now_this__link_works.html++[].
ASCIIDOC
12/20/2018 Asciidoctor User Manual
https://asciidoctor.org/docs/user-manual/ 118/315
Next, we’ll add a target and role to a link macro.
Remember, when you use attributes in the link macro, you must also set the linkattrs document attribute in the header.
Asciidoctor does not parse attributes in the link macro by default. Once you’ve activated the linkattrs attribute, you can then
specify the name of the target window using the window attribute.
Let’s view the raw HTML of the Asciidoctor homepage.
Since _blank is the most common window name, we’ve introduced shorthand for it. Just end the link text with a caret ( ^):
If you use the caret syntax more than once in a single paragraph, you may need to escape the first occurrence
with a backslash.
When the linkattrs attribute is set, you can add a role (i.e., CSS class) to the link.
Chat with other Asciidoctor users on the mailing list (http://discuss.asciidoctor.org/).
Links with attributes (including the subject and body segments on mailto links) are a feature unique to
Asciidoctor. When they’re enabled, you must surround the link text in double quotes if it contains a comma.
26.1. Link to Relative Files
If you want to link to an external file relative to the current document, use the link macro in front of the file name.
If your file is an HTML file, you can link directly to a section in the document, append a hash ( #) followed by the section’s ID to
the end of the file name.
26.2. Summary
Link attributes and values
Attribute Value(s) Example Syntax Comments
linkattrs :linkattrs: Must be set in the header to parse link
macro attributes.
window blank http://discuss.asciidoctor.org[Discuss
Asciidoctor, window="_blank"]
The blank value can also be specified
using ^. Requires linkattrs .
window ^ http://example.org["Google, Yahoo,
Bing^"] and
http://discuss.asciidoctor.org[Discuss
Asciidoctor^]
Requires linkattrs.
= Asciidoctor Document Title
:linkattrs:
Let's view the raw HTML of the link:view-source:asciidoctor.org[Asciidoctor homepage, window="_blank"].
ASCIIDOC
Let's view the raw HTML of the link:view-source:asciidoctor.org[Asciidoctor homepage^].
ASCIIDOC
Chat with other Asciidoctor users on the http://discuss.asciidoctor.org/[*mailing list*^, role="green"].
ASCIIDOC
link:protocol.json[Open the JSON file]
ASCIIDOC
link:external.html#livereload[LiveReload]
ASCIIDOC
12/20/2018 Asciidoctor User Manual
https://asciidoctor.org/docs/user-manual/ 119/315
Attribute Value(s) Example Syntax Comments
role CSS classes
available to inline
elements
http://discuss.asciidoctor.org[Discuss
Asciidoctor, role="teal"]
Requires linkattrs.
id name of element,
custom link text
<<section-title,cross reference text>> Applies to cross references
12/20/2018 Asciidoctor User Manual
https://asciidoctor.org/docs/user-manual/ 120/315
27. Cross References
A link to another location within the current AsciiDoc document or in another AsciiDoc document is called a cross reference (also
referred to as an xref). To create a cross reference, you first need to define the location where the reference will point (i.e., the
anchor). Then, you need to use one of the forms of the inline xref macro to create a reference to that location. From there, you can
customize the text of the reference in various ways.
27.1. Automatic Anchors
It’s important to understand that many anchors are already defined for you. Using default settings, Asciidoctor automatically
creates an anchor for every section and discrete heading. It does so by generating an ID for that section (or discrete heading) and
registering that ID in the references catalog. You can then use that ID as the target of an cross reference.
For example, considering the following section.
Asciidoctor automatically assigns the ID _section_title to this section, which you can then use as the target of an xref to create
a reference to this section. You can also customize how this ID is generated. Refer to Auto-generated IDs for more information
about how Asciidoctor generates these IDs.
If you’re referring to a content element other than a section, you’ll need to define an anchor on that element explicitly. Read on to
learn how.
27.2. Dening an Anchor
An anchor (aka ID) can be defined almost anywhere: on a section title or discrete heading (automatic), on a paragraph, on a block
or inline image, on listing or literal block, on a phrase, and so forth. The anchor is declared by enclosing a valid ID name in double
square brackets or by using the shorthand ID syntax.
If you want to reference a block element, all you need to do is assign an ID to that block. You can enclose the ID in double square
brackets:
Assigning an ID to a paragraph
or use the ID shorthand syntax:
Assigning an ID to a paragraph using shorthand syntax
You can also define an anchor anywhere in content that receives normal substitutions (specifically the macro substitution). You
can enclose the ID in double square brackets:
Defining an inline anchor
or using the shorthand ID syntax.
Defining an inline anchor using shorthand syntax
In addition to being able to define anchors on sections and blocks, anchors can be defined inline where ever you can type normal
text (anchors are a macro substitution). The anchors in the text get replaced with invisible anchor points in the output.
For example, you would not put an anchor in front of a list item:
Wrong position for an anchor ID in front of a list item.
= Section Title
ASCIIDOC
[[notice]]
This paragraph gets a lot of attention.
ASCIIDOC
[#notice]
This paragraph gets a lot of attention.
ASCIIDOC
[[bookmark-a]]Inline anchors make arbitrary content referenceable.
ASCIIDOC
[#bookmark-b]#Inline anchors can be applied to a phrase like this one.#
ASCIIDOC
12/20/2018 Asciidoctor User Manual
https://asciidoctor.org/docs/user-manual/ 121/315
Instead, you would put it at the very start of the text of the list item:
Defining an inline anchor on a list item
Here’s how you can define the ID for a section using an inline anchor:
Defining the ID of a section using an inline anchor
To add additional anchors to a section, place them in front of the title.
Adding additional anchors to a section
If you add additional anchors to a section title, make sure you also assign an explicit ID to that section.
Otherwise, the anchor tag gets caught up in the generated ID. See #840
(https://github.com/asciidoctor/asciidoctor/issues/840) for details.
Remember that inline anchors are discovered where ever the macro substitution is applied (e.g., paragraph text). If text content
doesn’t belong somewhere, neither does an inline anchor point.
It’s possible to customize the text that will be used in the cross reference link (called xreflabel ). If not defined, Asciidoctor does
it best to find suitable text (the solution differs from case to case). In case of an image, the image caption will be used. In case of a
section header, the text of the section’s title will be used.
To define the xreflabel , add it in the anchor definition right after the ID (separated by a comma).
An anchor ID with a defined xreflabel. The caption will not be used as link text.
Instead of the bracket form, you can use the macro anchor to achieve the same goal.
Setting an anchor ID using the macro form
27.3. Internal Cross References
In Asciidoctor, the inline xref macro is used to create cross references (also called in-text or page citations) to content elements
(sections, blocks, or phrases) that have an ID (regardless of whether that ID is explicit or auto-generated).
You create a cross reference by enclosing the ID of the target block or section (or the path of another document with an optional
anchor) in double angled brackets.
Cross reference using the ID of the target section
Rendered cross reference using the ID of the target section
The section Images describes how to insert images into your document.
[[anchor-point]]* list item text
ASCIIDOC
* Fist item
* [[step2]]Second item
* Third item
ASCIIDOC
=== Version 4.9 [[version-4_9]]
ASCIIDOC
=== [[current]]Version 4.9 [[version-4_9]]
ASCIIDOC
[[tiger-image,Image of a tiger]]
.This image represents a Bengal tiger also called the Indian tiger
image::tiger.png[]
ASCIIDOC
anchor:tiger-image[Image of a tiger]
ASCIIDOC
The section <<images>> describes how to insert images into your document.
ASCIIDOC
12/20/2018 Asciidoctor User Manual
https://asciidoctor.org/docs/user-manual/ 122/315
You can also link to a block or section using the title by referencing its title, referred to as a natural cross reference. The title must
contain at least one space character or contain at least one uppercase letter. (If you are using Ruby < 2.4, that uppercase letter is
restricted to the basic Latin charset).
Cross reference using a section’s title
Rendered cross reference using a section’s title
Refer to Internal Cross References.
Converters usually use the reftext of the target as the default text of the link. When the document is parsed, attribute references
in the reftext are substituted immediately. When the reftext is displayed, additional reftext substitutions are applied to the text
(specialchars, quotes, and replacements).
You can override the reftext of the target by specifying alternative text at the location of the cross reference. After the ID, add a
comma and then enter the custom text you want the cross reference to display.
Cross reference with custom xreflabel text
Rendered cross reference using custom xreflabel text
Learn how to use attributes within the link macro.
You can also use the inline xref macro as an alternative to the double angled bracket form.
Inline xref macro
27.4. Validating Internal Cross References
Asciidoctor provides limited support for validating internal cross references. Validation occurs when a cross reference is first
visited. Since there are still some references aren’t stored in the parse tree (such as an anchor in the middle of a paragraph),
which can lead to false positives, these validations are hidden behind a flag.
You can enable validation of cross references from the CLI by passing the -v and from the API by setting the $VERBOSE variable
to true . This puts the processor in pedantic mode. In this mode, the parser will immediately validate cross references, issuing a
warning message if the reference is not valid.
Consider the following example:
If you run Asciidoctor in verbose/pedantic mode on this document, it will send the following warning message to the logger.
asciidoctor: WARNING: invalid reference: foobar
Asciidoctor only validates references within the same document (after includes are resolved).
27.5. Customizing the Cross Reference Text
Starting in Asciidoctor 1.5.6, when you use one of the native converters (HTML, PDF, and EPUB3), you can customize the style of
the automatic cross reference text using the xrefstyle document attribute. This customization brings the cross reference text
formatting from the DocBook toolchain to the native Asciidoctor converters.
By default, the cross reference text matches the title of the referenced element. For example, if you’re linking to a section titled
“Installation”, the text of the cross reference link appears as:
Refer to <<Internal Cross References>>.
ASCIIDOC
Learn how to <<link-macro-attributes,use attributes within the link macro>>.
ASCIIDOC
Learn how to xref:link-macro-attributes[use attributes within the link macro].
ASCIIDOC
See <<foobar>>.
[#foobaz]
== Foobaz
12/20/2018 Asciidoctor User Manual
https://asciidoctor.org/docs/user-manual/ 123/315
Installation
If the reftext attribute is specified on the referenced element, that value is preferred over its title. For example, let’s assume the
section from the previous example was written as:
In this case, the text of the cross reference link appears as:
Installation Procedure
Attribute references are substituted in the reftext during parsing and reftext substitutions (specialchars, quotes, and
replacements) are applied to the value when it’s used during conversion.
If the reftext is not specified, the text of the cross reference is automatically generated. By default, this text is the title of the
reference. There are three built-in styles you can choose from to customize the generated text of a cross reference, as controlled
by the xrefstyle document attribute.
:xrefstyle: full
Uses the signifier for the reference (e.g., Section) followed by the reference number and emphasized (chapter or appendix) or
quoted title (e.g., Section 2.3, “Installation” or Figure 1, “Big Cats”).
:xrefstyle: short
Uses the signifier for the reference (e.g., Section) followed by the reference number (e.g., Section 2.3 or Figure 1).
:xrefstyle: basic
Uses the title only (Installation or Big Cats), applying emphasis if the reference is a chapter or appendix.
This formatting only applies to references that have both a title and number (or explicit caption), but no explicit reftext. If the
reference is a chapter or an appendix, the title is displayed in italics instead of quotes (even when the xrefstyle is basic).
Let’s assume you want to reference a section titled “Installation” that has the number 2.3. The full style is displayed as:
Section 2.3, “Installation”
The short style is displayed as:
Section 2.3
The basic style is displayed as:
Installation
The full and short styles only apply for references that have a caption. Specifically, the corresponding -caption-caption attribute must
be set for the target’s block type (e.g., listing-caption for listing blocks, example-caption for example blocks, table-
caption for tables, etc.). Otherwise, the *basic style is used.
You can use document attributes to customize the signifier that is placed in front of the reference’s number. This reference
signifier indicates the reference’s type (e.g., Chapter or Section).
chapter-refsig — defines the signifier to use for a cross reference to a chapter (default: Chapter)
section-refsig — defines the signifier to use for a cross reference to a section (default: Section)
appendix-refsig — defines the signifier to use for a cross reference to an appendix (default: Appendix)
[reftext="Installation Procedure"]
=== Installation
ASCIIDOC
12/20/2018 Asciidoctor User Manual
https://asciidoctor.org/docs/user-manual/ 124/315
(The signifier attribute for a part cross reference will be introduced once numeration is supported for parts).
For example, to customize the word “Section”, define the section-refsig attribute in the document header:
The full xrefstyle would then be displayed as:
Sect. 2.3, “Installation”
The short xrefstyle would be displayed as:
Sect. 2.3
If you unset the attribute, the signifier is dropped from the cross reference text. For example:
In this case, the full xrefstyle will display only the number and title:
2.3, “Installation”
The short xrefstyle will fall back to the number only:
2.3
The basic xrefstyle is unaffected by the value of the signifier.
Only the aforementioned styles are provided out of the box. Support for a custom formatting string is planned. Refer to #2212
(https://github.com/asciidoctor/asciidoctor/issues/2212) for details. Until then, you can implement custom formatting in a custom
converter or overridding the xreftext method on the node.
27.6. Inter-document Cross References
The inline xref macro can also link to IDs in other AsciiDoc documents. This eliminates the need to use direct links between
documents that are coupled to a particular converter (e.g., HTML links). It also captures the intent of the author to establish a
reference to a section in another document.
Here’s how a cross reference is normally defined in Asciidoctor:
This cross reference creates a link to the section with the ID images.
Let’s assume the cross reference is defined in the document document-a.adoc. If the target section is in a separate document,
document-b.adoc, the author may be tempted to write:
However, this link is coupled to HTML output. What’s worse, if document-b.adoc is included in the same document as document-
a.adoc, the link will refer to a document that doesn’t even exist!
These problems can be alleviated by using an inter-document xref:
:section-refsig: Sect.
ASCIIDOC
:!section-refsig:
ASCIIDOC
The section <<images>> describes how to insert images into your document.
ASCIIDOC
Refer to link:document-b.html#section-b[Section B] for more information.
ASCIIDOC
Refer to <<document-b.adoc#section-b,Section B>> for more information.
ASCIIDOC
12/20/2018 Asciidoctor User Manual
https://asciidoctor.org/docs/user-manual/ 125/315
The ID of the target is now placed behind a hash symbol ( #). Preceding the hash is the name of the reference document (the file
extension is optional). We’ve also added a label since Asciidoctor cannot (yet) resolve the section title in a separate document.
When Asciidoctor generates the link for this cross reference, it first checks to see if document-b.adoc is included in the same
document as document-a.doc. If not, it will generate a link to document-b.html, intelligently substituting the original file extension
with the file extension of the output file.
If document-b.adoc is included in the same document as document-a.doc, then the document will be dropped in the link target and
look like the output of a normal cross reference:
Now you can create inter-document cross references without the headache.
27.6.1. Navigating Between Source Files
In certain environments, such as a source repository or the browser preview extensions, you view the generated HTML through
the AsciiDoc source URL. This has consequences for inter-document cross references.
Since the default suffix for relative links in the html5 backend is .html , the inter-document cross references in these
environments end up pointing to non-existent HTML files. In this case, you need to change the inter-document cross references to
refer to other AsciiDoc source files instead. You can achieve this behavior by setting the outfilesuffix attribute to the value as
.adoc , as the example below shows.
The links in the generated document will now point to README.adoc instead of the default, README.html.
This configuration is no longer necessary on GitHub since GitHub now sets the value of outfilesuffix to
match the file extension of the source file. However, it’s still required in GitHub-like environments such as
GitLab.
You probably don’t want to set outfilesuffix to .adoc without the ifdef condition as it could result in
Asciidoctor overwriting input files when you run it locally (though there’s some protection against this).
While outfilesuffix gives you control over the end of the resolved path for an inter-document cross reference, the
relfileprefix attribute gives you control over the beginning of the path. When resolving the path of an inter-document cross
reference, if the relfileprefix attribute is set, the value of this attribute gets prepended to the path. Let’s look at an example of
when these two attributes are used together.
A common practice in website architecture is to move files into their own folder to make the path format agnostic (called
“indexify”). For example, the path filename.html becomes filename/ (which targets filename/index.html). However, this is
problematic for inter-document cross references. Any cross reference that resolves to the path filename.html is now invalid since
the file has moved to a subfolder (and thus no longer a sibling of the referencing document).
To solve this problem, you can define the following two attributes:
Now, the cross reference <<filename#,Label>> will resolve to ../filename/ instead of filename.html. Since this change is specific
to the website architecture described, you want to be sure to only set these attributes in that particular environment (either using
an ifdef directive or via the API).
<a href="document-b.html#section-b">Section B</a>
HTML
<a href="#section-b">Section B</a>
HTML
= Document Title
ifdef::env-github,env-browser[:outfilesuffix: .adoc]
See the <<README#,README>>.
We could also write the link as link:README{outfilesuffix}[README].
ASCIIDOC
:relfileprefix: ../
:outfilesuffix: /
ASCIIDOC
12/20/2018 Asciidoctor User Manual
https://asciidoctor.org/docs/user-manual/ 126/315
28. Include Directive
The include directive provides a way to import content from another file into the current document. The include directive must
be placed on a line by itself with the following syntax, which is covered in detail in the next section.
When the document is processed, the include directive is replaced by the contents of the include file. Think of the include
directive like a file expander.
This directive is useful if you want to:
partition a large document into smaller files (for better organization and to make restructuring simpler),
insert snippets of source code (so your examples are kept up-to-date with the latest source files),
populate tables with output from other programs (e.g., CSV data),
create document variants by combining the include directive with preprocessor conditionals (e.g., ifdef ), and
reuse fragments and boilerplate content multiple times within the same document.
You can use the include directive as many times as you want in the same document.
The include directive is disabled when Asciidoctor is run in secure mode. In this mode, the include directive is
converted to a link in the output document. To learn more about secure mode, refer to the section Running
Asciidoctor Securely.
28.1. Anatomy
The include directive has the following anatomy:
The leveloffset, lines, tag(s) and indent attributes are optional, making the simplest case look like:
The sections that follow go into detail about when the include is processed, how the include file is resolved, and how each
attribute is used.
28.2. Processing
Although the include directive looks like a block macro, it’s not a macro and therefore not processed like one. Instead, it’s a
preprocessor directive, just like ifdef and ifeval . It’s important to understand the distinction.
A preprocessor directive is processed when the lines are read, but before the document structure is parsed. Therefore, it’s not
aware of the surrounding document structure. A preprocessor directive merely adds lines to the reader or takes lines away. The
include directive is a preprocessor directive that always adds lines.
The best way to think of the include directive is to imagine that it is being replaced by the lines from the include file (i.e., the
imported lines). Only then does the parser read and interpret those lines. That’s also why it’s important to surround the include
directive by blank lines if it imports in a discrete structure. You only want to place include files directly adjacent to one another if
the imported content should be directly adjacent.
If you don’t want the include directive to be processed, you must escape it using a backslash.
\include::just-an-example.ext[]
Escaping the directive is necessary even if it appears in a verbatim block since it’s not aware of the surrounding document
structure.
28.3. File resolution
include::path[<attrlist>]
include::path[leveloffset=
offset
,lines=
ranges
,tag(s)=
name(s)
,indent=
depth
]
ASCIIDOC
include::content.adoc[]
ASCIIDOC
12/20/2018 Asciidoctor User Manual
https://asciidoctor.org/docs/user-manual/ 127/315
The path used in an include directive may be either relative or absolute.
If the path relative, the processor resolves the path using the following rules:
If the include directive is used in the main (top-level) document, relative paths are resolved relative to the base directory. (The
base directory defaults to the directory of the main document and can be overridden from the CLI or API).
If the include directive is used in a file that has itself been included, the path is resolved relative to the including (i.e., current)
file.
These defaults makes it easy to reason about how the path to the include file is resolved.
If the processor cannot locate the file (perhaps because you mistyped the path), you’ll still be able to convert the document.
However, you will get the following warning message during conversion:
asciidoctor: WARNING: master.adoc: line 3: include file not found: /.../content.adoc
The following message will also be inserted into the output:
Unresolved directive in master.adoc - include::content.adoc[]
To fix the problem, edit the file path and run the converter again.
If you store your AsciiDoc files in nested folders at different levels, relative file paths can quickly become awkward and inflexible.
A common pattern to help here is to define the paths in attributes defined in the header, then prefix all include paths with a
reference to one of these attributes:
Keep in mind that no matter how Asciidoctor resolves the path to the file, access to that file is limited by the safe mode setting
under which Asciidoctor is run. If a path violates the security restrictions, it may be truncated.
28.4. Partitioning large documents and using leveloset
When your document gets large, you can split it up into subsections for easier editing as follows:
Note the blank lines before and after the include directives. This practice is recommended whenever including
AsciiDoc content to avoid unexpected results (e.g., a section title getting interpreted as a line at the end of a
previous paragraph).
The leveloffset attribute can help here by pushing all headings in the included document down by the specified number of levels.
This allows you to publish each chapter as a standalone document (complete with a document title), but still be able to include the
chapters into a master document (which has its own document title).
You can easily assemble your book so that the chapter document titles become level 1 headings using:
:includedir: _includes
:sourcedir: ../src/main/java
include::{includedir}/fragment1.adoc[]
[source,java]
----
include::{sourcedir}/org/asciidoctor/Asciidoctor.java[]
----
= My book
include::chapter01.adoc[]
include::chapter02.adoc[]
include::chapter03.adoc[]
12/20/2018 Asciidoctor User Manual
https://asciidoctor.org/docs/user-manual/ 128/315
Because the leveloffset is relative (it begins with + or -), this works even if the included document has its own includes and
leveloffsets.
If you have lots of chapters to include and want them all to have the same offset, you can save some typing by setting leveloffset
around the includes:
The final line returns the leveloffset to 0.
Alternatively, you could use absolute levels:
Relative levels are preferred. Absolute levels become awkward when you have nested includes since they aren’t context aware.
28.5. AsciiDoc vs non-AsciiDoc les
The include directive performs a simple file merge, so it works with any text file. The content of all included content is
normalized. This means that the encoding is forced to UTF-8 (or converted from UTF-16 to UTF-8 if the file contains a BOM) and
trailing whitespace and endlines are removed from each line and replaced with a Unix line feed. This normalization is important
to how Asciidoctor works.
If the file is recognized as an AsciiDoc file (i.e., it has one of the following extensions: .asciidoc , .adoc , .ad , .asc , or .txt ),
Asciidoctor runs the preprocessor on the lines, looking for and interpreting the following directives:
includes
preprocessor conditionals (e.g., ifdef )
This allows includes to be nested, and provides lot of flexibility in constructing radically different documents with a single master
document and a few command line attributes.
Including non-AsciiDoc files is normally done to merge output from other programs or populate table data:
In this case, the include directive does not do any processing of AsciiDoc directives. The content is inserted as is (after being
normalized).
28.6. Select Portions of a Document to Include
= My Book
include::chapter01.adoc[leveloffset=+1]
include::chapter02.adoc[leveloffset=+1]
include::chapter03.adoc[leveloffset=+1]
= My book
:leveloffset: +1
include::chapter01.adoc[]
include::chapter02.adoc[]
include::chapter03.adoc[]
:leveloffset: -1
:leveloffset: 1
//includes
:leveloffset: 0
.2016 Sales Results
,===
include::sales/2016/results.csv[]
,===
12/20/2018 Asciidoctor User Manual
https://asciidoctor.org/docs/user-manual/ 129/315
The include directive supports selecting only portions of the document to include. Using the tags attribute (or tag attribute for
the singular case), you can select lines that fall between regions marked with user-defined tags. Using the lines attribute, you
can include ranges of line numbers.
When including multiple line ranges or multiple tags, each entry in the list must be separated by either a comma or a semi-colon.
If commas are used, the entire value must be enclosed in quotes. Using the semi-colon as the data separator eliminates this
requirement.
28.6.1. By tagged regions
Tags are useful when you want to display specific regions of content from an include file instead of all of its content. You can
select regions of content between tag/end directives using the tags attribute. The example below shows how you tag a region of
content inside a file containing multiple code examples.
Tagged code snippets in a file named core.rb
1To indicate the start of a tagged region, insert a comment line in the code.
2Assign a unique name to the tag directive. In this example the tag is called timings.
3Insert another comment line where you want the tagged region to end.
4Assign the name of the region you want to terminate to the end directive.
5This is the start a tagged snippet named parse.
6This is the end of the tagged snippet named parse.
The tag::[] and end::[] directives should be placed after a line comment as defined by the language of the
source file. The directives must also appear at the end of the line. In the previous example, we choose to prefix
the lines with a hash ( #) because that’s the start of a line comment in Ruby.
For languages that only have circumfix comments, such as XML, you can enclose the tag and end directives in
the respective circumfix comment markers. For example, in XML files, you can use <!-- tag::name[] -->
and <!-- end::name[] --> (the spaces around the tag are required).
In the next example, the tagged region named parse is selected by the include directive.
Selecting the parse code snippet from a document
1In the directive’s brackets, set the tag attribute and assign it the unique name of the code snippet you tagged in your
code file.
You can include multiple tags from the same file.
Selecting the timings and the parse code snippets from a document
It is also possible to have fine-grained tagged regions inside larger tagged regions.
# tag::timings[]
ifif timings
timings.record :read
timings.start :parse
endend
# end::timings[]
# tag::parse[]
doc = (options[:parse] == false ? (Document.new lines, options) :
(Document.new lines,options).parse)
timings.record :parse ifif timings
doc
# end::parse[]
RUBY
1 2
3 4
5
6
[source,ruby]
----
include::core.rb[tag=parse]
----
ASCIIDOC
1
[source,ruby]
----
include::core.rb[tags=timings;parse]
----
ASCIIDOC
12/20/2018 Asciidoctor User Manual
https://asciidoctor.org/docs/user-manual/ 130/315
For example, if your include file has the following content:
And you include this file using the following include directive:
The following lines will be selected and displayed:
Notice that none of the lines with the tag directives are displayed.
28.6.2. Tag ltering
The previous section showed how to select tagged regions explicitly, but you can also use wildcards and exclusions:
*
Select all tagged regions.
**
Select all the lines in the document (excluding lines containing a tag directive).
!
Negate the match.
The wildcards are applied first, then the exclusions are applied. Technically, the order you list them doesn’t matter, but it’s
customary to list them in this order.
Here are some of the permutations that you can use:
** — selects all the lines in the document; matches the default behavior of the include directive, except lines containing a tag
directive; shorthand for **;* when used alone
* — selects all tagged regions in the document.
**;* — selects all the lines outside and inside of tagged regions, but not the lines containing a tag directive.
foo;!bar — selects regions tagged foo, but excludes any nested regions tagged bar.
*;!foo — selects all tagged regions, but excludes any regions tagged foo (nested or otherwise).
**;!foo — selects all the lines of the document except for regions tagged foo.
**;!* — selects only the regions of the document outside of tags (i.e., non-tagged regions).
There are also some shorthands if only exclusions are specified:
!foo — equivalent to **;!foo ; an exclusion without an inclusion implicitly starts by selecting all the lines.
!* — equivalent to **;!* ; only selects regions that are not tagged.
28.6.3. By line ranges
To include content by line range, assign a starting line number and an ending line number separated by a pair of dots (e.g.,
lines=1..5 ) to the lines attribute.
// tag::snippets[]
// tag::snippet-a[]
snippet a
// end::snippet-a[]
// tag::snippet-b[]
snippet b
// end::snippet-b[]
// end::snippets[]
ASCIIDOC
include::file-with-snippets.adoc[tag=snippets]
ASCIIDOC
snippet a
snippet b
ASCIIDOC
include::filename.txt[lines=5..10]
ASCIIDOC
12/20/2018 Asciidoctor User Manual
https://asciidoctor.org/docs/user-manual/ 131/315
You can specify multiple ranges by separating each range by a comma. Since commas are normally used to separate individual
attributes, you must quote the comma-separated list of ranges.
To avoid having to quote the list of ranges, you can instead separate them using semi-colons.
If you don’t know the number of lines in the document, or you don’t want to couple the range to the length of the file, you can
refer to the last line of the document using the value -1.
28.7. Normalize Block Indentation
Source code snippets from external files are often padded with a leading block indent. This leading block indent is relevant in its
original context. However, once inside the documentation, this leading block indent is no longer needed.
The attribute indent allows the leading block indent to be stripped and, optionally, a new block indent to be set for blocks with
verbatim content (listing, literal, source, verse, etc.).
When indent is 0, the leading block indent is stripped
When indent is > 0, the leading block indent is first stripped, then the content is indented by the number of columns equal to
this value.
If the tabsize attribute is set on the block or the document, tabs are also replaced with the number of spaces specified by that
attribute, regardless of whether the indent attribute is set.
For example, this AsciiDoc source:
Produces:
def names
@name.split ' '
end
This AsciiDoc source:
[indent=2]
----
def names
@name.split ' '
end
----
Produces:
28.8. Include Content from a URI
The include directive recognizes when the target is a URI and can include the content referenced by that URI.
include::filename.txt[lines="1..10,15..20"]
ASCIIDOC
include::filename.txt[lines=7;14..25;28..43]
ASCIIDOC
include::filename.txt[lines=12..-1]
ASCIIDOC
[source,ruby,indent=0]
----
def names
@name.split ' '
end
----
ASCIIDOC
def names
@name.split ' '
end
12/20/2018 Asciidoctor User Manual
https://asciidoctor.org/docs/user-manual/ 132/315
Including content from a URI
This example demonstrates how to include an AsciiDoc file from a GitHub repo directly into your document.
For security reasons, this capability is not enabled by default. To allow content to be read from a URI, you must enable the URI
read permission by:
1. running Asciidoctor in SERVER mode or less and
2. setting the allow-uri-read attribute securely (i.e., from the CLI or API).
Here’s an example that shows how to run Asciidoctor from the console so it can read content from a URI:
$ asciidoctor -a allow-uri-read filename.adoc
Remember that Asciidoctor executes in SAFE mode by default when run from the command line.
Here’s an example that shows how to run Asciidoctor from the API so it can read content from a URI:
Including content from sources outside your control carries certain risks, including the potential to introduce
malicious behavior into your documentation. Because allow-uri-read is a potentially dangerous feature, it is
forcefully disabled when the safe mode is SECURE or higher.
URI vs URL
URI stands for Uniform Resource Identifier (https://en.wikipedia.org/wiki/Uniform_Resource_Identifier). When we talk about a URI,
we’re usually talking about a URL, or Uniform Resource Locator. A URL is simply a URI that points to a resource over a
network, or web address.
As far as Asciidoctor is concerned, all URIs share the same restriction, whether or not it’s actually local or remote, or
whether it points to a web address (http or https prefix), FTP address (ftp prefix), or some other addressing scheme.
The same restriction described in this section applies when embedding an image referenced from a URI, such as when data-uri
is set or when converting to PDF using Asciidoctor PDF.
28.9. Caching URI Content
Reading content from a URI is obviously much slower than reading it from a local file.
Asciidoctor provides a way for the content read from a URI to be cached, which is highly recommended.
To enable the built-in cache, you must:
1. Install the open-uri-cached gem.
2. Set the cache-uri attribute in the document.
When these two conditions are satisfied, Asciidoctor caches content read from a URI according the to HTTP caching
recommendations (https://www.w3.org/Protocols/rfc2616/rfc2616-sec13.html).
28.10. Include a File Multiple Times in the Same Document
A document can include the same file any number of times. The problem comes if there are IDs in the included file; the output
document (HTML or DocBook) will then have duplicate IDs which will make it not well-formed. To fix this, you can reference a
dynamic variable from the main document in the ID.
For example, let’s say you want to include the same subsection describing a bike chain in both the operation and maintenance
chapters:
include::https://raw.githubusercontent.com/asciidoctor/asciidoctor/master/README.adoc[]
ASCIIDOC
Asciidoctor.convert_file 'filename.adoc', safe: :safe, attributes: { 'allow-uri-read' => '' }
RUBY
12/20/2018 Asciidoctor User Manual
https://asciidoctor.org/docs/user-manual/ 133/315
Write fragment-chain.adoc as:
The first time the fragment-chain.adoc file is included, the ID of the included section resolves to chain-operation . The second
time the file included, the ID resolves to chain-maintenance .
In order for this to work, you must use the long-hand forms of both the ID assignment and the cross-reference. The single quotes
around the variable name in the assignment are required to force variable substitution (aka interpolation).
= Bike Manual
:chapter: operation
== Operation
include::fragment-chain.adoc[]
:chapter: maintenance
== Maintenance
include::fragment-chain.adoc[]
[id='chain-{chapter}']
=== Chain
See xref:chain-{chapter}[].
12/20/2018 Asciidoctor User Manual
https://asciidoctor.org/docs/user-manual/ 134/315
29. Images
To include an image on its own line (i.e., a block image), use the image:: prefix in front of the file name and square brackets
after it.
If you want to specify alt text, include it inside the square brackets:
You can also give the image an id, a title, set its dimensions and make it a link.
1Assigns an ID to the block; see Defining an Anchor.
2Defines the title of the block image, which gets displayed underneath the image when rendered.
3link makes the image a link (this can also be defined inside the attribute list of the block macro)
4The first positional attribute, Sunset, is the image’s alt text.
5The second and third positional attributes define the width and height, respectively.
A hyperlinked image with caption
(https://www.flickr.com/photos/javh/5448336655)
Figure 1: A mountain sunset
image::sunset.jpg[]
ASCIIDOC
image::sunset.jpg[Sunset]
ASCIIDOC
[#img-sunset]
.A mountain sunset
[link=https://www.flickr.com/photos/javh/5448336655]
image::sunset.jpg[Sunset,300,200]
ASCIIDOC
1
2
3
4 5
12/20/2018 Asciidoctor User Manual
https://asciidoctor.org/docs/user-manual/ 135/315
Block images are prefixed by a caption label (Figure) and number automatically. To turn off figure caption labels and numbers,
add the figure-caption attribute to the document header and unset it.
:figure-caption!:
If you want to include an image inline, use the image: prefix instead (notice there is only one colon):
Click to get the party started.
Click when you need a break.
For inline images, the optional title is displayed as a tooltip.
29.1. Setting the Location of Images
The path to the location of images is controlled by the imagesdir document attribute. The value of this attribute (empty by
default) is added to the beginning of every image target. Therefore, you never need to reference this attribute. You only need to set
it.
Incorrect
Correct
The resolved location of the image will be: <imagesdir> + <target>.
The benefit of the processor adding the value of the imagesdir attribute the the start of all image targets is that you can globally
control the folder where images are located per converter. We refer to this folder as the image catalog. Since different output
formats require the images to be in different locations, this attribute makes it possible to accomodate many different scenarios.
We recommend relying on the imagesdir attribute when defining the target of your image to avoid hard-coding that common
path in every single image macro. Always think about where the image is relative to the image catalog.
The imagesdir attribute value can be an absolute path, relative path or URI. By default, the value of the imagesdir attribute is
empty, which means these images are resolved relative to the document. If the image target is an absolute path or URI, the
imagesdir prefix is not added to the path.
You can set the imagesdir attribute in multiple places in your document, as long as it is not locked by the API.
This technique is useful if you store images for different parts, chapters, or sections of your document in
different locations.
29.1.1. Include Images by Full URL
Asciidoctor supports remote (i.e., images with a URL target) block and inline images. You can reference images served from any
URL (e.g., your blog, an image hosting service, your docs server, etc.) and never have to worry about downloading the images and
putting them somewhere locally.
Here are a few examples of images that have a URL target:
Block image with a URL target
Click image:icons/play.png[Play, title="Play"] to get the party started.
Click image:icons/pause.png[title="Pause"] when you need a break.
ASCIIDOC
image::{imagesdir}/name-of-image.png[]
ASCIIDOC
image::name-of-image.png[]
ASCIIDOC
image::https://upload.wikimedia.org/wikipedia/commons/3/35/Tux.svg[Tux,250,350]
ASCIIDOC
12/20/2018 Asciidoctor User Manual
https://asciidoctor.org/docs/user-manual/ 136/315
Inline image with a URL target
You can find everywhere these days.
The value of imagesdir is ignored when the image target is a URI.
If you want to avoid typing the URL prefix for every image, and all the images are located on the same server, you can use the
imagesdir attribute to set the base URL:
Using a URL as the base URL for images
This time, the imagesdir is used since the image target is not a URL (the imagesdir just happens to be one).
This feature is included in the AsciiDoc compatibility file so that AsciiDoc gets it right too.
29.2. Putting Images in Their Place
Images are a great way to enhance the text, whether to illustrate an idea, show rather than tell, or just help the reader connect
with the text.
Out of the box, images and text behave like oil and water. Images don’t like to share space with text. They are kind of “pushy”
about it. That’s why we focused on tuning the controls in the image macros so you can get the images and the text to flow
together.
There are two approaches you can take when positioning your images:
1. Named attributes
2. Roles
29.2.1. Positioning attributes
Asciidoctor supports the align attribute on block images to align the image within the block (e.g., left, right or center). The
named attribute float can be applied to both the block and inline image macros. Float pulls the image to one side of the page or
the other and wraps block or inline content around it, respectively.
You can find image:https://upload.wikimedia.org/wikipedia/commons/3/35/Tux.svg[Linux,25,35] everywhere these days.
ASCIIDOC
:imagesdir-old: {imagesdir}
:imagesdir: https://upload.wikimedia.org/wikipedia/commons
image::3/35/Tux.svg[Tux,250,350]
:imagesdir: {imagesdir-old}
ASCIIDOC
12/20/2018 Asciidoctor User Manual
https://asciidoctor.org/docs/user-manual/ 137/315
Here’s an example of a floating block image. The paragraphs or other blocks that follow the image will float up into the available
space next to the image. The image will also be positioned horizontally in the center of the image block.
A block image pulled to the right and centered within the block
Here’s an example of a floating inline image. The image will float into the upper-right corner of the paragraph text.
An inline image pulled to the right of the paragraph text
When you use the named attributes, CSS gets added inline (e.g., style="float: left" ). That’s bad practice because it can make
the page harder to style when you want to customize the theme. It’s far better to use CSS classes for these sorts of things, which
map to roles in AsciiDoc terminology.
29.2.2. Positioning roles
Here are the examples from above, now configured to use roles that map to CSS classes in the default Asciidoctor stylesheet:
Block image macro using positioning roles
Inline image macro using positioning role
The following table lists all the roles available out of the box for positioning images.
Roles for positioning images
Float Align
Role left right text-left text-right text-center
Block Image
Inline Image
Merely setting the float direction on an image is not sufficient for proper positioning. That’s because, by default, no space is left
between the image and the text. To alleviate this problem, we’ve added sensible margins to images that use either the positioning
named attributes or roles.
If you want to customize the image styles, perhaps to customize the margins, you can provide your own additions to the
stylesheet (either by using your own stylesheet that builds on the default stylesheet or by adding the styles to a docinfo file).
The shorthand syntax for a role ( .) can not yet be used with image styles.
29.2.3. Framing roles
It’s common to frame the image in a border to further offset it from the text. You can style any block or inline image to appear as a
thumbnail using the thumb role (or th for short).
The thumb role doesn’t alter the dimensions of the image. For that, you need to assign the image a height and
width.
Here’s a common example for adding an image to a blog post. The image floats to the right and is framed to make it stand out
more from the text.
image::tiger.png[Tiger,200,200,float="right",align="center"]
ASCIIDOC
image:linux.png[Linux,150,150,float="right"]
You can find Linux everywhere these days!
ASCIIDOC
[.right.text-center]
image::tiger.png[Tiger,200,200]
ASCIIDOC
image:sunset.jpg[Sunset,150,150,role="right"] What a beautiful sunset!
ASCIIDOC
image:logo.png[role="related thumb right"] Here's text that will wrap around the image to the left.
ASCIIDOC
12/20/2018 Asciidoctor User Manual
https://asciidoctor.org/docs/user-manual/ 138/315
Notice we added the related role to the image. This role isn’t technically required, but it gives the image semantic meaning.
29.2.4. Control the oat
When you start floating images, you may discover that too much content is floating around the image. What you need is a way to
clear the float. That is provided using another role, float-group .
Let’s assume that we’ve floated two images so that they are positioned next to each other and we want the next paragraph to
appear below them.
When this example is converted, then viewed a browser, the paragraph text appears to the right of the images. To fix this
behavior, you just need to “group” the images together in a block with self-contained floats. Here’s how it’s done:
This time, the text will appear below the images where we want it.
29.3. Sizing Images
Since images often need to be sized according to the medium, there are several ways to specify an image size.
In most output formats, the specified width is obeyed unless the image would exceed the content width or height, in which case it
scaled to fit while maintaining the original aspect ratio (i.e., responsive scaling).
29.3.1. width and height
The primary way to specify the size of an image is to define the width and height attributes on the image macro. Since these
two attributes are so common, they are the second and third (unnamed) positional attributes on the image macros.
That’s equivalent to the long-hand version:
While the values of width and height can be used to scale the image, these attributes are primarily intended to specify the
intrinsic (or faux-intrinsic, aka too-lazy-to-resize) size of the image in CSS pixels.[1] The width and height attributes are
mapped to attributes of the same name on the <img> element in the HTML output. These attributes are important because they
provide a hint to the browser to tell it how much space to reserve for the image during layout to minimize page reflows.
Automatic image scaling
The default Asciidoctor stylesheet implements responsive images (using width-wise scaling). If the width of the screen is
smaller than the width of the image, the image will be scaled down to fit. To support this feature, the original aspect ratio of
the image is preserved at all sizes. Thus, when you set the dimensions, the values should reflect the original aspect ratio of
the image as this will be enforced. If the values don’t match the aspect ratio, the height is ignored by the browser.
[.left]
.Image A
image::a.png[A,240,180]
[.left]
.Image B
image::b.png[B,240,180,title="Image B"]
Text below images.
ASCIIDOC
[.float-group]
--
[.left]
.Image A
image::a.png[A,240,180]
[.left]
.Image B
image::b.png[B,240,180]
--
Text below images.
ASCIIDOC
image::flower.jpg[Flower,640,480]
ASCIIDOC
image::flower.jpg[alt=Flower,width=640,height=480]
ASCIIDOC
12/20/2018 Asciidoctor User Manual
https://asciidoctor.org/docs/user-manual/ 139/315
29.3.2. pdfwidth
Asciidoctor recognizes the following attributes to size images when converting to PDF using Asciidoctor PDF:
pdfwidth - The preferred width of the image in the PDF when converting using Asciidoctor PDF.
The pdfwidth attribute accepts the following units:
px Output device pixels (assumed to be 96 dpi)
pt (or none) Points (1/72 of an inch)
pc Picas (1/6 of an inch)
cm Centimeters
mm Millimeters
in Inches
%Percentage of the content width (area between margins)
vw Percentage of the page width (edge to edge)
If pdfwidth is not provided, Asciidoctor PDF also accepts scaledwidth , or width (no units, assumed to be pixels), in that order.
See image scaling in Asciidoctor PDF (https://github.com/asciidoctor/asciidoctor-pdf#image-scaling) for more details.
29.3.3. scaledwidth
Asciidoctor recognizes the following attributes to size images when converting to PDF using the DocBook toolchain:
scaledwidth - The preferred width of the image when converting to PDF using the DocBook toolchain. (mutually exclusive
with scale)
scale - Scales the original image size by this amount when converting to PDF using the DocBook toolchain (mutually
exclusive with scaledwidth).
scaledwidth sizes images much like pdfwidth , except it does not accept the vw unit.
The value of scaledwidth when used with DocBook can have the following units:
px Output device pixels (assumed to be 72 dpi)
pt Points (1/72 of an inch)
pc Picas (1/6 of an inch)
cm Centimeters
mm Millimeters
in Inches
em Ems (current font size)
% (or none) Percentage of intrinsic image size
DocBook also accepts the width attribute if scaledwidth is not provided.
29.3.4. Image Sizing Recap
Image sizing attributes
Backend Absolute size Relative to original size Relative to content
width
Relative to page width
12/20/2018 Asciidoctor User Manual
https://asciidoctor.org/docs/user-manual/ 140/315
Backend Absolute size Relative to original size Relative to content
width
Relative to page width
html width=120
(assumed to be px)
Not possible width=50% Not possible
pdf pdfwidth=100mm
(or cm, in, pc, pt, px)
Not possible pdfwidth=80% pdfwidth=50vw
docbook scaledwidth=100mm
(or cm, em, in, pc, pt, px)
scale=80 scaledwidth=50% Not possible
Here’s an example of how you might bring these attributes together to control the size of an image in various output formats:
A practice you might consider is using attributes to set the values for each output:
Then you can specify a half-size image using:
In addition to providing consistency across your document, this technique will help insulate you from future changes. For a more
detailed example, see this thread (http://discuss.asciidoctor.org/Unit-of-measure-for-image-dimensions-td3040.html#a3222) on the discussion
list.
29.4. Taming SVGs
Both block and inline image macros have built-in support for scalable vector graphics (SVGs). But there’s more than one way to
include an SVG into a web page, and the strategy used can effect how the SVG behaves (or misbehaves). Therefore, these macros
provide additional options to control how the SVG is included (i.e., referenced).
When the image target is an SVG, the options attribute on the macro accepts one of three values:
none (default)
interactive
inline
The following table demonstrates the impact these options have.
Demonstration of option values for SVG images
image::flower.jpg[Flower,640,480,pdfwidth=50%,scaledwidth=50%]
ifdef::backend-html5[]
:twoinches: width='144'
:full-width: width='100%'
:half-width: width='50%'
:half-size:
:thumbnail: width='60'
endif::[]
ifdef::backend-pdf[]
:twoinches: pdfwidth='2in'
:full-width: pdfwidth='100vw'
:half-width: pdfwidth='50vw'
:half-size: pdfwidth='50%'
:thumbnail: pdfwidth='20mm'
endif::[]
ifdef::backend-docbook5[]
:twoinches: width='50mm'
:full-width: scaledwidth='100%'
:half-width: scaledwidth='50%'
:half-size: width='50%'
:thumbnail: width='20mm'
endif::[]
ASCIIDOC
image::image.jpg[{half-size}]
ASCIIDOC
12/20/2018 Asciidoctor User Manual
https://asciidoctor.org/docs/user-manual/ 141/315
image::sample.svg[Static,300]
image::sample.svg[Interactive,300,opts=interactive]
Observe that the color changes when hovering over the
SVG.
image::sample.svg[Embedded,300,opts=inline]
Observe that the color changes when hovering over the
SVG. The SVG also inherits CSS from the document
stylesheets.
How the options value works and when it should be used is described below:
Option values for SVG images (HTML output)
Option HTML Element
Used
Effect When To Use
none (default) <img> Image is rasterized Static image, no interactivity, no custom
fonts
interactive <object> Image embedded as a live, interactive
object (aka “content document”)
For using CSS animations, scripting,
webfonts
inline <svg> The SVG is embedded directly into the
HTML itself.
For using CSS animations, scripting,
webfonts, when you require search
engines to search the SVG content.
To allow SVG content reachable by
JavaScript in the main DOM or to inherit
styles from the main DOM.
When using the inline or interactive options, the viewBox attribute must be defined on the root <svg> element in order
for scaling to work properly.
When using the inline option, if you specify a width or height on the image macro in AsciiDoc, the width , height and style
attributes on the <svg> element will be removed. Additionally, when using inline the primary SVG elements (e.g., <svg> )
cannot have a namespace.
If using the interactive option, you must link to the CSS that declares the fonts in the SVG file using an XML stylesheet
declaration.
If you’re inserting an SVG using either the inline or interactive options, we strongly recommend you optimize your SVG
using a tool like svgo (https://github.com/svg/svgo) or SVG Editor (https://petercollingridge.appspot.com/svg-editor).
As you work with SVG, you’ll become more comfortable making the decision about which method to employ given the
circumstances. It’s only confusing when you first encounter the choice. To learn more about using SVG on the web, consult the
online book SVG on the Web: A Practical Guide (https://svgontheweb.com/) as well as these articles about SVG
(https://www.sarasoueidan.com/tags/svg/).
29.5. Summary
12/20/2018 Asciidoctor User Manual
https://asciidoctor.org/docs/user-manual/ 142/315
Block and inline image attributes and values
Attribute Value(s) Example Syntax Comments
imagesdir empty,
absolute path,
relative path
or base URL
:imagesdir: media If the image target is a
URL or an absolute path,
the imagesdir prefix is
not added; Default is
empty value
id User defined
text
id=sunset-img
(or [[sunset-img]] or [#sunset-img] above block
macro)
alt User defined
text in first
position of
attribute list or
named
attribute
image::sunset.jpg[Brilliant sunset]
(or alt=Sunset )
title User defined
text
title="A mountain sunset"
(or .A mountain sunset above block macro)
Blocks: title displayed
below image; Inline: title
displayed as tooltip
caption User defined
text
caption="Figure 8: " Only applies to block
images.
width User defined
size in pixels
image::sunset.jpg[Sunset,300]
(or width=300 )
height User defined
size in pixels
image::sunset.jpg[Sunset,300,200]
(or height=200 )
link User defined
location of
external URI
link=https://www.flickr.com/photos/javh/5448336655
scale A scaling
factor to apply
to the intrinsic
image
dimensions
scale=80 DocBook only
scaledwidth User defined
width for
block images
scaledwidth=25% DocBook only
pdfwidth User defined
width for
images in a
PDF
pdfwidth=80vw Asciidoctor PDF only
align left, center,
right
align=left Block images only; Align
and float attributes are
mutually exclusive
float left, right float=right Block images only; float
and align attributes are
mutually exclusive; to
scope the float, use a float
group.
12/20/2018 Asciidoctor User Manual
https://asciidoctor.org/docs/user-manual/ 143/315
Attribute Value(s) Example Syntax Comments
role left, right, th,
thumb,
related, rel
role="thumb right"
(or [.thumb.right] above block macro)
Inline images can use role
to float images left and
right; Role shorthand (.)
can not be used on images
12/20/2018 Asciidoctor User Manual
https://asciidoctor.org/docs/user-manual/ 144/315
30. Video
The block video macro enables you to embed videos into your documentation. You can embed self-hosted videos or videos shared
on popular video hosting sites such as YouTube and Vimeo.
The video formats Asciidoctor supports is dictated by the formats supported by the browser (and, in turn, the user’s system).
While this was once a precarious ordeal, HTML5 has brought sanity to video support in the browser by adding a dedicated
<video> (https://developer.mozilla.org/en-US/docs/Web/HTML/Element/video) element and by introducing several standard video
formats. Those formats are now widely supported across browsers and systems.
For a canonical list of supported web video formats and their interaction with modern browsers, see the Mozilla Developer
Supported Media Formats (https://developer.mozilla.org/en-US/docs/Web/HTML/Supported_media_formats#Browser_compatibility)
documentation.
A recommendation for serving video to browsers
Where appropriate, we recommend using a video hosting service like YouTube or Vimeo to serve videos in online
documentation. These services specialize in streaming optimized video to the browser, with the lowest latency possible
given hardware, software, and network capabilities of the device viewing the video.
Vimeo even offers a white label mode so users aren’t made aware that the video is being served through its service.
See YouTube and Vimeo videos for details about how to serve videos from these services.
Basic video file include
You can control the video settings using additional attributes on the macro. For instance, you can offset the start time of playback
using the start attribute and enable autoplay using the autoplay option.
Setting attributes for local video playback
You can include a caption on the video using the title attribute.
Adding a caption to a video
30.1. YouTube and Vimeo videos
The video macro supports embedding videos from external video hosting services like YouTube and Vimeo. Asciidoctor
automatically generates the correct code to embed the video in the HTML output.
To use this feature, put the video ID in the macro target and the name of the hosting service in the first positional attribute.
Embedding a YouTube video
Embedding a Vimeo video
30.2. Supported Attributes
Video attributes and values
Attribute Value(s) Example Syntax Comments
title User defined text .An ocean sunset
video::video_file.mp4[]
ASCIIDOC
video::video_file.mp4[width=640, start=60, end=140, options=autoplay]
ASCIIDOC
.A walkthrough of the product
video::video_file.mp4[]
ASCIIDOC
video::rPQoq7ThGAU[youtube]
ASCIIDOC
video::67480300[vimeo]
ASCIIDOC
12/20/2018 Asciidoctor User Manual
https://asciidoctor.org/docs/user-manual/ 145/315
Attribute Value(s) Example Syntax Comments
poster A URL to an image
to show until the
user plays or
seeks.
poster=sunset.jpg Can be specified as the first positional
(unnamed) attribute. Also used to
specify the service when referring to a
video hosted on YouTube (youtube) or
Vimeo (vimeo).
width User-defined size
in pixels.
width=640 Can be specified as the second
positional (unnamed) attribute.
height User-defined size
in pixels.
height=480 Can be specified as the third positional
(unnamed) attribute.
options autoplay, loop,
modest,
nocontrols,
nofullscreen
opts="autoplay,loop" The controls are enabled by default. The
modest option enables modest branding
for a YouTube video.
start User-defined
playback start
time in seconds.
start=30
end User-defined
playback end time
in seconds.
end=90
theme The YouTube
theme to use for
the frame.
theme=light Valid values are dark (the default) and
light.
lang The language used
in the YouTube
frame.
lang=fr A two-letter language code or fully
specified locale.
12/20/2018 Asciidoctor User Manual
https://asciidoctor.org/docs/user-manual/ 147/315
32. Admonition
There are certain statements that you may want to draw attention to by taking them out of the content’s flow and labeling them
with a priority. These are called admonitions. It’s rendered style is determined by the assigned label (i.e., value). Asciidoctor
provides five admonition style labels:
NOTE
TIP
IMPORTANT
CAUTION
WARNING
When you want to call attention to a single paragraph, start the first line of the paragraph with the label you want to use. The
label must be uppercase and followed by a colon ( :).
Admonition paragraph syntax
1The label must be uppercase and immediately followed by a colon ( :).
2Separate the first line of the paragraph from the label by a single space.
Result: Admonition paragraph
Wolpertingers are known to nest in server racks. Enter at your own risk.
When you want to apply an admonition to complex content, set the label as a style attribute on a block. As seen in the next
example, admonition labels are commonly set on example blocks. This behavior is referred to as masquerading. The label must
be uppercase when set as an attribute on a block.
Admonition block syntax
1Set the label in an attribute list on a delimited block. The label must be uppercase.
2Admonition styles are commonly set on example blocks. Example blocks are delimited by four equal signs ( ==== ).
Result: Admonition block
Feeding the Werewolves
While werewolves are hardy community members, keep in mind the following dietary concerns:
1. They are allergic to cinnamon.
2. More than two glasses of orange juice in 24 hours makes them howl in harmony with alarms and
sirens.
3. Celery makes them sad.
In the examples above, the admonition is rendered in a callout box with the style label in the gutter. You can replace the textual
labels with icons by setting the icons attribute on the document. This is how the WARNING admonition paragraph renders
when icons is set and assigned the font value.
WARNING: Wolpertingers are known to nest in server racks.
Enter at your own risk.
ASCIIDOC
1 2
[IMPORTANT]
.Feeding the Werewolves
====
While werewolves are hardy community members, keep in mind the following dietary concerns:
. They are allergic to cinnamon.
. More than two glasses of orange juice in 24 hours makes them howl in harmony with alarms and sirens.
. Celery makes them sad.
====
ASCIIDOC
1
2
12/20/2018 Asciidoctor User Manual
https://asciidoctor.org/docs/user-manual/ 148/315
Admonition paragraph with icons set
Result: Admonition paragraph with icons set
Wolpertingers are known to nest in server racks. Enter at your own risk.
Learn more about using Font Awesome or custom icons with admonitions in the icons section.
WARNING: Wolpertingers are known to nest in server racks.
Enter at your own risk.
ASCIIDOC
12/20/2018 Asciidoctor User Manual
https://asciidoctor.org/docs/user-manual/ 149/315
33. Sidebar
Use a sidebar for ancillary content that doesn’t fit into the flow of the document’s narrative. A sidebar can be titled and contain
any type of content such as source code and images.
Sidebar syntax
1A title is optional.
2A sidebar is delimited by four asterisks ( **** ).
Result: Sidebar with title
AsciiDoc history
AsciiDoc was first released in Nov 2002 by Stuart Rackham. It was designed from the start to be a shorthand syntax for
producing professional documents like DocBook and LaTeX.
.AsciiDoc history
****
AsciiDoc was first released in Nov 2002 by Stuart Rackham.
It was designed from the start to be a shorthand syntax
for producing professional documents like DocBook and LaTeX.
****
ASCIIDOC
1
2
12/20/2018 Asciidoctor User Manual
https://asciidoctor.org/docs/user-manual/ 150/315
34. Example
Example syntax
Result: Example block
Sample document
Here’s a sample AsciiDoc document:
The document header is useful, but not required.
.Sample document
====
Here's a sample AsciiDoc document:
[listing]
....
= Title of Document
Doc Writer
:toc:
This guide provides...
....
The document header is useful, but not required.
====
ASCIIDOC
= Title of Document
Doc Writer
:toc:
This guide provides...
12/20/2018 Asciidoctor User Manual
https://asciidoctor.org/docs/user-manual/ 151/315
““
“
““
“
35. Prose Excerpts, Quotes and Verses
Prose excerpts, quotes and verses share the same syntax structure, including:
block name, either quote or verse
name of who the content is attributed to
bibliographical information of the book, speech, play, poem, etc., where the content was drawn from
excerpt text
35.1. Quote
For content that doesn’t require the preservation of line breaks, set the quote attribute in the first position of the attribute list.
Next, set the attribution and relevant citation information. However, these positional attributes are optional.
Anatomy of a basic quote
If the quote is a single line or paragraph, you can place the attribute list directly on top of the text.
Quote paragraph syntax
1Mark lead-in text explaining the context or setting of the quote using a period ( .). (optional)
2For content that doesn’t require the preservation of line breaks, set quote in the first position of the attribute list.
3The second position contains who the excerpt is attributed to. (optional)
4Enter additional citation information in the third position. (optional)
5Enter the excerpt or quote text on the line immediately following the attribute list.
Result: Quote paragraph
After landing the cloaked Klingon bird of prey in Golden Gate park:
Everybody remember where we parked.
— Captain James T. Kirk
Star Trek IV: The Voyage Home
If the quote or excerpt is more than one paragraph, place the text between delimiter lines consisting of four underscores ( ____ ).
Quote block syntax
Result: Quote block
Dennis: Come and see the violence inherent in the system. Help! Help! I’m being repressed!
King Arthur: Bloody peasant!
Dennis: Oh, what a giveaway! Did you hear that? Did you hear that, eh? That’s what I’m on about!
Did you see him repressing me? You saw him, Didn’t you?
[quote, attribution, citation title and information]
Quote or excerpt text
.After landing the cloaked Klingon bird of prey in Golden Gate park:
[quote, Captain James T. Kirk, Star Trek IV: The Voyage Home]
Everybody remember where we parked.
ASCIIDOC
1
234
5
[quote, Monty Python and the Holy Grail]
____
Dennis: Come and see the violence inherent in the system. Help! Help! I'm being repressed!
King Arthur: Bloody peasant!
Dennis: Oh, what a giveaway! Did you hear that? Did you hear that, eh? That's what I'm on about! Did you see him repressing
____
ASCIIDOC
12/20/2018 Asciidoctor User Manual
https://asciidoctor.org/docs/user-manual/ 152/315
““
“
““
“
““
“
— Monty Python and the Holy Grail
Asciidoctor also provides three alternative ways to markup quotes and prose excerpts.
35.1.1. Quoted paragraph
You can turn a single paragraph into a blockquote by:
1. surrounding it with double quotes
2. adding an optional attribution (prefixed with two dashes) below the quoted text
Quoted paragraph syntax
Result: Quoted paragraph
I hold it that a little rebellion now and then is a good thing, and as necessary in the political world
as storms in the physical.
— Thomas Jefferson
Papers of Thomas Jefferson: Volume 11
35.1.2. Air quotes
Air quotes (https://en.wikipedia.org/wiki/Air_quotes) are two double quotes on each line, emulating the gesture of making quote marks
with two fingers on each hand.
Result: Air quotes
Not everything that is faced can be changed. But nothing can be changed until it is faced.
— James Baldwin
35.1.3. Markdown-style blockquotes
Asciidoctor supports Markdown-style blockquotes.
Markdown-style blockquote syntax
Result: Markdown-style blockquote
I hold it that a little rebellion now and then is a good thing, and as necessary in the political world
as storms in the physical.
— Thomas Jefferson
Papers of Thomas Jefferson: Volume 11
Like Markdown, Asciidoctor supports block content inside the blockquote, including nested blockquotes.
Markdown-style blockquote containing block content
"I hold it that a little rebellion now and then is a good thing,
and as necessary in the political world as storms in the physical."
-- Thomas Jefferson, Papers of Thomas Jefferson: Volume 11
ASCIIDOC
[, James Baldwin]
""
Not everything that is faced can be changed.
But nothing can be changed until it is faced.
""
ASCIIDOC
> I hold it that a little rebellion now and then is a good thing,
> and as necessary in the political world as storms in the physical.
> -- Thomas Jefferson, Papers of Thomas Jefferson: Volume 11
MARKDOWN
12/20/2018 Asciidoctor User Manual
https://asciidoctor.org/docs/user-manual/ 153/315
““
“
Here’s how this conversation renders.
Result: Markdown-style blockquote with block content
What’s new?
I’ve got Markdown in my AsciiDoc!
Like what?
Blockquotes
Headings
Fenced code blocks
Is there more?
Yep. AsciiDoc and Markdown share a lot of common syntax already.
35.2. Verse
When you need to preserve indents and line breaks, use the verse block name. Verses are defined by setting verse on a
paragraph or an excerpt block delimited by four underscores ( ____ ).
Verse paragraph syntax
Result: Verse paragraph
The fog comes
on little cat feet.
— Carl Sandburg
two lines from the poem Fog
When the verse content includes blank or indented lines, enclose it in an excerpt block.
Verse delimited block syntax
> > What's new?
>
> I've got Markdown in my AsciiDoc!
>
> > Like what?
>
> * Blockquotes
> * Headings
> * Fenced code blocks
>
> > Is there more?
>
> Yep. AsciiDoc and Markdown share a lot of common syntax already.
MARKDOWN
[verse, Carl Sandburg, two lines from the poem Fog]
The fog comes
on little cat feet.
ASCIIDOC
12/20/2018 Asciidoctor User Manual
https://asciidoctor.org/docs/user-manual/ 154/315
Result: verse block
The fog comes
on little cat feet.
It sits looking
over harbor and city
on silent haunches
and then moves on.
— Carl Sandburg
Fog
[verse, Carl Sandburg, Fog]
____
The fog comes
on little cat feet.
It sits looking
over harbor and city
on silent haunches
and then moves on.
____
ASCIIDOC
12/20/2018 Asciidoctor User Manual
https://asciidoctor.org/docs/user-manual/ 157/315
37. Text Substitutions
Text substitution elements replace characters, markup, attribute references, and macros with converter specific styles and values.
When Asciidoctor processes a document it uses a set of six text substitution elements. The processor runs the text substitution
elements in the following order.
1. Special characters
2. Quotes
3. Attribute references
4. Replacements
5. Inline macros
6. Post replacements
In turn, these substitutions are organized into composite value groups. The table below shows which substitution elements are
included in each group.
Substitution groups
Group Special
characters
Quotes Attributes Replacements Macros Post
replacements
Header
None
Normal
Pass
Verbatim
By default, the normal substitution group is applied to most block and inline elements. However, there are a few exceptions.
The header substitution group is applied to metadata lines (author and revision information) in the document header. This
group is also applied to the values of attribute entries, regardless of whether those entries are defined in the header or elsewhere
in the document. In the header, only special characters and attribute references are replaced. In attribute entries, you can also
use the inline pass macro.
Fenced, literal, listing, and source blocks are processed with the verbatim substitution group. Only special characters are
replaced in these blocks.
The pass substitution group can only be applied to passthrough elements. Attribute references and macros are replaced in
passthroughs.
The none substitution group is applied to comment blocks.
The title substitution group
The title substitution group includes the same text substitutions as the normal group. However, the order that the
substitutions are executed is slightly different. Text substitutions are applied to titles in the following sequence:
1. Special characters
2. Quotes
3. Replacements
4. Inline macros
5. Attribute references
6. Post replacements
37.1. Special Characters
12/20/2018 Asciidoctor User Manual
https://asciidoctor.org/docs/user-manual/ 158/315
When applicable, the first text substitution to occur is the replacement of any special characters. This process is handled by the
specialchars element. The specialchars element searches for three characters ( <, >, &) and replaces them with their named
character references.
The less than symbol, <, is replaced with the named character reference < .
The greater than symbol, >, is replaced with the named character reference > .
An ampersand, &, is replaced with the named character reference & .
By default, the special characters substitution occurs on all inline and block elements except for comments and certain
passthroughs. The substitution of special characters can be controlled on blocks using the subs attribute and on inline elements
using the passthrough macro.
Special character substitution precedes attribute substitution, so you will need to manually escape any
attributes containing special characters that you set in the CLI or API. For example, on the command line, type
-a toc-title="Sections, Tables & Figures" instead of -a toc-title="Sections, Tables &
Figures" .
37.2. Quotes
The quotes substitution replaces the formatting markup on inline elements.
For example, when a document is converted to HTML, any asterisks enclosing text are replaced with <strong> HTML tags.
Syntax input
HTML output
The following table shows the HTML markup that is generated by the quotes substitution process.
HTML markup generated from AsciiDoc formatting syntax
Name AsciiDoc HTML
emphasis _word_ <em>word</em>
strong *word* <strong>word</strong>
monospace `word` <code>word</code>
superscript ^word^ <sup>word</sup>
subscript ~word~ <sub>word</sub>
double curved quotes "`word`" “word”
single curved quotes '`word`' ‘word’
The quotes substitution occurs on formatted text within title, paragraph, example, quote, sidebar, and verse blocks.
Elements subject to quotes text substitution
Element quotes
substitution
Attribute Entry Value
Comment
Example
Fenced
Happy werewolves are *really* slobbery.
ASCIIDOC
Happy werewolves are <strong>really</strong> slobbery.
HTML
12/20/2018 Asciidoctor User Manual
https://asciidoctor.org/docs/user-manual/ 159/315
Element quotes
substitution
Header
Literal
Listing
Macro
Open Varies
Paragraph
Passthrough
Quote
Sidebar
Source
Special sections
Table Varies
Title
Verse
37.3. Attributes
Attribute references are replaced with their values when they’re processed by the attributes substitution.
Elements subject to attributes text substitution
Element attributes
substitution
Attribute Entry Value
Comment
Example
Fenced
Header
Literal
Listing
Macro
Open Varies
Paragraph
Passthrough
Quote
Sidebar
Source
Special sections
12/20/2018 Asciidoctor User Manual
https://asciidoctor.org/docs/user-manual/ 160/315
Element attributes
substitution
Table Varies
Title
Verse
37.4. Replacements
The replacements substitution processes textual characters such as marks, arrows and dashes and replaces them with the
decimal format of their Unicode code point, i.e. their numeric character reference.
Textual symbol replacements
Name Syntax Unicode
Replacement
Rendered Notes
Copyright (C) © ©
Registered (R) ® ®
Trademark (TM) ™ ™
Em dash -- — — Only replaced if between two
word characters, between a word
character and a line boundary, or
flanked by spaces.
When flanked by space characters
(e.g., a -- b), the normal spaces
are replaced by thin spaces
( ).
ellipses ... … …
right single arrow -> → →
right double arrow => ⇒ ⇒
left single arrow <- ← ←
left double arrow <= ⇐ ⇐
apostrophe Sam's Sam’s Sam’s The vertical form apostrophe is
replaced with the curved form
apostrophe.
The replacements element depends on the substitutions completed by the specialcharacters element.
This is important to keep in mind when applying custom substitutions to a block. See the section about
applying custom substitutions for more information.
The replacements substitution also recognizes HTML and XML character references
(https://en.wikipedia.org/wiki/List_of_XML_and_HTML_character_entity_references) as well as decimal and hexadecimal Unicode code
points (https://en.wikipedia.org/wiki/List_of_Unicode_characters) and substitutes them for their corresponding decimal form Unicode
code point.
For example, to produce the § symbol you could write § , § , or § . When the document is processed,
replacements will replace the section symbol reference, regardless of whether it is a named character reference or a numeric
character reference, with § . In turn, § will display as §.
Anatomy of a character reference
12/20/2018 Asciidoctor User Manual
https://asciidoctor.org/docs/user-manual/ 161/315
A character reference is a standard sequence of characters that is substituted for a single character when Asciidoctor
processes a document. There are two types of character references: named character references and numeric character
references.
A named character reference (often called a character entity reference) is a short name that refers to a character (i.e., glyph).
To make the reference, the name must be prefixed with an ampersand ( &) and end with a semicolon ( ;).
For example:
† displays as †
€ displays as €
◊ displays as ◊
Numeric character references are the decimal or hexadecimal Universal Character Set/Unicode code points which refer to a
character.
The decimal code point references are prefixed with an ampersand ( &), followed by a hash ( #), and end with a
semicolon ( ;).
Hexadecimal code point references are prefixed with an ampersand ( &), followed by a hash ( #), followed by a
lowercase x, and end with a semicolon ( ;).
For example:
† or † displays as †
€ or € displays as €
◊ or ◊ displays as ◊
Developers may be more familiar with using Unicode escape sequences to perform text substitutions. For example, to
produce an @ sign using a Unicode escape sequence, you would prefix the hexadecimal Unicode code point with a
backslash ( \) and an uppercase or lowercase u, i.e. u0040 . However, Asciidoctor doesn’t process and replace Unicode
escape sequences at this time.
Asciidoctor also provides numerous built-in attributes for representing characters and symbols. These
attributes and their corresponding output are listed in Predefined attributes for character replacements .
The replacements substitution occurs within title, paragraph, example, quote, sidebar, and verse blocks.
Elements subject to replacements text substitution
Element replacements
substitution
Attribute Entry Value
Comment
Example
Fenced
Header
Literal
Listing
Macro
Open Varies
Paragraph
Passthrough
[1][2][3]
12/20/2018 Asciidoctor User Manual
https://asciidoctor.org/docs/user-manual/ 162/315
Element replacements
substitution
Quote
Sidebar
Source
Special sections
Table Varies
Title
Verse
37.5. Macros
Macros are processed by the macros element. The macros substitution replaces a macro’s content with the appropriate built-in
and user-defined configuration.
Elements subject to macros substitution
Element macros
substitution
Attribute Entry Value inline pass macro
only
Comment
Example
Fenced
Header
Literal
Listing
Macro
Open Varies
Paragraph
Passthrough
Quote
Sidebar
Source
Special sections
Table Varies
Title
Verse
37.6. Post Replacements
The line break character, +, is replaced when the post_replacements process runs.
Elements subject to post replacements text
12/20/2018 Asciidoctor User Manual
https://asciidoctor.org/docs/user-manual/ 163/315
substitution
Element post_replacements
substitution
Attribute Entry Value
Comment
Example
Fenced
Header
Literal
Listing
Macro
Open Varies
Paragraph
Passthrough
Quote
Sidebar
Source
Special sections
Table Varies
Title
Verse
37.7. Applying Substitutions
Specific substitution elements can be applied to any block or paragraph by setting the subs attribute. The subs attribute can be
assigned a comma separated list of the following substitution elements and groups.
none Disables substitutions
normal Performs all substitutions except for callouts
verbatim Replaces special characters and processes callouts
specialchars , specialcharacters Replaces <, >, and & with their corresponding entities
quotes Applies text formatting
attributes Replaces attribute references
replacements Substitutes textual and character reference replacements
macros Processes macros
post_replacements Replaces the line break character ( +)
Let’s look at an example where you only want to process special characters, formatting markup, and callouts in a literal block. By
default, literal blocks are only subject to special characters substitution. But you can change this behavior by setting the subs
attribute in the block’s attribute list.
12/20/2018 Asciidoctor User Manual
https://asciidoctor.org/docs/user-manual/ 164/315
[source,java,subs="verbatim,quotes"]
----
System.out.println("Hello *bold* text").
----
1The subs attribute is set in the attribute list and assigned the verbatim and quotes values.
2The formatting markup in this line will be replaced when the quotes substitution runs.
1The verbatim value enables the callouts to be processed.
2The quotes value enables the text formatting to be processed.
If you are applying the same set of substitutions to numerous blocks, you should consider making them an
attribute entry to ensure consistency.
Another way to ensure consistency and keep your documents clean and simple is to use the TreeProcessor
extension.
37.8. Incremental Substitutions
When you set the subs attribute on a block, you automatically remove all of its default substitutions. For example, if you set subs
on a literal block, and assign it a value of attributes , only attributes are substituted. The verbatim substitution will not be
applied. To remedy this situation, Asciidoctor provides a syntax to append or remove substitutions instead of replacing them
outright.
You can add or remove a substitution from the default substitution list using the plus ( +) and minus ( -) modifiers. These are
known as incremental substitutions.
<substitution>+ Prepends the substitution to the default list.
+<substitution> Appends the substitution to the default list.
-<substitution> Removes the substitution from the default list.
For example, you can add the attributes substitution to a listing block’s default substitution list.
Add attributes substitution to a default substitution list
Similarly, you can remove the callouts substitution.
Remove callouts substitution from a default substitution list
1
2
System.out.println("Hello boldbold text").
JAVA
1 2
:markup-in-source: verbatim,quotes
[source,java,subs="{markup-in-source}"]
----
System.out.println("Hello *bold* text").
----
ASCIIDOC
[source,xml,subs="attributes+"]
----
<version>{version}</version>
----
ASCIIDOC
[source,xml,subs="-callouts"]
.An illegal XML tag
----
<1>
content inside "1" tag
</1>
----
ASCIIDOC
12/20/2018 Asciidoctor User Manual
https://asciidoctor.org/docs/user-manual/ 165/315
You can also specify whether the substitution is placed at the beginning or end of the substitution list. If a + comes before the
name of the substitution, then it’s added to the end of the existing list, and if a + comes after the name, it’s added to the beginning
of the list.
In the above example, the quotes, then the special characters, and then the attributes substitutions will be applied to the listing
block.
37.8.1. Applying Substitutions to Inline Elements
Custom substitutions can also be applied to some inline elements, such as the pass macro.
For example, the quotes text substitution value is assigned in the inline pass macro below.
The text underline me is underlined and the word “me” is bold.
37.9. Preventing Substitutions
Asciidoctor provides several approaches for preventing substitutions.
Backslash escaping
To prevent punctuation from being interpreted as formatting markup, precede it with a backslash ( \). If the formatting
punctuation begins with two characters (e.g., __ ), you need to precede it with two backslashes ( \\ ). This is also how you can
prevent character and attribute references from substitution. When your document is processed, the backslash is removed so it
doesn’t display in your output.
You can also prevent substitutions with macro and block passthroughs.
[source,xml,subs="attributes+,+replacements,-callouts"]
----
<version>{version}</version>
<copyright>(C) ACME</copyright>
<1>
content inside "1" tag
</1>
----
ASCIIDOC
The text pass:q[<u>underline *me*</u>] is underlined and the word "`me`" is bold.
ASCIIDOC
\*Stars* will appear as *Stars*, not as bold text.
\§ will appear as an entity, not the § symbol.
\\__func__ will appear as __func__, not as emphasized text.
\{two-semicolons} will appear {two-semicolons}, not resolved as ;;.
ASCIIDOC
12/20/2018 Asciidoctor User Manual
https://asciidoctor.org/docs/user-manual/ 166/315
38. Literal Text and Blocks
Literal paragraphs and blocks display the text you write exactly as you enter it. Literal text is treated as preformatted text. The
text is shown in a fixed-width font and endlines are preserved. Only special characters and callouts are replaced when the
document is converted.
Literal blocks are defined three ways:
1. Indenting the first line of a paragraph by one or more spaces
2. Applying the literal attribute to a paragraph or block
3. Using the literal block delimiter ( .... )
When a line begins with one or more spaces it is displayed as a literal paragraph. This method is a quick and easy way to insert
code snippets.
Implicit literal text
Result: Implicit literal text
~/secure/vault/defops
When you want an entire block of text to be literal and would prefer not to indent it, set the literal attribute on top of the
element.
Literal style paragraph syntax
Result: Literal style paragraph
error: The requested operation returned error: 1954 Forbidden search for defensive operations manual
absolutely fatal: operation initiation lost in the dodecahedron of doom
would you like to die again? y/n
Finally, you can surround the content you want rendered as literal by enclosing it in a set of literal block delimiters ( .... ). This
method is useful when the content consists of several elements that are separated by blank lines.
Literal delimited block syntax
Notice in the output that the bold text formatting is not applied to the text nor are the three consecutive periods replaced by the
ellipsis Unicode character.
Result: Literal delimited block
~/secure/vault/defops
ASCIIDOC
[literal]
error: The requested operation returned error: 1954 Forbidden search for defensive operations manual
absolutely fatal: operation initiation lost in the dodecahedron of doom
would you like to die again? y/n
ASCIIDOC
....
Lazarus: Where is the *defensive operations manual*?
Computer: Calculating ...
Can not locate object that you are not authorized to know exists.
Would you like to ask another question?
Lazarus: Did the werewolves tell you to say that?
Computer: Calculating ...
....
ASCIIDOC
12/20/2018 Asciidoctor User Manual
https://asciidoctor.org/docs/user-manual/ 167/315
Lazarus: Where is the *defensive operations manual*?
Computer: Calculating ...
Can not locate object that you are not authorized to know exists.
Would you like to ask another question?
Lazarus: Did the werewolves tell you to say that?
Computer: Calculating ...
12/20/2018 Asciidoctor User Manual
https://asciidoctor.org/docs/user-manual/ 168/315
39. Listing Blocks
Like literal blocks, the content in listing blocks is displayed exactly as you entered it. Listing block content is converted to <pre>
text. The content in listing blocks is only subject to special character and callout substitutions.
The listing block name can be applied to content two ways.
1. Set the listing attribute on the element.
2. Contain the content within a delimited listing block.
The listing block name is applied to an element, such as a paragraph, by setting the listing attribute on that element.
Listing paragraph syntax
Result: Listing paragraph
A delimited listing block is surrounded by lines composed of four hyphens ( ---- ).
Delimited listing block syntax
Here’s how the block above appears when rendered as HTML.
Result: Listing block
You should notice a few things about how the content is processed.
the HTML tag <pre> is escaped
then endlines are preserved
the phrase listing block is not italicized, despite having underscores around it.
Listing blocks are good for displaying raw source code, especially when used in tandem with the source and source-
highlighter attributes. The example below shows a listing block with source and the language ruby applied to its content.
Source block syntax
Result: Listing block with the source attribute set
app.rb
[listing]
This is an example of a paragraph styled with `listing`.
Notice that the monospace markup is preserved in the output.
ASCIIDOC
This is an example of a paragraph styled with `listing`.
Notice that the monospace markup is preserved in the output.
----
This is an example of a _listing block_.
The content inside is displayed as <pre> text.
----
ASCIIDOC
This is an example of a _listing block_.
The content inside is displayed as <pre> text.
.app.rb
[source,ruby]
----
require 'sinatra'
get '/hi' do
"Hello World!"
end
----
ASCIIDOC
12/20/2018 Asciidoctor User Manual
https://asciidoctor.org/docs/user-manual/ 169/315
Detailed instructions for using the source and source-highlighter attributes are provided in the source code blocks section.
Listing block with custom substitutions syntax
Result: Listing block with custom substitutions applied
39.1. To Wrap or to Scroll
The default Asciidoctor stylesheet wraps long lines in listing and literal blocks by applying the CSS white-space: pre-wrap and
word-wrap: break-word . The lines are wrapped at word boundaries, similar to how most text editors wrap lines. This prevents
horizontal scrolling which some users considered a greater readability problem than line wrapping.
However, this behavior is configurable because there are times when you don’t want the lines in listing and literal blocks to wrap.
There are two ways to prevent lines from wrapping so that horizontal scrolling is used instead:
nowrap block option
unset the prewrap document attribute (on by default)
You can use the nowrap option on literal or listing blocks to prevent lines from being wrapped in the HTML.
Listing block with nowrap option syntax
When the nowrap option is used, the nowrap class is added to the <pre> element. This class changes the CSS to white-space:
pre and word-wrap: normal .
Result: Listing block with nowrap option applied
require 'sinatra'
get '/hi' dodo
"Hello World!"
endend
RUBY
:version: 1.5.6.1
[source,xml,subs="verbatim,attributes"]
----
<dependency>
<groupId>org.asciidoctor</groupId>
<artifactId>asciidoctor-java-integration</artifactId>
<version>{version}</version>
</dependency>
----
<dependency>
<groupId>org.asciidoctor</groupId>
<artifactId>asciidoctor-java-integration</artifactId>
<version>1.5.6.1</version>
</dependency>
XML
[source%nowrap,java]
----
public class ApplicationConfigurationProvider extends HttpConfigurationProvider
{
@Override
public Configuration getConfiguration(ServletContext context)
{
return ConfigurationBuilder.begin()
.addRule()
.when(Direction.isInbound().and(Path.matches("/{path}")))
.perform(Log.message(Level.INFO, "Client requested path: {path}"))
.where("path").matches(".*");
}
}
----
ASCIIDOC
12/20/2018 Asciidoctor User Manual
https://asciidoctor.org/docs/user-manual/ 170/315
To prevent lines from wrapping globally, unset the prewrap attribute on the document.
Disable prewrap globally (thus, enabling nowrap)
When the prewrap attribute is unset, the nowrap class is added to any <pre> elements.
Now, you can use the line wrapping strategy that works best for you and your readers.
publicpublic classclass ApplicationConfigurationProviderApplicationConfigurationProvider extendsextends HttpConfigurationProvider
{
@Override
publicpublic Configuration getConfiguration(ServletContext context)
{
returnreturn ConfigurationBuilder.begin()
.addRule()
.when(Direction.isInbound().and(Path.matches("/{path}")))
.perform(Log.message(Level.INFO, "Client requested path: {path}"))
.where("path").matches(".*");
}
}
JAVA
:prewrap!:
ASCIIDOC
12/20/2018 Asciidoctor User Manual
https://asciidoctor.org/docs/user-manual/ 171/315
40. Passthroughs
The passthrough is the primary mechanism by which to escape content in AsciiDoc (far more comprehensive and consistent than
using a backslash). As the name implies, a passthrough passes content directly through to the output document without applying
any substitutions. When using the passthrough block or macro, it’s possible to specify a custom set of substitutions to be applied
before the content is reintroduced. Other forms of passthroughs, such as the single and double plus, apply substitutions strictly
for compliance with the output format.
Using passthroughs to pass content (without substitutions) can couple your content to a specific output format,
such as HTML. In these cases, you should use conditional preprocessor directives to route passthrough content
for different output formats based on the current backend.
40.1. Passthrough Macros
Asciidoctor supports several forms of the passthrough macro.
inline pass macro
An inline macro named pass that can be used to passthrough content. Supports an optional set of substitutions.
single and double plus
A special syntax for preventing text from being formatted. Only escapes special characters for compliance with the output
format and doesn’t support explicit substitutions.
triple plus
A special syntax for designating passthrough content. Does not apply any substitutions (equivalent to the inline pass macro)
and doesn’t support explicit substitutions.
double dollar (deprecated)
A deprecated special syntax for designating passthrough content. Like the triple plus, does not apply any substitutions and
doesn’t support explicit substitutions.
Asciidoctor does not implement the block pass macro. Instead, you should use a pass block.
40.1.1. Inline pass macro and explicit substitutions
To exclude a phrase from substitutions and disable escaping of special characters, enclose it in the inline pass macro. For
example, here’s one way to format text as underline when generating HTML from AsciiDoc:
The text underline me is underlined.
If you want to enable ad-hoc quotes substitution, then assign the macros value to subs and use the inline pass macro.
[subs=+macros]
----
I better not contain *bold* or _italic_ text.
pass:quotes[But I should contain *bold* text.]
----
1macros is assigned to subs , which allows any macros within the block to be processed.
2The pass macro is assigned the quotes value. Text within the square brackets will be formatted.
The inline pass macro does introduce additional markup into the source code that could make it invalid in raw form. However,
the output it produces will be valid when viewed in a viewer (HTML, PDF, etc.).
pass:[content like #{variable} passed directly to the output] followed by normal content.
content with only select substitutions applied: pass:c,a[__<{email}>__]
ASCIIDOC
The text pass:[<u>underline me</u>] is underlined.
ASCIIDOC
1
2
12/20/2018 Asciidoctor User Manual
https://asciidoctor.org/docs/user-manual/ 172/315
The inline pass macro also accepts shorthand values for specifying substitutions.
c = special characters
q = quotes
a = attributes
r = replacements
m = macros
p = post replacements
For example, the quotes text substitution value is assigned in the inline passthrough macro below:
The text underline me is underlined and the word “me” is bold.
40.1.2. Triple plus passthrough
The triple-plus passthrough works much the same way as the pass macro. To exclude content from substitutions, enclose it in
triple pluses (+++).
+++content passed directly to the output+++ followed by normal content.
The triple-plus macro is often used to output custom HTML or XML.
The text underline me is underlined.
40.1.3. Nesting blocks and passthrough macros
When you’re using passthroughs inside literal and listing blocks, it can be easy to forget that the triple-plus, double-dollar, and
backtick passthroughs are macros (not quotes). If you want to enable the passthroughs, make sure to assign the macros value to
the subs attribute.
[source,java,subs="+quotes,+macros"]
----
protected void configure(HttpSecurity http) throws Exception {
http
.authorizeRequests()
**.antMatchers("/resources/$$**$$").permitAll()**
.anyRequest().authenticated()
.and()
.formLogin()
.loginPage("/login")
.permitAll();
----
I better not contain *bold* or _italic_ text.
But I should contain boldbold text.
The text pass:q[<u>underline *me*</u>] is underlined and the word "`me`" is bold.
ASCIIDOC
The text +++<u>underline me</u>+++ is underlined.
ASCIIDOC
12/20/2018 Asciidoctor User Manual
https://asciidoctor.org/docs/user-manual/ 173/315
40.2. Passthrough Blocks
The passthrough block and pass block style exclude block content from all substitutions (unless specified otherwise).
A passthrough block is delimited by four plus signs ( ++++ ). The pass style is implied.
(Keep in mind that AsciiDoc has a video macro, so this example is merely for demonstration. However, a passthrough could come
in handy if you need to output more sophisticated markup than what the built-in HTML converter produces).
The pass style can also be set on a paragraph or an open block.
You can use the subs attribute to specify a comma-separated list of substitutions. These substitutions will be applied to the
content prior to it being reintroduced to the output document.
The content of the pass block does not get wrapped in a paragraph. Therefore, you can use the pass style in combination with
the normal substitution category to output content without generating a paragraph.
protectedprotected voidvoid configure(HttpSecurity http) throwsthrows Exception {
http
.authorizeRequests()
.antMatchers(.antMatchers(""/resources/**/resources/**"").permitAll()).permitAll()
.anyRequest().authenticated()
.and()
.formLogin()
.loginPage("/login")
.permitAll();
JAVA
++++
<video poster="images/movie-reel.png">
<source src="videos/writing-zen.webm" type="video/webm">
</video>
++++
ASCIIDOC
[pass]
<u>underline me</u> is underlined.
ASCIIDOC
[subs=attributes]
++++
{name}
image:tiger.png[]
++++
ASCIIDOC
[subs=normal]
++++
Normal content which is not enclosed in a paragraph.
++++
ASCIIDOC
12/20/2018 Asciidoctor User Manual
https://asciidoctor.org/docs/user-manual/ 174/315
41. Open Blocks
The most versatile block of all is the open block.
Open block syntax
Result: Open block
An open block can be an anonymous container, or it can masquerade as any other block.
An open block can act as any other block, with the exception of pass and table. Here’s an example of an open block acting as a
sidebar.
Open block masquerading as a sidebar syntax
Result: Open block masquerading as a sidebar
Related information
This is aside text.
It is used to present information related to the main content.
This is an open block acting as a source block.
Open block masquerading as a source block syntax
Result: Open block masquerading as a source block
--
An open block can be an anonymous container,
or it can masquerade as any other block.
--
ASCIIDOC
[sidebar]
.Related information
--
This is aside text.
It is used to present information related to the main content.
--
ASCIIDOC
[source]
--
puts "I'm a source block!"
--
ASCIIDOC
puts "I'm a source block!"
ASCIIDOC
12/20/2018 Asciidoctor User Manual
https://asciidoctor.org/docs/user-manual/ 176/315
42. Equations and Formulas
If you need to get technical in your writing, Asciidoctor integrates with MathJax (https://www.mathjax.org). MathJax is the standard
library for displaying Science, Technology, Engineering and Math (STEM) expressions in the browser.
Thanks to MathJax JavaScript library (https://www.mathjax.org), Asciidoctor supports both AsciiMathML
(https://docs.mathjax.org/en/latest/asciimath.html) and TeX and LaTeX (https://docs.mathjax.org/en/latest/tex.html) math notation in the same
document.
12/20/2018 Asciidoctor User Manual
https://asciidoctor.org/docs/user-manual/ 177/315
43. Activating stem support
To activate equation and formula support, simply set the stem attribute in the document’s header (or by passing the attribute to
the command line or API).
Setting the stem attribute
1The default interpreter value, asciimath , is assigned implicitly.
By default, Asciidoctor’s stem support assumes all equations are AsciiMath if not specified explicitly. If you want to use the LaTeX
interpreter by default, assign latexmath to the stem attribute.
The html backend will just use mathjax client-side to render math notation, whereas the docbook backend will use it to convert
math to mathml.
Assigning an alternative interpreter to the stem attribute
You can still use both interpreters in the same document. The value of the stem attribute merely sets the
default interpreter. To set the interpreter explicitly for a given block or inline span, just use asciimath or
latexmath in place of stem as explained in Using Multiple Stem Interpreters.
Stem content can be displayed inline with other content or as discrete blocks. No substitutions are applied to the content within a
stem macro or block.
43.1. Inline Stem Content
The best way to mark up an inline formula is to use the stem macro.
Inline stem macro syntax
1The inline stem macro contains only one colon ( :).
2Place the content you want interpreted within the square brackets ( [] ) of the macro.
Rendered inline stem content
Water ( ) is a critical component.
43.2. Block Stem Content
Block formulas are marked up by assigning the stem style to a delimited passthrough block.
Delimited stem block syntax
1Assign the stem style to the passthrough block.
2A passthrough block is delimited by a line of four consecutive plus signs ( ++++ ).
= My Diabolical Mathmatical Opus
Jamie Moriarty
:stem:
ASCIIDOC
1
= My Diabolical Mathmatical Opus
Jamie Moriarty
:stem: latexmath
ASCIIDOC
stem:[sqrt(4) = 2]
Water (stem:[H_2O]) is a critical component.
ASCIIDOC
1 2
[stem]
++++
sqrt(4) = 2
++++
ASCIIDOC
1
2
12/20/2018 Asciidoctor User Manual
https://asciidoctor.org/docs/user-manual/ 178/315
The result is rendered beautifully in the browser thanks to MathJax!
Rendered delimited stem block
You don’t need to add special delimiters around the expression as the MathJax documentation
(https://math.meta.stackexchange.com/questions/5020/mathjax-basic-tutorial-and-quick-reference) suggests. Asciidoctor
handles that for you automatically!
43.3. Using Multiple Stem Interpreters
You can use multiple interpreters for stem content within the same document by using the interpreter’s name instead of the
default stem name.
For example, if you want LaTeXMath to interpret an inline equation, name the macro latexmath .
Inline latexmath macro syntax
Rendered latexmath content
The name that maps to the interpreter you want to use can also be applied to block stem content.
Delimited asciimath block syntax
43.4. Enabling STEM expressions in the DocBook Toolchain
When converting to HTML, Asciidoctor relies on MathJax to parse and render the STEM expressions in the browser. We can’t rely
on MathJax when converting to DocBook, so Asciidoctor must explicitly convert the expressions into something the DocBook
toolchain can understand. Enter the asciimath gem.
The asciimath gem converts AsciiMath expressions to MathML. The DocBook converter uses this functionality if the gem is
available. Thus, to enable AsciiMath support when converting to DocBook, you need to install the asciimath gem:
$ gem install asciimath
For full functionality, you’ll also need at least Asciidoctor version 1.5.4.
The asciimath gem converts AsciiMath to MathML. If you’re generating a PDF from the DocBook, the MathML needs to be
interpreted and drawn into the PDF. In the DocBook FOP pipeline, this is handled by JEuclid.
Fortunately, fopub (https://github.com/asciidoctor/asciidoctor-fopub) is already configured to use the JEuclid integration. When fopub
generates the PDF, the JEuclid FOP plugin processes any MathML found in the DocBook file, including the expressions
transformed from AsciiMath to MathML by the asciimath gem. As a result, AsciiMath stem expressions in the AsciiDoc file will
render as expected in the generated PDF.
There’s no equivalent gem for converting STEM expressions written in LaTeX to MathML. Instead, you can convert the DocBook to
PDF using the dblatex pipeline, which obviously supports LaTeX expressions.
latexmath:[C = \alpha + \beta Y^{\gamma} + \epsilon]
ASCIIDOC
= My Diabolical Mathmatical Opus
Jamie Moriarty
:stem: latexmath
[asciimath]
++++
sqrt(4) = 2
++++
ASCIIDOC
12/20/2018 Asciidoctor User Manual
https://asciidoctor.org/docs/user-manual/ 179/315
44. User Interface Macros
We are looking for feedback on these macros before setting them in stone. If you have suggestions, we want to hear from you!
You must set the experimental attribute to enable the UI macros.
44.1. Keyboard shortcuts
Asciidoctor recognizes a macro for creating keyboard shortcuts using the syntax kbd:[key(+key)*] .
Keyboard macro syntax
Result: Keyboard macros displaying common browser keyboard
shortcuts
Shortcut Purpose
Toggle fullscreen
+Open a new tab
+ + New incognito window
Used to escape characters
+Jump to keyword
+Increase zoom
You no longer have to struggle to explain to users what keys they are supposed to press.
44.2. Menu selections
Trying to explain to someone how to select a menu item can be a pain. With the menu macro, the symbols do the work.
Menu macro syntax
The instructions in the example above appear below.
Result: Menu macros displaying menu selections
To save the file, select File Save.
|===
|Shortcut |Purpose
|kbd:[F11]
|Toggle fullscreen
|kbd:[Ctrl+T]
|Open a new tab
|kbd:[Ctrl+Shift+N]
|New incognito window
|kbd:[\ ]
|Used to escape characters
|kbd:[Ctrl+\]]
|Jump to keyword
|kbd:[Ctrl + +]
|Increase zoom
|===
ASCIIDOC
F11
Ctrl T
Ctrl Shift N
\
Ctrl ]
Ctrl +
To save the file, select menu:File[Save].
Select menu:View[Zoom > Reset] to reset the zoom level to the default setting.
ASCIIDOC
12/20/2018 Asciidoctor User Manual
https://asciidoctor.org/docs/user-manual/ 180/315
Select View Zoom Reset to reset the zoom level to the default setting.
44.3. UI buttons
It can be equally difficult to communicate to the reader that they need to press a button. They can’t tell if you are saying “OK” or
they are supposed to look for a button labeled OK. It’s all about getting the semantics right. The btn macro to the rescue!
Button macro syntax
Result: Button macros displaying UI buttons
Press the OK button when you are finished.
Select a file in the file navigator and click Open .
Press the btn:[OK] button when you are finished.
Select a file in the file navigator and click btn:[Open].
ASCIIDOC
[ ]
[ ]
12/20/2018 Asciidoctor User Manual
https://asciidoctor.org/docs/user-manual/ 181/315
45. Icons
Icons are used for admonition labels, callout numbers and inline symbols. Asciidoctor provides three strategies for display icons:
as text, as images or as a characters selected from an icon font. The strategy is controlled using the icons attribute. The default
behavior is to display the fallback text.
If you want icons to display using images, set the icons attribute to an empty value in the document header. This strategy is
recommended if you are converting to DocBook or you want an easy way to make HTML for viewing offline. The DocBook
toolchain provides images for the admonition and callout icons, which you can replace with your own custom icons. If you use
the inline icon macro, you’ll need to provide the images for those icons.
Alternatively, you can have Asciidoctor “draw” icons using the Font Awesome (https://fontawesome.com/v4.7.0) font-based icon set. To
use this feature, set the value of the icons document attribute to font in the document header. You can see the available icons
on the icons page (https://fontawesome.com/v4.7.0/icons/). Using Font Awesome provides many more images, but requires online
access by default.
The default CSS stylesheet (or any stylesheet produced by the Asciidoctor stylesheet factory
(https://github.com/asciidoctor/asciidoctor-stylesheet-factory)) is required when using font-based icons.
45.1. Admonition Icons
When font-based icons are enabled, Asciidoctor will draw the icons for the 5 built-in admonition types using Font Awesome.
Here’s an example that shows how to enable font-based icons, starting with the AsciiDoc source:
Set icons attribute to font in the document header
Asciidoctor will then emit HTML markup that selects an appropriate font character from the Font Awesome font for each
admonition block:
Result: HTML output when the icons attribute is set to font
This is how the admonition looks rendered.
Result: Admonition block label is displayed as an icon when the icons attribute is set
Asciidoctor supports font-based admonition icons, powered by Font Awesome!
Asciidoctor adds a reference to the Font Awesome stylesheet and font files served from a CDN to the document header:
The icons chosen are selected by the stylesheet. The default stylesheet maps icons to the following 5 CSS classes:
.admonitionblock td.icon .icon-note
= Document Title
:icons: font
NOTE: Asciidoctor supports font-based admonition icons, powered by Font Awesome!
ASCIIDOC
<div class="admonitionblock note">
<table>
<tr>
<td class="icon">
<i class="fa icon-note" title="Note"></i>
</td>
<td class="content">
Asciidoctor supports font-based admonition icons, powered by Font Awesome!
</td>
</tr>
</table>
</div>
HTML
<link rel="stylesheet"
href="https://cdnjs.cloudflare.com/ajax/libs/font-awesome/4.7.0/css/font-awesome.min.css">
HTML
12/20/2018 Asciidoctor User Manual
https://asciidoctor.org/docs/user-manual/ 182/315
.admonitionblock td.icon .icon-tip
.admonitionblock td.icon .icon-warning
.admonitionblock td.icon .icon-caution
.admonitionblock td.icon .icon-important
If you want to customize the icon or the color that is used, you’ll need to provide a custom stylesheet or override the styles using a
docinfo file. Here’s an example that shows how to change the icon for the note admonition to sticky note:
45.1.1. Unicode Admonition Icons
Instead of image or font-based icons, it’s possible to use Unicode glyphs for admonition icons by applying a little trick.
If the icons attribute is not set on the document, Asciidoctor outputs a textual label that identifies the admonition type. The text
for this label comes from an AsciiDoc attribute. The name of the attribute is <type>-caption , where <type> is the admonition
type in lowercase. For example, the attribute for a tip admonition is tip-caption .
Instead of a word, you can assign a Unicode glyph to this attribute:
Here’s the HTML that Asciidoctor outputs for the icon cell:
Instead of entering the glyph directly, you can enter a character reference instead. However, since you’re defining the character
reference in an attribute entry, you (currently) have to disable substitutions on the value.
On GitHub, the HTML output that Asciidoctor emits is run through a postprocessing filter that substitutes emoji shortcodes with
emoji symbols. That means you can use these shortcodes in the value of the attribute:
When the document is processed through the GitHub interface, the shortcodes get replaced with real emojis. This is the only
known way to get admonition icons to work on GitHub. Give it a try!
45.2. Inline Icons
An icon can be inserted at an arbitrary place in paragraph content with an inline macro.
Here’s an example that inserts the Font Awesome tags icon in front of a list of tag names.
Inline icon macro syntax
.admonitionblock.admonitionblock td.icon.icon .icon-note.icon-note::before {
content: "\f24a";
color:black;
}
CSS
:tip-caption: 💡
[TIP]
It's possible to use Unicode glyphs as admonition icons.
ASCIIDOC
<td class="icon">
<div class="title">💡</div>
</td>
HTML
:tip-caption: pass:[💡]
[TIP]
It's possible to use Unicode glyphs as admonition icons.
ASCIIDOC
ifdef::env-github[]
:tip-caption: :bulb:
endif::[]
[TIP]
It's possible to use emojis as admonition icons on GitHub.
ASCIIDOC
icon:tags[] ruby, asciidoctor
ASCIIDOC
12/20/2018 Asciidoctor User Manual
https://asciidoctor.org/docs/user-manual/ 183/315
Here’s how the HTML converter converts the above syntax when the icons attribute is assigned the font value.
Result: HTML output
More importantly, here’s how it looks!
Result: Inline icon macro
ruby, asciidoctor
You can even give the icon color by assigning it a role.
Inline icon macro and role syntax
Result: Inline icon macro and role
ruby, asciidoctor
If you aren’t using font-based icons, Asciidoctor looks for icon images on disk, in the iconsdir , naturally. Here’s how the HTML
converter converts an icon macro when the icons attribute is not set or empty.
Result: HTML output
Here’s how the DocBook converter converts to icon macro. DocBook does not support font-based icons, so the DocBook output is
not affected by the value of the icons attribute.
Result: DocBook output
Relationship to the inline image macro
The inline icon macro is similar to the inline image macro with a few exceptions:
If the icons attribute has the value font, the macro will translate to a font-based icon in the HTML converter (e.g., <i
class="icon-tags"></i> )
If the icons attribute does not have the value font, or the converter is DocBook, the macro will insert an image into the
document that resolves to a file in the iconsdir directory (e.g., <img src="./images/icons/tags.png"> )
The file resolution strategy when using image-based icons is the same used to locate images for the admonition icons. The file
extension is set using the icontype attribute, which defaults to PNG ( png ).
45.2.1. Size, Rotate, and Flip
The icon macro has a few attributes that can be used to modify the size and orientation of the icon. At the moment, these are
specific to Font Awesome and therefore only apply to HTML output when icon fonts are enabled.
size
First positional attribute; scales the icon; values: 1x (default), 2x , 3x , 4x , 5x , lg , fw
rotate
Rotates the icon; values: 90 , 180 , 270
<div class="paragraph">
<p><span class="icon"><i class="fa fa-tags"></i></span> ruby, asciidoctor</p>
</div>
XML
icon:tags[role="blue"] ruby, asciidoctor
ASCIIDOC
<div class="paragraph">
<p><span class="image"><img src="./images/icons/tags.png" alt="tags"></span> ruby, asciidoctor</p>
</div>
XML
<inlinemediaobject>
<imageobject>
<imagedata fileref="./images/icons/tags.png"/>
</imageobject>
<textobject><phrase>tags</phrase></textobject>
</inlinemediaobject> ruby, asciidoctor
XML
12/20/2018 Asciidoctor User Manual
https://asciidoctor.org/docs/user-manual/ 184/315
flip
Flips the icon; values: horizontal , vertical
The first unnamed attribute is assumed to be the size. For instance, to make the icon twice the size as the default, simply add 2x
inside the square brackets.
This is equivalent to:
And this is how the displays.
The previous example emits the following HTML:
If you want to line up icons so that you can use them as bullets in a list, use the fw size as follows:
To rotate and flip the icon, specify these options using attributes:
The looks like this.
The previous example emits the following HTML:
45.2.2. Link and Window
Like an inline image, it’s possible to add additional metadata to an inline icon.
Below are the possible attributes that apply to both font-based and image-based icons:
link
The URI target used for the icon, which will wrap the converted icon in a link
window
The target window of the link (when the link attribute is specified) (HTML converter)
Here’s an example of an icon with a link:
The previous example emits the following HTML:
45.2.3. Image Icon Attributes
Below are the possible attributes that apply in the case that font-based icons are not in use:
icon:heart[2x]
ASCIIDOC
icon:heart[size=2x]
ASCIIDOC
<span class="icon"><i class="fa fa-heart fa-2x"></i></span>
XML
[%hardbreaks]
icon:bolt[fw] bolt
icon:heart[fw] heart
icon:shield[rotate=90, flip=vertical]
ASCIIDOC
<span class="icon"><i class="fa-shield fa-rotate-90 fa-flip-vertical"></i></span>
XML
icon:download[link="https://rubygems.org/downloads/asciidoctor-1.5.2.gem"]
ASCIIDOC
<span class="icon"><a class="image" href="https://rubygems.org/downloads/asciidoctor-1.5.2.gem"><i class="fa-download"></i>
XML
12/20/2018 Asciidoctor User Manual
https://asciidoctor.org/docs/user-manual/ 185/315
alt
The alternative text on the <img> tag (HTML backend) or text for <inlinemediaobject> (DocBook converter)
width
The width applied to the image
height
The height applied to the image
title
The title of the image displayed when the mouse hovers over it (HTML converter)
role
The role applied to the element that surrounds the icon
Currently, the inline icon macro doesn’t support any options to change its physical position (such as alignment left or right).
45.3. Favicon
When using Asciidoctor to generate a standalone HTML document (i.e., the header_footer option is true ), you can instruct the
processor to include a link to a favicon by setting the favicon attribute in the document header.
By default, the processor will add a link reference of type "icon" that refers to a file named favicon.ico (relative to the HTML
document):
This reference gets added inside the HTML <head> tag (which explains why this feature is not available when generating an
embeddable HTML document).
To modify the name or location of the icon file, simply assign a value to the favicon attribute:
This will now produce the following HTML tag:
Notice the mimetype is automatically set based on the file extension of the image.
The value of the iconsdir attribute is not prepend to the favicon path as it is with icons in the content. If you want this directory
to be included in the favicon path, you must reference it explicitly:
If you’re converting a set of AsciiDoc files in multiple directories for the purpose of making a website, and the
favicon is located in a shared location, you’ll likely want to use a forward slash ( /) at the beginning of the
favicon path.
If you’re looking for more control over how the favicon is declared, you should use a head docinfo file. Keep in mind that if you
add an icon link in a head docinfo file and also set the favicon attribute, you’ll end up with two icon links in the generated HTML
document.
= Document Title
:favicon:
ASCIIDOC
<link rel="icon" type="image/x-icon" href="favicon.ico">
HTML
= Document Title
:favicon: ./images/favicon/favicon.png
ASCIIDOC
<link rel="icon" type="image/png" href="./images/favicon/favicon.png">
HTML
:favicon: {iconsdir}/favicon.png
ASCIIDOC
12/20/2018 Asciidoctor User Manual
https://asciidoctor.org/docs/user-manual/ 186/315
46. Syntax Highlighting Source Code
Developers are accustomed to seeing source code that uses color and other styling to emphasize the code’s structure (i.e.,
keywords, types, delimiters, etc.). This technique is known as syntax highlighting source code (or source highlighting, for short).
Since this technique is so prevalent— one could say expected— Asciidoctor integrates a wealth of libraries to syntax highlight
source code blocks in your document. This list includes CodeRay, Pygments, highlight.js, and prettify.
46.1. Enabling Source Highlighting
When enabled, syntax highlighting gets applied to listing or literal blocks that have the source block style and a source language.
However, syntax highlighting is not enabled by default.
To enable syntax highlighting in a document, you must set the source-highlighter document attribute. You can set this
attribute in the document or from the CLI or API.
If you set the attribute in the document, it must be defined in the document header.
For example, here’s how to enable syntax highlighting using CodeRay:
46.2. Available Source Highlighters
The following table lists the recognized values for the source-highlighter attribute.
Recognized values and supported environments for the source-highlighter attribute
Library Name Attribute Value Supported Environments
CodeRay
(http://coderay.rubychan.de)
coderay Asciidoctor, AsciidoctorJ, Asciidoctor PDF
highlight.js
(https://highlightjs.org)
highlightjs Asciidoctor, AsciidoctorJ, Asciidoctor.js
prettify
(https://code.google.com/p/google-
code-prettify)
prettify Asciidoctor, AsciidoctorJ, Asciidoctor.js
Pygments (http://pygments.org) pygments Asciidoctor, Asciidoctor PDF
Rouge (http://rouge.jneen.net) rouge Asciidoctor PDF
To use CodeRay, Pygments, or Rouge, you must have the appropriate library installed on your system. See the
CodeRay or Pygments section to find installation instructions. (We don’t yet have a section about Rouge).
On the other hand, if you’re using a client-side syntax highlighting library like highlight.js or prettify, there’s no
need to install additional libraries. The generated HTML will load the required source files from a CDN (or
custom URL or file path).
46.3. Applying Source Highlighting
To apply highlighting to source code, you must add the source block style to a listing block, literal block, or paragraph and also
specify a source language.
Code block with title and syntax highlighting
= Document Title
:source-highlighter: <value>
ASCIIDOC
= Document Title
:source-highlighter: coderay
ASCIIDOC
12/20/2018 Asciidoctor User Manual
https://asciidoctor.org/docs/user-manual/ 187/315
1An optional title can be added to the block.
2An optional ID can be added to the block. See Defining an Anchor.
3Assign the block name source to the first position in the attribute list.
4Assign a source language to the second position.
5The source block name is typically assigned to listing and literal blocks.
Result: Source block with title and syntax highlighting
app.rb
Source paragraph
1Place the attribute list directly on the paragraph.
2Once an empty line is encountered the syntax highlighting is unset.
Result: Source paragraph
This is normal content.
If the majority of your source blocks use the same source language, you can set the source-language attribute in the document
header and assign a language to it.
Source language attribute
Additionally, you can use an include directive to insert source code into an AsciiDoc document directly from a file.
.app.rb
[#src-listing]
[source,ruby]
----
require 'sinatra'
get '/hi' do
"Hello World!"
end
----
1
2
3 4
5
require 'sinatra'
get '/hi' dodo
"Hello World!"
endend
RUBY
[source,xml]
<meta name="viewport"
content="width=device-width, initial-scale=1.0">
This is normal content.
1
2
<meta name="viewport"
content="width=device-width, initial-scale=1.0">
XML
:source-highlighter: pygments
:source-language: java
[source]
----
public void setAttributes(Attributes attributes) {
this.options.put(ATTRIBUTES, attributes.map());
}
----
You can override the global source language by specifying a source language on the block.
[source,ruby]
require 'sinatra'
12/20/2018 Asciidoctor User Manual
https://asciidoctor.org/docs/user-manual/ 188/315
Code block inserted from another file
If you specify custom substitutions on the source block using the subs attribute, make sure to include the
specialcharacters substitution if you want to preserve syntax highlighting. However, if you do plan to
modify the substitutions, we recommend using incremental substitutions instead.
Highlighting PHP source code
The PHP language has two modes. It can either be used as a standalone language (pure mode) or it can be mixed with HTML
(mixed mode) by putting it inside PHP tags (a form that resembles an XML processing instruction). This presents some
challenges for the syntax highlighter.
If the code in the source block is pure PHP, you should use the language tag php . For example:
If the PHP source is mixed with HTML, you should either use the language tag html+php , as shown here:
Or you could use the language tag php and set the mixed option on the source block, as shown here:
Under the covers, the syntax highlighter is configured to assume an implicit start PHP tag is present when the language tag
is php . Both the mixed option and the language tag html+php disable this setting.
46.4. Pygments
Pygments (http://pygments.org) is a popular syntax highlighter that supports a broad range of programming, template and markup
languages (http://pygments.org/languages/).
In order to use Pygments with Asciidoctor, you need Python 2 (https://www.python.org) and the pygments.rb gem
(https://rubygems.org/gems/pygments.rb).
You do not need to install Pygments itself. It comes bundled with the pygments.rb gem.
You must have Python 2 installed to use pygments.rb. Python 3 is not compatible with the pygments.rb gem.
Check that you have a python2 (Linux), python (macOS), or py -2 (Windows) executable on your PATH. (On
macOS, verify that the python executable uses Python 2 by running python -V ).
Installing Python and the pygments.rb gem via the CLI (cross platform)
[source,ruby]
----
include::app.rb[]
----
[source,php]
----
echo "Hello, World!";
----
[source,html+php]
----
<p>
<?php echo "Hello, World!"; ?>
</p>
----
[source%mixed,php]
----
<p>
<?php echo "Hello, World!"; ?>
</p>
----
$ "`\which apt-get || \which dnf || \which yum || \which brew`" install python
$ gem install pygments.rb
CONSOLE
1
2
12/20/2018 Asciidoctor User Manual
https://asciidoctor.org/docs/user-manual/ 189/315
1Install Python using your package manager
2Install the pygments.rb gem
Once you’ve installed these libraries, assign pygments to the source-highlighter attribute in your document’s header.
You can further customize the source block output with additional Pygments attributes.
pygments-style
Sets the name of the color theme Pygments uses. To see the list of available style names, see Available Pygments style names.
Default: pastie .
pygments-css
Controls what method is used for applying CSS to the tokens. Can be class (CSS classes) or style (inline styles). See Pygments
stylesheet to learn more about how the value class is handled. Default: class .
pygments-linenums-mode
Controls how line numbers are arranged when line numbers are enabled on the source block. Can be table or inline . If line
wrapping is enabled on preformatted blocks (i.e., prewrap ), and you want to use line numbering on source blocks, you must
set the value of this attribute to inline in order for the numbers to line up properly with their target lines. Default: table .
Customizing a source block with Pygments attributes
Result: Source block using inline line numbers and the manni theme
46.4.1. Highlight Select Lines
Not to be confused with syntax highlighting, you can configure Pygments to highlight (i.e., emphasize) select lines in order to call
attention to them. This feature is activated on a source block if the highlight attribute is defined.
The highlight attribute accepts a comma or semi-colon delimited list of line ranges. A line range is represented by two numbers
separated by a double period (e.g., 2..5 ). These numbers correspond to the line numbers of the source block, inclusive, where
the first line is 1.
Highlight select lines in a source block
:source-highlighter: pygments
ASCIIDOC
:source-highlighter: pygments
:pygments-style: manni
:pygments-linenums-mode: inline
[source,ruby,linenums]
----
ORDERED_LIST_KEYWORDS = {
'loweralpha' => 'a',
'lowerroman' => 'i',
'upperalpha' => 'A',
'upperroman' => 'I'
#'lowergreek' => 'a'
#'arabic' => '1'
#'decimal' => '1'
}
----
ASCIIDOC
12/20/2018 Asciidoctor User Manual
https://asciidoctor.org/docs/user-manual/ 190/315
46.4.2. Available Pygments style names
To list the available Pygments styles, run the following command in a terminal:
$ $(dirname $(gem which pygments.rb))/../vendor/pygments-main/pygmentize -L styles
The pygments.rb gem uses a bundled version of Pygments (often ahead of the latest release). This command ensures that you are
invoking the pygmentize command from the Pygments used by that gem.
46.4.3. Using a custom Pygments installation
If you already have Pygments installed on your system, you want to use your own fork, or you want to customize how Pygments
is configured, you can get Asciidoctor to use a custom version of Pygments instead of the one bundled with the pygments.rb gem.
First, install your own version of Pygments. You can do this, for instance, by cloning the upstream Pygments repository:
$ hg clone https://bitbucket.org/birkenfeld/pygments-main pygments
Find the directory that contains the file pygmentize or the Makefile. That’s your Pygments installation path. Make note of it.
Next, create a script to run before invoking Asciidoctor for the first time. Let’s call it pygments_init.rb. Populate the script with the
following content:
pygments_init.rb
You could enhance this script to read the Pygments installation path from an environment variable (or
configuration file).
Now just require this script before your invoke Asciidoctor the first time. When using the asciidoctor command, pass the script
using the -r flag:
$ asciidoctor -r ./pygments_init.rb document.adoc
When using the Asciidoctor API, require the script using require or require_relative :
Now Asciidoctor is using your custom installation of Pygments instead of the one bundled with the pygments.rb gem.
46.5. CodeRay
CodeRay (http://coderay.rubychan.de/) is an encoding-aware, syntax highlighter that supports the languages listed below.
:source-highlighter: pygments
[source,ruby,highlight=2..5]
----
ORDERED_LIST_KEYWORDS = {
'loweralpha' => 'a',
'lowerroman' => 'i',
'upperalpha' => 'A',
'upperroman' => 'I',
}
----
ASCIIDOC
require 'pygments'
# use a custom Pygments installation (directory that contains pygmentize)
Pygments.start '/path/to/pygments'
# example of registering a missing or additional lexer
#Pygments::Lexer.create name: 'Turtle', aliases: ['turtle'],
# filenames: ['*.ttl'], mimetypes: ['text/turtle', 'application/x-turtle']
RUBY
require 'asciidoctor'
require_relative './pygments_init.rb'
Asciidoctor.convert_file 'document.adoc', safe: :safe
RUBY
12/20/2018 Asciidoctor User Manual
https://asciidoctor.org/docs/user-manual/ 191/315
C C++ Clojure
CSS Delphi diff
ERB Go Groovy
HAML HTML Java
JavaScript JSON Lua
PHP Python Ruby
Sass SQL Taskpaper
XML YAML
In order to use CodeRay with Asciidoctor, you need the coderay RubyGem (https://rubygems.org/gems/coderay). You can use one of the
following methods to install CodeRay.
Install using gem (all systems)
$ gem install coderay
Install using apt-get (Debian-based systems)
$ sudo apt-get install coderay
Install using dnf (Fedora-based systems)
$ sudo dnf install rubygem-coderay
Once you’ve installed the RubyGem, assign the coderay value to the source-highlighter attribute in the document header to
activate it.
You can further customize the source block output with additional CodeRay attributes.
coderay-css
Controls what method is used for applying CSS to the tokens. Can be class or style . Default: class .
coderay-linenums-mode
Controls how line numbers are laid out. Can be table or inline . If line wrapping is enabled on preformatted blocks (i.e.,
prewrap ), and you want to use line numbering on source blocks, you must set the value of this attribute to inline in order
for the numbers to line up properly with their target lines. Default: table .
Customizing a source block with CodeRay line numbers
See the CodeRay stylesheet section to learn about the coderay-css attribute.
46.5.1. Highlight Select Lines
:source-highlighter: coderay
ASCIIDOC
:source-highlighter: coderay
:coderay-linenums-mode: inline
[source,ruby,linenums]
----
ORDERED_LIST_KEYWORDS = {
'loweralpha' => 'a',
'lowerroman' => 'i',
'upperalpha' => 'A',
'upperroman' => 'I'
#'lowergreek' => 'a'
#'arabic' => '1'
#'decimal' => '1'
}
----
ASCIIDOC
12/20/2018 Asciidoctor User Manual
https://asciidoctor.org/docs/user-manual/ 192/315
Not to be confused with syntax highlighting, you can configure CodeRay to highlight (i.e., emphasize) select lines in order to call
attention to them. This feature is activated on a source block if the following conditions are met:
Line numbering is enabled (i.e., the linenums option). (In CodeRay, the highlight feature is coupled with line numbering).
The highlight attribute is defined.
The highlight attribute accepts a comma or semi-colon delimited list of line ranges. A line range is represented by two numbers
separated by a double period (e.g., 2..5 ). These numbers correspond to the line numbers of the source block, inclusive, where
the first line is 1.
Highlight select lines in a source block
46.6. highlight.js
Highlight.js (https://highlightjs.org/) is a popular client-side syntax highlighter that supports a broad range of languages
(https://highlightjs.org/download/).
To use highlight.js, simply add the following attribute entry to the header of your AsciiDoc file:
By default, Asciidoctor will link to the highlight.js library and stylesheet hosted on cdnjs (https://cdnjs.com/libraries/highlight.js).
The version of the highlight.js library hosted on cdnjs only includes the basic language bundle. To enable support for a wider
range of languages (or to use a different version), follow these steps:
1. Create your custom bundle on the download page (https://highlightjs.org/download/).
2. Download and unpack the zip into a folder called highlight adjacent to your AsciiDoc file (or in the output directory, if
different)
3. Rename highlight/highlight.pack.js to highlight/highlight.min.js
4. Rename highlight/styles/github.css to highlight/styles/github.min.css
Replace github with the name of the highlightjs-theme you are using, if different.
5. Add the attribute entry :highlightjsdir: highlight to the header of your AsciiDoc file.
Alternatively, you can pass the -a highlightjsdir=highlight flag when invoking the Asciidoctor CLI.
The output file will use your personal copy of the highlight.js library and stylesheet instead of the one hosted on cdnjs.
:source-highlighter: coderay
[source,ruby,linenums,highlight=2..5]
----
ORDERED_LIST_KEYWORDS = {
'loweralpha' => 'a',
'lowerroman' => 'i',
'upperalpha' => 'A',
'upperroman' => 'I',
}
----
ASCIIDOC
:source-highlighter: highlightjs
ASCIIDOC
12/20/2018 Asciidoctor User Manual
https://asciidoctor.org/docs/user-manual/ 193/315
47. Callouts
Callout numbers (aka callouts) provide a means to add annotations to lines in a verbatim block.
Each callout number used in a verbatim block must appear twice. The first use, which goes within the verbatim block, marks the
line being annotated (i.e., the target). The second use, which goes below the verbatim block, defines the annotation text. Multiple
callout numbers may be used on a single line.
The callout number (at the target) must be placed at the end of the line.
Here’s a basic example of a verbatim block that uses callouts:
Here’s how this example gets rendered:
1Library import
2URL mapping
3Response block
Since callout number can interfere with the syntax of the code they are annotating, Asciidoctor provides several features to hide
the callout numbers from both the source and the converted document. The sections that follow detail these features.
47.1. Copy and Paste Friendly Callouts
In versions prior to Asciidoctor 0.1.4, when a reader visiting an HTML page generated by Asciidoctor selected source code from a
listing that contained callouts and copied it, the callout numbers would get caught up in the copied text. If the reader pasted that
code and tried to run it, likely the extra characters from the callouts would cause compile or runtime errors.
Asciidoctor uses CSS to prevent callouts from being selected.
On the other side of the coin, you don’t want the callout annotations or CSS messing up your raw source code either. You can tuck
your callouts neatly behind line comments. Asciidoctor will recognize the line comments characters in front of a callout number,
optionally offset by a space, and remove them when converting the document.
Here are the line comments that are supported:
Here’s how it looks when rendered:
[source,ruby]
----
require 'sinatra' <1>
get '/hi' do <2> <3>
"Hello World!"
end
----
<1> Library import
<2> URL mapping
<3> Response block
ASCIIDOC
require 'sinatra'
get '/hi' dodo
"Hello World!"
endend
RUBY
1
2 3
----
line of code // <1>
line of code # <2>
line of code ;; <3>
----
<1> A callout behind a line comment for C-style languages.
<2> A callout behind a line comment for Ruby, Python, Perl, etc.
<3> A callout behind a line comment for Clojure.
ASCIIDOC
12/20/2018 Asciidoctor User Manual
https://asciidoctor.org/docs/user-manual/ 194/315
1A callout behind a line comment for C-style languages.
2A callout behind a line comment for Ruby, Python, Perl, etc.
3A callout behind a line comment for Clojure.
47.1.1. XML Callouts
XML doesn’t have line comments, so our “tuck the callout behind a line comment” trick doesn’t work here. To use callouts in XML,
you must place the callout’s angled brackets around the the XML comment and callout number.
Here’s how it appears in a listing:
Here’s how it looks when rendered:
1The section title is required.
Notice the comment has been replaced with a circled number that cannot be selected (if not using font icons it will be rendered
differently and selectable). Now both you and the reader can copy and paste XML source code containing callouts without
worrying about errors.
47.2. Callout Icons
The font icons setting also enables callout icons drawn using CSS.
1Activates the font-based icons in the HTML5 backend.
2Admonition block that uses a font-based icon.
line of code
line of code
line of code
1
2
3
[source,xml]
----
<section>
<title>Section Title</title> <!--1-->
</section>
----
<1> The section title is required.
ASCIIDOC
<section>
<title>Section Title</title>
</section>
XML
1
= Document Title
:icons: font
NOTE: Asciidoctor now supports font-based admonition icons, powered by Font Awesome!
ASCIIDOC
1
2
12/20/2018 Asciidoctor User Manual
https://asciidoctor.org/docs/user-manual/ 195/315
48. Conditional Preprocessor Directives
You can include or exclude lines of text in your document using one of the following conditional preprocessor directives:
ifdef
ifndef
ifeval
These directives tell the processor whether to include the enclosed content based on certain conditions. The conditions are based
on the presence or value of document attributes.
For example, say you want to include a certain section of content only when converting to HTML. Conditional preprocessor
directives make this possible. You simply check for the presence of the basebackend-html attribute using an ifdef directive.
Details of this example, as well as others, are described in the following sections.
48.1. Processing
Although a conditional preprocessor directive looks like a block macro, it’s not a macro and therefore not processed like one.
Instead, it’s a preprocessor directive, just like include . It’s important to understand the distinction.
A preprocessor directive is processed when the lines are read, but before the document structure is parsed. Therefore, it’s not
aware of the surrounding document structure. A preprocessor directive merely adds lines to the reader or takes lines away. The
conditional preprocessor directives determine which lines to add and which ones to take away based on the condition.
If you don’t want a conditional preprocessor directive to be processed, you must escape it using a backslash.
\ifdef::just-an-example[]
Escaping the directive is necessary even if it appears in a verbatim block since it’s not aware of the surrounding document
structure.
48.2. ifdef Directive
Content between the ifdef and endif directives gets included if the specified attribute is set:
ifdef example
The syntax of the start directive is ifdef::<attribute>[] , where <attribute> is the name of an attribute.
Keep in mind that the content is not limited to a single line. You can have any amount of content between the ifdef and endif
directives.
If you have a large amount of content inside the ifdef directive, you may find it more readable to use the long-form version of
the directive, in which the attribute (aka condition) is referenced again in the endif directive.
ifdef long-form example
A great example of long-form conditional formatting is the source of this user manual! We use it to show and
hide entire sections when building individual content for separate guides.
ifdef::env-github[]
This content is for GitHub only.
endif::[]
ifdef::env-github[]
This content is for GitHub only.
So much content in this section, I'd get confused reading the source without the closing `ifdef` directive.
It isn't necessary for short blocks, but if you are conditionally including a section it may be something worth considering
Other readers reviewing your docs source code may go cross-eyed when reading your source docs if you don't.
endif::env-github[]
12/20/2018 Asciidoctor User Manual
https://asciidoctor.org/docs/user-manual/ 196/315
If you’re only dealing with a single line of text, you can put the content directly inside the square brackets and drop the endif
directive.
ifdef single line example
The single-line block above is equivalent to this formal ifdef directive:
48.3. ifndef Directive
ifndef is the logical opposite of ifdef . Content between ifndef and endif gets included only if the specified attribute is not
set:
ifndef Example
The syntax of the start directive is ifndef::<attribute>[] , where <attribute> is the name of an attribute.
The ifndef directive supports the same single-line and long-form variants as ifdef .
48.4. Checking multiple attributes (ifdef and ifndef only)
Both the ifdef and ifndef directives accept multiple attribute names. The combinator can be “and” or “or”.
Any attribute (or)
Multiple comma-separated (,) directive names evaluate to true, allowing the content to be included, if one or more of the
directives is defined. Otherwise the content is not included.
Any attribute example
All attributes (and)
Multiple plus-separated (+) directive names evaluate to true, allowing the content to be included, if all of the directives are
defined. Otherwise the content is not included.
All attributes example
The ifndef directive negates the results of the expression.
Starting in Asciidoctor 1.5.6, the operator logic in the ifndef directive changed to align with the behavior of
AsciiDoc Python. Specifically, when attributes are separated by commas, content is only included if none of the
attributes are defined. When attributes are separated by pluses, content is included if at least one of the
attributes is undefined. See issue #1983 (https://github.com/asciidoctor/asciidoctor/issues/1983) to find the discussion
about this behavior and the rationale for the change.
48.5. ifeval directive
Content between ifeval and endif gets included if the expression inside the square brackets evaluates to true.
ifeval example
ifdef::revnumber[This document has a version number of {revnumber}.]
ifdef::revnumber[]
This document has a version number of {revnumber}.
endif::[]
ASCIIDOC
ifndef::env-github[]
This content is not shown on GitHub.
endif::[]
ifdef::backend-html5,backend-docbook5[Only shown when converting to HTML5 or DocBook 5.]
ifdef::env-github+backend-html5[Only shown when converting to HTML5 on GitHub.]
ifeval::[{sectnumlevels} == 3]
If the `sectnumlevels` attribute has the value 3, this sentence is included.
endif::[]
12/20/2018 Asciidoctor User Manual
https://asciidoctor.org/docs/user-manual/ 197/315
The ifeval directive does not have a single-line or long-form variant like ifdef and ifndef .
48.5.1. Anatomy
The expression consists of a left-hand value and a right-hand value with an operator in between.
ifeval expression examples
48.5.2. Values
Each expression value can reference the name of zero or more AsciiDoc attribute using the attribute reference syntax (for
example, {backend} ).
Attribute references are resolved (substituted) first. Once attributes references have been resolved, each value is coerced to a
recognized type.
When the expected value is a string (i.e., a string of characters), we recommend that you enclose the expression in quotes.
The following values types are recognized:
number
Either an integer or floating-point value.
quoted string
Enclosed in either single (') or double (") quotes.
boolean
Literal value of true or false .
How value type coercion works
If a value is enclosed in quotes, the characters between the quotes are preserved and coerced to a string.
If a value is not enclosed in quotes, it is subject to the following type coercion rules:
an empty value becomes nil (aka null).
a value of true or false becomes a boolean value.
a value of only repeating whitespace becomes a single whitespace string.
a value containing a period becomes a floating-point number.
any other value is coerced to an integer value.
48.5.3. Operators
The value on each side is compared using the operator to derive an outcome.
==
Checks if the two values are equal.
!=
Checks if the two values are not equal.
<
ifeval::[2 > 1]
...
endif::[]
ifeval::["{backend}" == "html5"]
...
endif::[]
ifeval::[{sectnumlevels} == 3]
...
endif::[]
// the value of outfilesuffix includes a leading period (e.g., .html)
ifeval::["{docname}{outfilesuffix}" == "master.html"]
...
endif::[]
12/20/2018 Asciidoctor User Manual
https://asciidoctor.org/docs/user-manual/ 198/315
Checks whether the left-hand side is less than the right-hand side.
<=
Checks whether the left-hand side is less than or equal to the right-hand side.
>
Checks whether the left-hand side is greater than the right-hand side.
>=
Checks whether the left-hand side is greater than or equal to the right-hand side.
The operators follow the same rules as operators in Ruby.
12/20/2018 Asciidoctor User Manual
https://asciidoctor.org/docs/user-manual/ 199/315
49. Docinfo Files
You can add custom content to the head or footer of an output document using docinfo files. Docinfo files are useful for injecting
auxiliary metadata, stylesheet, and script information into the output not added by the converter.
Different docinfo files get used depending on whether you are converting to HTML or DocBook (but don’t yet apply when
converting to PDF).
49.1. Head docinfo les
The content of head docinfo files gets injected into the top of the document. For HTML, the content is append to the <head>
element. For DocBook, the content is appended to the root <info> element.
The docinfo file for HTML output may contain valid elements to populate the HTML <head> element, including:
<base>
<link>
<meta>
<noscript>
<script>
<style>
Use of the <title> element is not recommend as it’s already emitted by the converter.
You do not need to include the enclosing <head> tag as it’s assumed to be the envelop.
Here’s an example:
A head docinfo file for HTML output
Docinfo files for HTML output must be saved with the .html file extension. See Naming docinfo files for more details.
The docinfo file for DocBook 5.0 output may include any of the <info> element’s children (https://tdg.docbook.org/tdg/5.0/info.html),
such as:
<address>
<copyright>
<edition>
<keywordset>
<publisher>
<subtitle>
<revhistory>
The following example shows some of the content a docinfo file for DocBook might contain.
A docinfo file for DocBook 5.0 output
<meta name="keywords" content="open source, documentation">
<meta name="description" content="The dangerous and thrilling adventures of an open source documentation team.">
<link rel="stylesheet" href="basejump.css">
<script src="map.js"></script>
HTML
12/20/2018 Asciidoctor User Manual
https://asciidoctor.org/docs/user-manual/ 200/315
Docinfo files for DocBook output must be saved with the .xml file extension. See Naming docinfo files for more details.
To see a real-world example of a docinfo file for DocBook, checkout the RichFaces Developer Guide docinfo file
(https://github.com/richfaces/richfaces-docs/blob/master/Developer_Guide/src/main/docbook/en-US/Developer_Guide-docinfo.xml).
49.2. Footer docinfo les
Footer docinfo files are differentiated from head docinfo files by the addition of -footer to the file name. In the HTML output,
the footer content is inserted immediately after the footer div (i.e., <div id="footer"> ). In the DocBook output, the footer
content is inserted immediately before the ending tag (e.g., </article> or </book> ).
One possible use of the footer docinfo file is to completely replace the default footer in the standard stylesheet.
Just set the attribute nofooter , then apply a custom footer docinfo file.
49.3. Naming docinfo les
The file that gets selected to provide the docinfo depends on which converter is in use (html, docbook, etc) and whether the
docinfo scope is configured for a specific document (“private”) or for all documents in the same directory (“shared”). The file
extension of the docinfo file must match the file extension of the output file (as specified by the outfilesuffix attribute, a value
which always begins with a period ( .)).
Docinfo file naming
Mode Location Behavior Docinfo file name
Private Head Adds content to <head> /<info> for
<docname>.adoc files.
<docname>-docinfo<outfilesuffix>
Footer Adds content to end of document for
<docname>.adoc files.
<docname>-docinfo-
footer<outfilesuffix>
Shared Head Adds content to <head> /<info> for
any document in same directory.
docinfo<outfilesuffix>
Footer Adds content to end of document for
any document in same directory.
docinfo-footer<outfilesuffix>
To specify which file(s) you want to apply, set the docinfo attribute to any combination of these values:
private-head
private-footer
private (alias for private-head,private-footer )
shared-head
shared-footer
shared (alias for shared-head,shared-footer )
<author>
<personname>
<firstname>Karma</firstname>
<surname>Chameleon</surname>
</personname>
<affiliation>
<jobtitle>Word SWAT Team Leader</jobtitle>
</affiliation>
</author>
<keywordset>
<keyword>open source</keyword>
<keyword>documentation</keyword>
<keyword>adventure</keyword>
</keywordset>
<printhistory>
<para>April, 2019. Twenty-sixth printing.</para>
</printhistory>
XML
12/20/2018 Asciidoctor User Manual
https://asciidoctor.org/docs/user-manual/ 201/315
Setting docinfo with no value is equivalent to setting the value to private .
For example:
This docinfo configuration will apply the shared docinfo head and footer files, if they exist, as well as the private footer file, if it
exists.
docinfo attribute values were introduced in Asciidoctor 1.5.5 to replace the less descriptive docinfo1 and
docinfo2 attributes. Here are the equivalents of the old attributes using the new values:
:docinfo: = :docinfo: private
:docinfo1: = :docinfo: shared
:docinfo2: = :docinfo: shared,private
Let’s apply this to an example:
You have two AsciiDoc documents, adventure.adoc and insurance.adoc, saved in the same folder. You want to add the same
content to the head of both documents when they’re converted to HTML.
1. Create a docinfo file containing <head> elements.
2. Save it as docinfo.html.
3. Set the docinfo attribute in adventure.adoc and insurance.adoc to shared .
You also want to include some additional content, but only to the head of adventure.adoc.
1. Create another docinfo file containing <head> elements.
2. Save it as adventure-docinfo.html.
3. Set the docinfo attribute in adventure.adoc to shared,private-head
If other AsciiDoc files are added to the same folder, and docinfo is set to shared in those files, only the docinfo.html file will be
added when converting those files.
49.4. Locating docinfo les
By default, docinfo files are searched for in the same folder as the document file. If you want to keep them anywhere else, set the
docinfodir attribute to their location:
Note that if you use this attribute, only the specified folder will be searched; docinfo files in the document folder will no longer be
found.
49.5. Attribute substitution in docinfo les
Docinfo files may include attribute references. Which substitutions get applied is controlled by the docinfosubs attribute, which
takes a comma-separated list of substitution names. The value of this attribute defaults to attributes .
For example, if you created the following docinfo file:
Docinfo file containing a revnumber attribute reference
And this source document:
Source document including a revision number
:docinfo: shared,private-footer
ASCIIDOC
:docinfodir: common/meta
ASCIIDOC
<edition>{revnumber}</edition>
XML
12/20/2018 Asciidoctor User Manual
https://asciidoctor.org/docs/user-manual/ 202/315
Then the converted DocBook output would be:
1The revnumber attribute reference was replaced by the source document’s revision number in the converted output.
= Document Title
Author Name
v1.0, 2019-06-01
:doctype: book
:backend: docbook
:docinfo:
ASCIIDOC
<?xml version="1.0" encoding="UTF-8"?>
<book xmlns="http://docbook.org/ns/docbook"
xmlns:xlink="http://www.w3.org/1999/xlink" version="5.0" lang="en">
<info>
<title>Document Title</title>
<date>2019-06-01</date>
<author>
<personname>
<firstname>Author</firstname>
<surname>Name</surname>
</personname>
</author>
<authorinitials>AN</authorinitials>
<revhistory>
<revision>
<revnumber>1.0</revnumber>
<date>2019-06-01</date>
<authorinitials>AN</authorinitials>
</revision>
</revhistory>
</info>
</book>
XML
1
12/20/2018 Asciidoctor User Manual
https://asciidoctor.org/docs/user-manual/ 203/315
50. Counters
Counters are used to store and display ad-hoc sequences of numbers or latin characters. They are designed for simple use cases.
Possible uses include inline itemized lists, paragraph numbers and serial item numbers.
A counter is implemented as a specialized document attribute. You declare and display a counter using an augmented attribute
reference, in which the attribute name is prefixed with counter: (e.g., {counter:name} ). Since counters are attributes, counter
names follow the same rules as attribute names. The most important rule to note is that letters in counter names must be
lowercase.
The counter value is incremented and displayed every time the counter: attribute reference is used. The term increment means
advance to the next value in the sequence. If the counter value is an integer, add 1. If the counter value is a character, move to the
next letter in the Latin alphabet. The default start value of a counter is 1.
To create a sequence starting at 1, use the simple form {counter:name} as shown here:
Here’s the resulting output:
The salad calls for 1) apples, 2) oranges and 3) pears.
To increment the counter without displaying it (i.e., to skip an item in the sequence), use the counter2 prefix instead:
A counter2 attribute reference on a line by itself will produce an empty paragraph. You’ll need to adjoin it to
the nearest content to avoid this side effect.
To display the current value of the counter without incrementing it, reference the counter name as you would any other attribute:
To create a character sequence, or start a number sequence with a value other than 1, specify a start value by appending it to the
first use of the counter:
Character sequences either run from a,b,c,… x,y,z,{,|… or A,B,C,… ,X,Y,Z,[,… depending on the start value.
Therefore, they aren’t really useful for more than 26 items.
The start value of a counter is only recognized if the counter is unset at that point in the document. Otherwise, the start value is
ignored.
To reset a counter attribute, unset the corresponding attribute using an attribute entry. The attribute entry must be adjacent to a
block or else it is ignored.
This gives:
The salad calls for 1) apples, 2) oranges and 3) pears.
Dessert calls for A) mangoes, B) grapes and C) cherries.
The salad calls for {counter:seq1}) apples, {counter:seq1}) oranges and {counter:seq1}) pears.
ASCIIDOC
{counter2:seq1}
ASCIIDOC
{counter2:pnum}This is paragraph {pnum}.
ASCIIDOC
Dessert calls for {counter:seq1:A}) mangoes, {counter:seq1}) grapes and {counter:seq1}) cherries.
ASCIIDOC
The salad calls for {counter:seq1:1}) apples, {counter:seq1}) oranges and {counter:seq1}) pears.
:!seq1:
Dessert calls for {counter:seq1:A}) mangoes, {counter:seq1}) grapes and {counter:seq1}) cherries.
ASCIIDOC
12/20/2018 Asciidoctor User Manual
https://asciidoctor.org/docs/user-manual/ 204/315
Here’s a full example that shows how to use a counter for part numbers in a table.
Here’s the output of that table:
Parts
Part Id Description
PX-1 Description of PX-1
PX-2 Description of PX-2
[caption=""]
.Parts{counter2:index:0}
|===
|Part Id |Description
|PX-{counter:index}
|Description of PX-{index}
|PX-{counter:index}
|Description of PX-{index}
|===
ASCIIDOC
12/20/2018 Asciidoctor User Manual
https://asciidoctor.org/docs/user-manual/ 205/315
Structuring, Navigating, and Referencing Your Content
Asciidoctor provides macros or attributes for the specialized frontmatter and backmatter sections commonly found in journal
articles, academic papers, and books. In the following sections, you’ll learn the dependency, structure, and output rules for the
special section macros and attributes and how to use them.
12/20/2018 Asciidoctor User Manual
https://asciidoctor.org/docs/user-manual/ 206/315
51. Colophon
Book colophons list information such as the ISBN, publishing house, edition and copyright dates, legal notices and disclaimers,
cover art, design, and book layout credits, and any significant production notes. In most mass market books, the colophon is on
the verso (back side) of the title page, but it can also be located at the end of the book.
[colophon]
= Colophon
The Asciidoctor Press, Ceres and Denver
(C) 2018 by The Asciidoctor Press
Published in the Milky Way Galaxy
This book is designed by Dagger Flush, Denver, Colorado.
The types are handset Chinchilla and Dust, designed by Leeloo.
Leeloo designed the typefaces to soften the bluntness of documentation.
Created in Asciidoctor and Fedora 27.
The printing and binding is by Ceres Lithographing, Inc., Ceres, Milky Way.
ASCIIDOC
12/20/2018 Asciidoctor User Manual
https://asciidoctor.org/docs/user-manual/ 207/315
52. Table of Contents
A table of contents (TOC) is an index of section and subsection titles that can be automatically generated from the document’s
structure when converting a document with Asciidoctor.
To enable the auto-generated TOC, you must set the toc attribute.
The toc attribute can be specified via the command line ( -a toc ),
TOC enabled via the CLI
or in the document header ( :toc: ).
TOC enabled via the document header
When no other options are specified, the TOC is inserted directly below the document header (document title, author, and
revision lines), it has the title Table of Contents, and contains section 1 and section 2 level titles only.
Result: Setting the toc attribute
Asciidoctor allows you to customize the layout, placement, and title of the table of contents. However, not all customizations are
supported by all converters. See the Table of Contents Summary to find out which customizations are available to each backend.
52.1. In-Document Placement
toc values of auto (the default), preamble , and macro place the TOC in the main document area.
When the value of toc attribute is unspecified or auto , the TOC is inserted directly below the document header (document title,
author and revision lines).
When toc is set to preamble , the TOC is placed immediately below the preamble.
$ asciidoctor -a toc adventure.adoc
= The Dangerous and Thrilling Documentation Chronicles
Kismet Chameleon
:toc:
This journey begins on a bleary...
== Cavern Glow
The river rages through the cavern, rattling its content...
ASCIIDOC
12/20/2018 Asciidoctor User Manual
https://asciidoctor.org/docs/user-manual/ 208/315
When using the preamble placement, the TOC will not appear if your document does not have a preamble. To
fix this problem, just set the toc attribute to an empty value (or auto ).
To place the TOC anywhere else in the document, set the toc attribute to macro . Then, put the block toc macro ( toc::[] ) at the
location in the document where you want the TOC to appear. The toc macro should appear at most once in any document.
If toc is not set to macro , any toc macro in the document will be silently ignored.
Setting toc value to macro and using the block toc macro
1The toc attribute must be set to macro in order to enable the use of the toc macro.
2In this example, the toc macro is placed below the first section’s title, indicating that this is the location where the TOC
will be displayed once the document is rendered.
Result: Setting toc value to macro and using the block toc macro
52.2. Side Column Placement
When converting to HTML, you can position the TOC to the left or right of the main content column by assigning the value left
or right to the toc attribute, respectively. In this case, the sidebar column containing the TOC is both fixed and scrollable.
Assigning the left value to toc
= The Dangerous and Thrilling Documentation Chronicles
Kismet Chameleon
:toc: macro
This journey begins on a bleary...
== Cavern Glow
toc::[]
The river rages through the cavern, rattling its content...
ASCIIDOC
1
2
12/20/2018 Asciidoctor User Manual
https://asciidoctor.org/docs/user-manual/ 209/315
Result: Assigning the left value to toc
This positioning is achieved using CSS, which means it depends on support from the stylesheet. However, it’s only honored if
there’s sufficient room on the screen for a sidebar column. If there isn’t sufficient room available (i.e., the screen width falls below
a certain breakpoint), the TOC will automatically shift back to the center, appearing directly below the document title.
The TOC is always placed in the center in an embeddable HTML document, regardless of the value of the toc
attribute.
52.3. Title
The toc-title attribute allows you to change the title of the TOC.
Defining a new TOC title
1The toc attribute must be set in order to use toc-title.
2toc-title is set and assigned the value Table of Adventures in the document’s header.
Result: Defining a new TOC title
= The Dangerous and Thrilling Documentation Chronicles
Kismet Chameleon
:toc: left
This journey begins on a bleary...
== Cavern Glow
The river rages through the cavern, rattling its content...
== The Ravages of Writing
Her finger socks had been vaporized by crystalline nuggets of...
=== A Recipe for Potion
Two fresh Burdockian leaves, harvested by the light of the teal moons...
ASCIIDOC
= The Dangerous and Thrilling Documentation Chronicles
Kismet Chameleon
:toc:
:toc-title: Table of Adventures
This journey begins on a bleary...
== Cavern Glow
The river rages through the cavern, rattling its content...
ASCIIDOC
1
2
12/20/2018 Asciidoctor User Manual
https://asciidoctor.org/docs/user-manual/ 210/315
52.4. Levels
By default, the TOC will display level 1 and level 2 section titles. You can set a different depth with the toclevels attribute.
Defining a new toclevels value
1The toc attribute must be set in order to use toclevels .
2toclevels is set and assigned the value 4 in the document’s header. The TOC will list the titles of the section 1, 2, 3, and
4 levels when the document is rendered.
Result: Defining a new toclevels value
= The Dangerous and Thrilling Documentation Chronicles
Kismet Chameleon
:toc:
:toclevels: 4
This journey begins on a bleary...
== Cavern Glow
The river rages through the cavern, rattling its content...
== The Ravages of Writing
Her finger socks had been vaporized by crystalline nuggets of...
=== A Recipe for Potion
Two fresh Burdockian leaves, harvested by the light of the teal moons...
==== Searching for Burdockian
Crawling through the twisted understory...
ASCIIDOC
1
2
12/20/2018 Asciidoctor User Manual
https://asciidoctor.org/docs/user-manual/ 211/315
52.5. Using a TOC with Embeddable HTML
When AsciiDoc is converted to embeddable HTML (i.e., the header_footer option is false ), there are only three valid values
for the toc attribute:
auto (or unspecified value)
preamble
macro
All of the following environments convert AsciiDoc to embeddable HTML:
the file viewer on GitHub and GitLab
the AsciiDoc preview in an editor like Atom, Brackets or AsciidocFX
the Asciidoctor browser extensions
The side column placement (left or right) isn’t available in this mode. That’s because the embeddable HTML
doesn’t have the outer framing (or the CSS) necessary to support a side column TOC.
52.6. Table of Contents Summary
Table of contents attributes and allowed values
Attribute Values Example Syntax Comments Backends
toc auto, left,
right, macro,
preamble
:toc: left Not set by default. Defaults to auto if
value is unspecified.
html
auto, macro,
preamble
:toc: macro Not set by default. Defaults to auto if
value is unspecified.
html
(embeddable)
12/20/2018 Asciidoctor User Manual
https://asciidoctor.org/docs/user-manual/ 212/315
Attribute Values Example Syntax Comments Backends
auto :toc: Not set by default. The table of
contents is placed after the title page
(See issue #233
(https://github.com/asciidoctor/asciidoctor-
pdf/issues/233)
for developments).
pdf
auto :toc: Not set by default. The placement
and styling of the table of contents is
determined by the DocBook
toolchain configuration.
docbook
toclevels 1–5 :toclevels: 4 Default value is 2. html, pdf
toc-title <text> :toc-title: Contents Default value is Table of Contents. html, pdf
12/20/2018 Asciidoctor User Manual
https://asciidoctor.org/docs/user-manual/ 213/315
53. Abstract
An abstract is a concise overview of an article or of a chapter in a book. They are frequently found in the frontmatter of academic,
research, and analytical papers. A complete (i.e., informative) abstract states the key topics and findings while a limited (i.e.,
descriptive) abstract briefly describes the structure of the content.
The abstract may be written using a section, open block, or paragraph and must bear the abstract style. If used, the abstract must
appear before the first section of an article (at the start of the preamble) or at the start of a chapter in a book. An abstract may not
be used before a part or chapter in a book.
Here’s an example of an abstract at the beginning of an article, defined using a section:
Here’s an example of the same abstract defined using a paragraph:
In the book doctype, the abstract section must be a level below the chapter.
An abstract defined using an open block or paragraph does not require a title and does not depend on a subsequent section to
terminate.
To include a quote at the beginning of a chapter in a book, wrap the quote block inside an abstract block.
= Article Title
[abstract]
== Abstract
Documentation is a distillation of many long, squiggly adventures.
== First Section
ASCIIDOC
= Article Title
[abstract]
.Abstract
Documentation is a distillation of many long, squiggly adventures.
== First Section
ASCIIDOC
== Chapter Title
[abstract]
=== Chapter Abstract
Documentation is a distillation of many long, squiggly adventures.
=== First Section
ASCIIDOC
= Article Title
[abstract]
.Optional Abstract Title
--
This article will take you on a wonderful adventure of knowledge.
You'll start with the basics.
Beyond that, where you go is up to you.
--
Your journey begins here.
ASCIIDOC
12/20/2018 Asciidoctor User Manual
https://asciidoctor.org/docs/user-manual/ 214/315
54. Preface
The preface is a special section of a book that precedes the first part or chapter of the book (or the first chapter of a part). The
preface can contain subsections.
An author explains how the idea behind her book manifested and developed in the preface. The preface can include
acknowledgments and may be signed by the author with her name, writing date and location.
For multi-part books, the preface must be defined as a level-0 section and any subsections must start at level 2.
For books without parts, the preface must be defined as a level-1 section and any subsections must start at level 2.
The same structure can be used to define a preface for a part.
As an alternative to a special section, Asciidoctor will automatically promote the preamble to a preface. The title of the preface is
set using the preface-title document attribute. When defined this way, the preface may not contain subsections.
The special section is the preferred way of defining a preface.
= Book Title
:doctype: book
[preface]
= Documentation Preface
The basis for this documentation germinated when I awoke one morning and was confronted by the dark and stormy eyes of the
She had conquered the mountain of government reports that, over the course of six months, had eroded into several minor foo
=== Acknowledgments in Preface
I'd like to thank the Big Bang and String Theory.
Would we be without them?
= Part 1
...
ASCIIDOC
= Book Title
:doctype: book
[preface]
== Documentation Preface
The basis for this documentation germinated when I awoke one morning and was confronted by the dark and stormy eyes of the
She had conquered the mountain of government reports that, over the course of six months, had eroded into several minor foo
=== Acknowledgments in Preface
I'd like to thank the Big Bang and String Theory.
Would we be without them?
== Chapter 1
...
ASCIIDOC
= Book Title
:doctype: book
:preface-title: Documentation Preface
The basis for this documentation germinated when I awoke one morning and was confronted by the dark and stormy eyes of the
She had conquered the mountain of government reports that, over the course of six months, had eroded into several minor foo
== Chapter 1
...
ASCIIDOC
12/20/2018 Asciidoctor User Manual
https://asciidoctor.org/docs/user-manual/ 216/315
56. Book Parts and Chapters
You may group the sections of your document into parts when you set the doctype to book . In fact, parts can only be used when
the doctype is book .
When a document has its doctype set to book and contains at least one part, it implicitly becomes a multi-part book. There is no
dedicated doctype value for a multi-part book to distinguish it from a regular book. That distinction is made by the content.
Part titles are specified with a single equals sign ( =), the equivalent to the structure of a document title (i.e., level-0 section). Each
part must contain at least one section (a chapter or special section). Immediately after the part title, you may insert an optional
introduction, which is designated by the partintro style.
A part can also include its own preface, bibliography, glossary and index.
When using the PDF converter (i.e., Asciidoctor PDF), the value of the chapter-label attribute (followed by a space) is
automatically added to the beginning of the chapter title. A chapter title is a level-1 section title when the doctype is book.
You can modify this prefix by redefining the chapter-label attribute.
To use no prefix, set the value to blank.
[partintro]
.Optional part introduction title
--
Optional part introduction goes here.
--
ASCIIDOC
= Title of Part 1
[partintro]
--
This is the introduction to the first part of our mud-encrusted journey.
--
== Chapter 1
There was mud...
== Chapter 2
Great gobs of mud...
[glossary]
== Part 1 Glossary
[glossary]
mud:: wet, cold dirt
= Part 2
[preface]
== Part 2 Preface
This part was written because...
== Chapter 1
The mud had turned to cement...
ASCIIDOC
:chapter-label: Chapter ~
ASCIIDOC
12/20/2018 Asciidoctor User Manual
https://asciidoctor.org/docs/user-manual/ 217/315
57. Appendix
You can indicate that a section, part, or chapter is an appendix by adding an [appendix] line above the section title.
While the AsciiDoc structure allows appendices to be placed anywhere, it’s customary to place them at the end of the document,
after all other sections.
Sections marked as appendix have a different title, which is built as follows:
A fixed prefix (taken from the value of the appendix-caption attribute, which defaults to “Appendix”)
A letter that represents the number of this appendix within the sequence of appendices (A, B, C, … )
A colon
The original section title
For example:
Appendix A: Copyright and License
The prefix can be modified by defining the appendix-caption attribute. This value can be changed using:
Or it can be unset using:
Appendices can have subsections. However, there are some rules to follow depending on which type of document you are
creating.
For articles, the appendix must be defined as a level-1 section. (If a level-0 section is used, a level-1 section is implied). For
example:
The table of contents will appear as follows:
[appendix]
== Copyright and License
ASCIIDOC
:appendix-caption: Appx
ASCIIDOC
:appendix-caption!:
ASCIIDOC
= Article Title
:appendix-caption: Appx
:sectnums:
:toc:
== First Section
=== Subsection
[appendix]
== First Appendix
=== First Subsection
=== Second Subsection
[appendix]
== Second Appendix
ASCIIDOC
1. First Section
1.1. Subsection
Appx A: First Appendix
1.1. First Subsection
1.2. Second Subsection
Appx B: Second Appendix
ASCIIDOC
12/20/2018 Asciidoctor User Manual
https://asciidoctor.org/docs/user-manual/ 218/315
For books, the appendix must be defined as a level-1 section if you want the appendix to be a adjacent to other chapters (and in
the current part if the book has multiple parts). In a multi-part book, if you want the appendix to be adjacent to other parts, the
appendix must be defined as a level-0 section. In either case, the first subsection of the appendix must be a level-3 section, not a
level-2 section. That’s because an appendix cannot contain chapters.
The following example shows how to define an appendix for a multi-book (take away the part title if you’re creating a simple
book):
The table of contents will appear as follows:
= Book Title
:doctype: book
:appendix-caption: Appx
:sectnums:
:toc:
= First Part
== First Chapter
=== Subsection
[appendix]
= First Appendix
=== First Subsection
=== Second Subsection
[appendix]
= Second Appendix
ASCIIDOC
First Part
1. First Chapter
1.1. Subsection
Appx A: First Appendix
1.1. First Subsection
1.2. Second Subsection
Appx B: Second Appendix
ASCIIDOC
12/20/2018 Asciidoctor User Manual
https://asciidoctor.org/docs/user-manual/ 219/315
58. Glossary
You can include a glossary of definitions by including the [glossary] marker before the section header and before the first
definition.
[glossary]
== Glossary
[glossary]
mud:: wet, cold dirt
rain::
water falling from the sky
ASCIIDOC
12/20/2018 Asciidoctor User Manual
https://asciidoctor.org/docs/user-manual/ 220/315
59. Bibliography
AsciiDoc has basic support for bibliographies. AsciiDoc doesn’t concern itself with the structure of the bibliography entry itself,
which is entirely freeform. What it does is provide a way to make references to the entries from the same document and output
the bibliography with proper semantics for processing by other toolchains (such as DocBook).
In order to reference a bibliography entry, you need to assign a non-numeric label to the entry. To assign this label, prefix the
entry with the label enclosed in a pair of triple square brackets (e.g., [[[label]]] ). We call this a bibliography anchor. Using this
label, you can then reference the entry from anywhere above the bibliography in the same document using the normal cross
reference syntax (e.g., <<label>> ).
By default, the bibliography anchor and reference to the bibliography entry is converted to [<label>] , where <label> is the ID of
the entry. If you specify xreftext on the bibliography anchor (e.g., [[[label,xreftext]]] ), the bibliography anchor and
reference to the bibliography entry converts to [<xreftext>] instead.
If you want the bibliography anchor and reference to appear as a number, assign the number of the entry using the xreftext. For
example, [[[label,1]]] will be converted to [1] .
The bibliography entries themselves are declared as items in an unordered list. You promote a normal unordered list to a
bibliography list by adding the bibliography style. However, to be conforming, bibliography lists must be contained inside a
bibliography section. A bibliography section is a section with the special bibliography style. By adding the bibliography style
to the section, you implicitly add it to each unordered list in that section.
If the bibliography style is used on an unordered list outside of a bibliography section, the resulting behavior is
undefined.
Let’s consider an example.
Bibliography with inbound references
This renders as:
_The Pragmatic Programmer_ <<pp>> should be required reading for all developers.
To learn all about design patterns, refer to the book by the "`Gang of Four`" <<gof>>.
[bibliography]
== References
- [[[pp]]] Andy Hunt & Dave Thomas. The Pragmatic Programmer:
From Journeyman to Master. Addison-Wesley. 1999.
- [[[gof,2]]] Erich Gamma, Richard Helm, Ralph Johnson & John Vlissides. Design Patterns:
Elements of Reusable Object-Oriented Software. Addison-Wesley. 1994.
ASCIIDOC
12/20/2018 Asciidoctor User Manual
https://asciidoctor.org/docs/user-manual/ 222/315
References
[pp] Andy Hunt & Dave Thomas. The Pragmatic Programmer: From Journeyman to Master. Addison-Wesley. 1999.
[2] Erich Gamma, Richard Helm, Ralph Johnson & John Vlissides. Design Patterns: Elements of Reusable Object-Oriented
Software. Addison-Wesley. 1994.
If you want more advanced features such as automatic numbering and custom citation styles, try the asciidoctor-bibtex
(https://github.com/asciidoctor/asciidoctor-bibtex) project.
To escape a bibliography anchor anywhere in the text, use the syntax [[[word]]] . This prevents the anchor
from being matched as a bibliography anchor or a normal anchor.
12/20/2018 Asciidoctor User Manual
https://asciidoctor.org/docs/user-manual/ 223/315
60. Index
You can mark index terms explicitly in AsciiDoc content. Index terms form a controlled vocabulary that can be used to navigate
the document by keyword starting from an index.
60.1. Index Terms
There are two types of index terms in AsciiDoc:
flow index term
indexterm2:[<primary>] or ((<primary>))
An index term that appears in the flow of text (i.e., a visible term) and in the index. This type of index term can only be used to
define a primary entry.
concealed index term
indexterm:[<primary>, <secondary>, <tertiary>] or (((<primary>, <secondary>, <tertiary>)))
A group of index terms that appear only in the index. This type of index term can be used to define a primary entry as well as
optional secondary and tertiary entries.
Here’s an example that shows the two forms in use.
1The double parenthesis form adds a primary index term and includes the term in the generated output.
2The triple parenthesis form allows for an optional second and third index term and does not include the terms in the
generated output (i.e., concealed index term).
3The inline macro indexterm2:[primary] is equivalent to the double parenthesis form.
4The inline macro indexterm:[primary, secondary, tertiary] is equivalent to the triple parenthesis form.
If you’re defining a concealed index term (i.e., the indexterm macro), and one of the terms contains a comma, you must
surround that segment in double quotes so the comma is treated as content. For example:
or
60.2. Index Catalog
Although index terms are always processed, only Asciidoctor PDF and the DocBook toolchain support creating an index catalog
automatically. To create an index, define a level-1 section marked with the style index at the end of your document.
Both Asciidoctor PDF and the DocBook toolchain will automatically populate an index into this seed section.
The Lady of the Lake, her arm clad in the purest shimmering samite,
held aloft Excalibur from the bosom of the water,
signifying by divine providence that I, ((Arthur)),
was to carry Excalibur (((Sword, Broadsword, Excalibur))).
That is why I am your king. Shut up! Will you shut up?!
Burn her anyway! I'm not a witch.
Look, my liege! We found them.
indexterm2:[Lancelot] was one of the Knights of the Round Table.
indexterm:[knight, Knight of the Round Table, Lancelot]
1
2
3
4
I, King Arthur.
indexterm:[knight, "Arthur, King"]
I, King Arthur.
(((knight, "Arthur, King")))
[index]
== Index
12/20/2018 Asciidoctor User Manual
https://asciidoctor.org/docs/user-manual/ 225/315
61. Footnotes
A footnote is created with the footnote macro ( footnote:[] ). If you plan to reference a footnote more than once, use the
footnoteref macro ( footnoteref:[] ).
Footnote syntax
1Insert the footnote macro directly after any punctuation. Note that the footnote macro only uses one colon ( :).
2Insert the footnote’s content within the square brackets ( [] ). The text may span several lines.
3If you plan to reuse a footnote, use footnoteref: and provide a unique ID in the first position inside the square
brackets when you create it.
4Separate the ID from the footnote text with a comma. Do not enter a space between the comma and the footnote text.
5The next time you reference the footnote you only need to insert the ID in the square brackets.
The footnotes will be numbered consecutively throughout the article.
Rendered footnotes
The hail-and-rainbow protocol can be initiated at five levels: double, tertiary, supernumerary, supermassive, and
apocalyptic party.[2] A bold statement![3]
Another outrageous statement.[3]
The hail-and-rainbow protocol can be initiated at five levels: double, tertiary, supernumerary, supermassive, and apocalypt
A bold statement!footnoteref:[disclaimer,Opinions are my own.]
Another outrageous statement.footnoteref:[disclaimer]
ASCIIDOC
3 4
5
2. The double hail-and-rainbow level makes my toes tingle.
3. Opinions are my own.
12/20/2018 Asciidoctor User Manual
https://asciidoctor.org/docs/user-manual/ 226/315
Processing Your Content
While the AsciiDoc syntax is designed to be readable in raw form, the intended audience for that format are writers and editors.
Readers aren’t going to appreciate the raw text nearly as much. Aesthetics matter. You’ll want to apply nice typography with font
sizes that adhere to the golden ratio, colors, icons and images to give it the respect it deserves. That’s where converters, backends,
and themes come into play.
12/20/2018 Asciidoctor User Manual
https://asciidoctor.org/docs/user-manual/ 227/315
62. Selecting an Output Format
The Asciidoctor processor is typically used to parse an AsciiDoc document and convert it to a variety of formats, such as HTML,
DocBook, or PDF. This section describes how to specify the output format.
The processor generates the output format using a converter. Each converter is mapped to the name of a backend. You specify the
backend— and, in turn, the converter— using the -b ( --backend ) command line option or backend API option. If no backend is
specified, the processor uses the converter for the default backend ( html5 ).
Asciidoctor provides several built-in converters, which are mapped to the following backend names:
html (or html5)
HTML 5, styled with CSS3 (default).
xhtml (or xhtml5)
The XHTML variant of the output from html5 .
docbook (or docbook5)
DocBook 5.0 XML.
docbook45
DocBook 4.5 XML.
manpage
Manual pages for Unix and Unix-like operating systems.
Asciidoctor also has several add-on converters, which can be plugged in by adding the appropriate library to the runtime path
(e.g., -r asciidoctor-pdf ). These converters are mapped to the following backend names:
pdf
PDF, a portable document format. Requires the asciidoctor-pdf (https://rubygems.org/gems/asciidoctor-pdf) gem.
epub3
EPUB3, a distribution and interchange format standard for digital publications and documents. Requires the asciidoctor-epub3
(https://rubygems.org/gems/asciidoctor-epub3) gem.
latex
LaTeX, a document preparation system for high-quality typesetting. Requires the asciidoctor-latex
(https://rubygems.org/gems/asciidoctor-latex) gem.
mallard
Mallard 1.0 XML. Requires the asciidoctor-mallard (https://github.com/asciidoctor/asciidoctor-mallard) gem (not yet released).
There are also converters available for HTML5 presentation systems such as reveal.js and Bespoke.js. Those converters are still in
development and will be documented once releases become available.
12/20/2018 Asciidoctor User Manual
https://asciidoctor.org/docs/user-manual/ 228/315
63. HTML
Asciidoctor’s default output format is HTML.
html5
HTML 5 markup styled with CSS3.
63.1. Using the Command Line
In this section, we’ll create a sample document, then process and convert it with Asciidoctor’s html5 converter.
1. Create an AsciiDoc file like the one below
2. Save the file as mysample.adoc
To convert mysample.adoc to HTML from the command line:
1. Open a console
2. Switch to the directory that contains the mysample.adoc document
3. Call the Asciidoctor processor with the asciidoctor command, followed by the name of the document you want to convert
$ asciidoctor mysample.adoc
Remember, Asciidoctor’s default converter is html5, so it isn’t necessary to specify it with the -b command.
You won’t see any messages printed to the console. If you type ls or view the directory in a file manager, there is a new file
named mysample.html.
$ ls
mysample.adoc mysample.html
Asciidoctor derives the name of the output document from the name of the input document.
Open mysample.html in your web browser. Your document should look like the image below.
= My First Experience with the Dangers of Documentation
In my world, we don't have to worry about mutant, script-injecting warlocks.
No.
We have something far worse.
We're plagued by Wolpertingers.
== Origins
You may not be familiar with these https://en.wikipedia.org/wiki/Wolpertinger[ravenous beasts], but, trust me, they'll eat
ASCIIDOC
12/20/2018 Asciidoctor User Manual
https://asciidoctor.org/docs/user-manual/ 229/315
The document’s text, titles, and link is styled by the default Asciidoctor stylesheet, which is embedded in the HTML output. As a
result, you could save mysample.html to any computer and it will look the same.
63.2. Using the Ruby API
Asciidoctor also includes a Ruby API that lets you generate an HTML document directly from a Ruby application.
Alternatively, you can capture the HTML output in a variable instead of writing it to a file.
The convert methods also accept a map of options. Use of this map is described in Ruby API Options.
63.3. Styling the HTML with CSS
Asciidoctor uses CSS for HTML document styling and JavaScript for generating document attributes such as a table of contents
and footnotes. It comes bundled with a stylesheet, named asciidoctor.css. When you generate a document with the html5
backend, the asciidoctor.css stylesheet is embedded into the HTML output by default (when the safe mode is less than SECURE ).
You have the option of linking to the stylesheet instead of embedding it. This is the mandatory behavior when the safe mode is
SECURE. If your stylesheet is being linked when you expect it to be embedded, lower the safe mode ( safe is the recommend
value).
To have your document link to the stylesheet, set the linkcss attribute in the document’s header.
You can also set linkcss with the CLI.
$ asciidoctor -a linkcss mysample.adoc
Now, when you view the directory, you should see the file asciidoctor.css in addition to mysample.adoc and mysample.html. The
linkcss attribute automatically copies asciidoctor.css to the output directory. Additionally, you can inspect mysample.html in your
browser and see <link rel="stylesheet" href="./asciidoctor.css"> inside the <head> tags.
require 'asciidoctor'
Asciidoctor.convert_file 'mysample.adoc'
RUBY
html = Asciidoctor.convert_file 'mysample.adoc', to_file: false, header_footer: true
puts html
RUBY
= My First Experience with the Dangers of Documentation
:linkcss:
In my world, we don't have to worry about mutant, script-injecting warlocks.
No.
We have something far worse.
We're plagued by Wolpertingers.
== Origins
You may not be familiar with these https://en.wikipedia.org/wiki/Wolpertinger[ravenous beasts], but, trust me, they'll eat
ASCIIDOC
12/20/2018 Asciidoctor User Manual
https://asciidoctor.org/docs/user-manual/ 230/315
If you don’t want any styles applied to the HTML output of your document, unset the stylesheet attribute.
$ asciidoctor -a stylesheet! mysample.adoc
One of Asciidoctor’s strengths is the ease in which you can swap the default stylesheet for an alternative Asciidoctor theme or use
your own custom stylesheet.
63.4. Managing Images
Images are not embedded in the HTML output by default. If you have image references in your document, you’ll have to save the
image files in the same directory as your converted document.
As an alternative, you can embed the images directly into the document by setting the data-uri document attribute.
$ asciidoctor -a data-uri mysample.adoc
= My First Experience with the Dangers of Documentation
:imagesdir: myimages
:data-uri:
In my world, we don't have to worry about mutant, script-injecting warlocks.
No.
We have something far worse.
We're plagued by Wolpertingers.
== Origins
[.left.text-center]
image::wolpertinger.jpg[Wolpertinger]
You may not be familiar with these https://en.wikipedia.org/wiki/Wolpertinger[ravenous beasts], but, trust me, they'll eat
ASCIIDOC
12/20/2018 Asciidoctor User Manual
https://asciidoctor.org/docs/user-manual/ 231/315
If the target of one or more images in the document is a URI, you must also set the allow-uri-read attribute securely and run
Asciidoctor in SECURE mode or less.
$ asciidoctor -a data-uri -a allow-uri-read mysample.adoc
The same is true when converting the document to PDF using Asciidoctor PDF, even if the allow-uri-read attribute is not set
(since the behavior is implied).
63.5. CodeRay and Pygments Stylesheets
Asciidoctor will also embed the theme stylesheet for the CodeRay or Pygments syntax highlighter.
CodeRay
If the source-highlighter attribute is coderay and the coderay-css attribute is class , the CodeRay stylesheet is:
embedded by default
copied to the file asciidoctor-coderay.css inside the stylesdir folder within the output directory if linkcss is set
Pygments
If the source-highlighter attribute is pygments and the pygments-css attribute is class , the Pygments stylesheet is:
embedded by default
copied to the file asciidoctor-pygments.css inside the stylesdir folder within the output directory if linkcss is set
12/20/2018 Asciidoctor User Manual
https://asciidoctor.org/docs/user-manual/ 232/315
64. XHTML
To convert AsciiDoc to XHTML, set the backend to xhtml5 .
Produce XHTML using the built-in HTML converter
To produce XHTML instead of HTML when using converter templates, set the htmlsyntax attribute to xml in addition to the
backend option:
Produce XHTML using custom templates
Black Box Decoded: XHTML and htmlsyntax
XHTML output is a special mode of the built-in HTML5 converter. It is activated by prefixing the backend value with x (e.g.,
xhtml or xhtml5 ). This hint implicitly assigns the htmlsyntax attribute to the value xml , which normally has the value
html .
For all other converters, the htmlsyntax attribute is not set explicitly. If you want a converter template that’s written in
Slim or Haml to output XHTML instead of the default HTML, you simply need to set the htmlsyntax attribute to xml
explicitly. Asciidoctor will pass on this preference to the Slim or Haml template engine by setting the :format option to
:html5 .
asciidoctor -b xhtml5 document.adoc
CONSOLE
asciidoctor -T /path/to/templates -b slides -a htmlsyntax=xml document.adoc
CONSOLE
12/20/2018 Asciidoctor User Manual
https://asciidoctor.org/docs/user-manual/ 233/315
65. DocBook
Asciidoctor can produce DocBook 5.0 and 4.5 output. Since the AsciiDoc syntax was designed with DocBook output in mind, the
conversion is very good. There’s a corresponding DocBook element for each markup in the AsciiDoc syntax.
To convert the mysample.adoc document to DocBook 5.0 format, call the processor with the backend flag set to docbook .
$ asciidoctor -b docbook mysample.adoc
A new XML document, named mysample.xml , will now be present in the current directory.
$ ls
mysample.adoc mysample.html mysample.xml
Here’s a snippet of the XML generated by the DocBook converter.
XML generated from AsciiDoc
By default, the xmlns attribute is not added to the root element of the DocBook 4.5 document. To enable it,
assign an empty value to the xmlns attribute.
If you’re on Linux, you can view the DocBook file with Yelp (https://wiki.gnome.org/action/show/Apps/Yelp).
$ yelp mysample.xml
And of course, if you’re using the Asciidoctor Ruby API, you can generate a DocBook document directly from your application.
Generate DocBook output from the API
By default, the docbook converter produces DocBook 5.0 output that is compliant to the DocBook 5.0 specification.
A summary of the differences are as follows:
XSD declarations are used on the document root instead of a DTD
<?xml version="1.0" encoding="UTF-8"?>
<article xmlns="http://docbook.org/ns/docbook"
xmlns:xl="http://www.w3.org/1999/xlink" version="5.0" xml:lang="en">
<info>
<title>Hello, AsciiDoc!</title>
<date>2013-09-03</date>
<author>
<personname>
<firstname>Doc</firstname>
<surname>Writer</surname>
</personname>
<email>doc@example.com</email>
</author>
<authorinitials>DW</authorinitials>
</info>
<simpara>
An introduction to <link xl:href="http://asciidoc.org">AsciiDoc</link>.
</simpara>
<section xml:id="_first_section">
<title>First Section</title>
<itemizedlist>
<listitem>
<simpara>item 1</simpara>
</listitem>
<listitem>
<simpara>item 2</simpara>
</listitem>
</itemizedlist>
</section>
</article>
XML
Asciidoctor.convert_file 'mysample.adoc', backend: 'docbook'
RUBY
12/20/2018 Asciidoctor User Manual
https://asciidoctor.org/docs/user-manual/ 234/315
<info> elements for document info instead of <articleinfo> and <bookinfo>
elements that hold the author’s name are wrapped in a <personname> element
the id for an element is defined using an xml:id attribute
<link> is used for links instead of <ulink>
the URL for a link is defined using the xl:href attribute
Refer to What’s new in DocBook v5.0? (https://tdg.docbook.org/tdg/5.0/ch01.html#introduction-whats-new) for more details about how
DocBook 5.0 differs from DocBook 4.5.
If you need to output DocBook 4.5, set the backend to docbook45 .
$ asciidoctor -b docbook45 mysample.adoc
12/20/2018 Asciidoctor User Manual
https://asciidoctor.org/docs/user-manual/ 235/315
66. Man Pages
One of the more specialized uses of AsciiDoc is to serve as a shorthand for generating man pages (short for manual pages) for
Unix and Unix-like operating systems.
A man page is coded in the roff typesetting language. By adhering to a specific structure in the man page file, the man command
can parse the content and present a formatted document in a textual (command line) pager. Manual pages provide a unified help
catalog for all commands in the system. For a full description, see the roff man page (http://man7.org/linux/man-pages/man7/roff.7.html)
(or type man roff or man 7 man ).
Asciidoctor can produce roff-formatted man pages if the structure of the AsciiDoc document adheres to the manpage doctype
structure (described later in this section).
To produce a roff-formatted man page from an AsciiDoc file that declares the manpage doctype, run:
$ asciidoctor -b manpage source.adoc
Note that the man page converter sets the output file name to progname.1 , where progname is the name of the command and 1
is the volume number, as defined by the doctitle of the source document.
When converting to the man page format, Asciidoctor uppercases the titles of all level-0 and level-1 sections. This saves you from
having to type section titles in all uppercase. It also makes the document portable to other output formats since this style is only
needed in the man page output to align with conventions.
If you’re use Ruby 2.4 or better, Asciidoctor will uppercase any letter in the title that is recognized by the
Unicode specification as having an uppercase equivalent (which includes non-Latin letters). Prior to Ruby 2.4,
Ruby could only uppercase Latin letters.
Asciidoctor can also produce HTML and PDF versions similar to the man output for viewing in other contexts. To see the man
page in HTML instead, run:
$ asciidoctor source.adoc
Here is an example man page composed in AsciiDoc for the eve command:
12/20/2018 Asciidoctor User Manual
https://asciidoctor.org/docs/user-manual/ 236/315
The manpage doctype has the following required parts:
Document Header
A man page document header is mandatory. The title line contains the man page name followed immediately by the manual
section number in round brackets. The title name should not contain white space. The manual section number is a single digit
optionally followed by a single character.
The NAME Section
The first man page section is mandatory, must be titled “NAME” and must contain a single paragraph (usually a single line)
consisting of a list of one or more comma separated command name(s) separated from the command purpose by a dash
character. The dash must have at least one white space character on either side.
The SYNOPSIS Section
The second man page section is mandatory and must be titled “SYNOPSIS”.
Subsequent sections are optional, but typical sections include “SEE ALSO”, “BUGS REPORTS”, “AUTHORS” and “COPYRIGHT”.
There are several built-in document attributes that affect only man pages. If used, they must be set in the document header.
Built-in document attributes specific to the manpage doctype
Attribute name Description Value (as parsed from example above)
mantitle Alternative way to set the man page name. ASCIIDOCTOR(1)
manvolnum Manual section number. 1
manname Alternative way to set the command name. asciidoctor
manpurpose Alternative way to set the command purpose. converts AsciiDoc source files
= eve(1)
Andrew Stanton
v1.0.0
:doctype: manpage
:manmanual: EVE
:mansource: EVE
:man-linkstyle: pass:[blue R < >]
== Name
eve - analyzes an image to determine if it's a picture of a life form
== Synopsis
*eve* [_OPTION_]... _FILE_...
== Options
*-o, --out-file*=_OUT_FILE_::
Write result to file _OUT_FILE_.
*-c, --capture*::
Capture specimen if it's a picture of a life form.
== Exit status
*0*::
Success.
Image is a picture of a life form.
*1*::
Failure.
Image is not a picture of a life form.
== Resources
*Project web site:* http://eve.example.org
== Copying
Copyright (C) 2008 {author}. +
Free use of this software is granted under the terms of the MIT License.
ASCIIDOC
12/20/2018 Asciidoctor User Manual
https://asciidoctor.org/docs/user-manual/ 237/315
Attribute name Description Value (as parsed from example above)
man-linkstyle Style the links in the manpage output. A valid
link format sequence.
blue R <>
mansource The source to which the man page pertains.
When producing DocBook, it becomes a
DocBook refmiscinfo
(https://tdg.docbook.org/tdg/5.0/refmiscinfo.html)
attribute and appears in the footer.
Asciidoctor
manversion The version of the man page. Defaults to
revnumber if not specified. When producing
DocBook, it becomes a DocBook refmiscinfo
(https://tdg.docbook.org/tdg/5.0/refmiscinfo.html)
attribute and appears in the footer. Not used by
Asciidoctor.
1.5.4
manmanual Manual name. When producing DocBook, it
becomes a DocBook refmiscinfo
(https://tdg.docbook.org/tdg/5.0/refmiscinfo.html)
attribute and appears in the footer.
Asciidoctor Manual
Refer to the AsciiDoc source of the Asciidoctor man page
(https://raw.githubusercontent.com/asciidoctor/asciidoctor/master/man/asciidoctor.adoc) to see a complete example. The man page for
Asciidoctor is produced using the built-in man page converter in Asciidoctor. The man pages for git are also produced from
AsciiDoc documents, so you can use those as another example to follow.
12/20/2018 Asciidoctor User Manual
https://asciidoctor.org/docs/user-manual/ 238/315
67. PDFs
Conversion from AsciiDoc to PDF is made possible by a number of tools.
Asciidoctor PDF (https://github.com/asciidoctor/asciidoctor-pdf)
A native PDF converter for Asciidoctor (converts directly from AsciiDoc to PDF using Prawn).
Instructions for installing and using Asciidoctor PDF are documented in the project’s README
(https://github.com/asciidoctor/asciidoctor-pdf/blob/master/README.adoc). The tool provides built-in theming via a YAML configuration
file, which is documented in the theming guide
(http://gist.asciidoctor.org/?github-asciidoctor%2Fasciidoctor-pdf%2F%2Fdocs%2Ftheming-guide.adoc).
Asciidoctor PDF is the preferred tool for converting to PDF and is fully supported by the Asciidoctor
community.
a2x
A DocBook toolchain frontend provided by that AsciiDoc Python project.
To use this tool, you should first convert to DocBook using Asciidoctor, then convert the DocBook to PDF using a2x. a2x accepts
a DocBook file as input and can convert it to a PDF using either Apache FOP or dblatex. Instructions for using a2x are
documented in the project’s man page (http://asciidoc.org/a2x.1.html).
asciidoctor-fopub (https://github.com/asciidoctor/asciidoctor-fopub)
A DocBook toolchain frontend similar to a2x, but which only requires Java to be installed on your machine.
Instructions for using asciidoctor-fopub are documented in the project’s README
(https://github.com/asciidoctor/asciidoctor-fopub/blob/master/README.adoc). To alter the look and feel of the PDF, it’s necessary to pass
XSL parameters or modify the XSLT. More information about customization can be found in DocBook XSL: The Complete Guide
(http://www.sagehill.net/docbookxsl/).
12/20/2018 Asciidoctor User Manual
https://asciidoctor.org/docs/user-manual/ 239/315
68. Preview Your Content
68.1. Guard/Live Viewer
Guard
AsciiDoc is a plugin for Guard (https://github.com/guard/guard) that converts watched AsciiDoc files to the specified output format
whenever they change using Asciidoctor.
Instructions for using the Guard/Live viewer are documented in the project’s README
(https://github.com/asciidoctor/guard-asciidoc/blob/master/README.asciidoc).
12/20/2018 Asciidoctor User Manual
https://asciidoctor.org/docs/user-manual/ 240/315
69. CLI Inputs and Outputs
So far, you’ve seen how to pass a single input file to the CLI for it to convert. You can also convert multiple files at once, read
content from STDIN, write content to STDOUT, or write content to a different output file or directory. This section explains the
various input and output options of the CLI.
69.1. Process Multiple Source Files from the CLI
You can pass multiple source files or a filename pattern to the Asciidoctor CLI and it will convert each file given in turn.
Let’s assume there exist two AsciiDoc files in the current directory, a.adoc and b.adoc. You can pass both files to Asciidoctor using
a single command, as follows:
$ asciidoctor a.adoc b.adoc
Asciidoctor will convert both files, transforming a.adoc to a.html and b.adoc to b.html.
To save some typing, you can use the glob operator ( *) to match all AsciiDoc files in the current directory using a single
argument:
$ asciidoctor *.adoc
Your shell will automatically expand the pattern and interpret the command exactly as you had typed it above:
$ asciidoctor a.adoc b.adoc
You can pass all AsciiDoc files inside direct subfolders using the glob operator ( *) in place of the directory name:
$ asciidoctor */*.adoc
To match all files in the current directory and direct subfolders, combine both glob patterns:
$ asciidoctor *.adoc */*.adoc
Since the globs in this command rely on shell expansion, the command is not portable across platforms. To make it portable, you
can allow the Asciidoctor CLI to expand the globs. To do so, instruct the shell to not expand the glob by quoting the pattern, as
shown here:
$ asciidoctor '*.adoc' '*/*.adoc'
This time, the arguments *.adoc and */*.adoc are passed directly to Asciidoctor instead of being expanded. Asciidoctor
handles the glob matching in a manner that is portable across platforms.
But it gets better. The glob handling in Asciidoctor (which matches the rules of file globbing in Ruby) is likely more powerful than
what your shell offers. For example, you can match AsciiDoc files in the current folder and in folders of any depth using the
double glob operator ( ** ).
$ asciidoctor '**/*.adoc'
Most shells do not honor this double glob pattern.
In conclusion, when specifying a glob pattern, we always recommend enclosing the argument in quotes.
If you process multiple nested AsciiDoc files at once and are also applying a custom stylesheet to them, you’ll
need to manage the stylesheet’s location.
69.2. Specifying an Output File
12/20/2018 Asciidoctor User Manual
https://asciidoctor.org/docs/user-manual/ 241/315
By default, the CLI writes the converted output to the same directory as the input file and with the same name as the input file,
except with a file extension that matches the output format (e.g., replacing .adoc with .html). You can override this default and
have the CLI write to a file and directory of your choice.
There are several circumstances when you’ll want to specify a different output file:
You want to write the output file to a different name, perhaps to append a qualifier such as a version string.
You want to write the output file to a different directory.
You are piping content to the CLI, but want to write the output to a file (in this case, an output file is required).
By specifying an output file, you implicitly overwrite the output directory as well. The output file will be
resolved relative to the current working directory, not the directory of the input file.
To specify the output file, you’ll use the -o option. For example, let’s say we want to convert mydoc.adoc and write the output to a
filename that includes the current date. You’d use:
$ asciidoctor -o mydoc-$(date +%Y-%m-%d).html mydoc.adoc
We could write it to another folder as well by prefixing the output file with a folder name:
$ asciidoctor -o build/mydoc-$(date +%Y-%m-%d).html mydoc.adoc
If you only want to specify the output directory, but let the filename be defaulted, use the -D option:
$ asciidoctor -D build mydoc.adoc
The -D option can also be used when processing multiple input files:
$ asciidoctor -D build *.adoc
If you are piping content to the CLI, the default is to write the output to STDOUT. If you want to write the output to a file in this
case, you have to specify one:
$ cat mydoc.adoc | asciidoctor -o build/mydoc-$(date +%Y-%m-%d).html -
You’ll learn more about piping content through the CLI in the next section.
69.3. Piping Content Through the CLI
Using the - flag, you can pipe content to the asciidoctor command. This flag tells Asciidoctor read the source from standard
input (STDIN). For example:
$ echo 'content' | asciidoctor -
Any variation of STDIN will work.
This command is effectively the same as:
$ echo 'content' | asciidoctor -o - -
When reading source from STDIN, Asciidoctor doesn’t have a reference to an input file. Therefore, it sends the converted text to
standard output (STDOUT) by default.
If, instead, you want to write the full document to an output file, you specify it using the -o flag. For example, the following
command writes a standalone HTML document to output.html instead of STDOUT:
$ echo "content" | asciidoctor -o output.html -
12/20/2018 Asciidoctor User Manual
https://asciidoctor.org/docs/user-manual/ 242/315
When you pipe content to the asciidoctor command, it no longer has a concept of where the document is located. Therefore,
relative references such as includes may not work as expected. To resolve this problem, you should specify an absolute base
directory using the -B option:
$ echo "content" | asciidoctor -B /path/to/basedir -o output.html -
Alternately, you can set an artificial document directory by passing an absolute path to the docdir attribute:
$ echo "content" | asciidoctor -a docdir=/path/to/docdir -o output.html -
Try both approaches to determine which one suits your needs better.
When piping source from STDIN to STDOUT through the asciidoctor command, you often just want the converted body (i.e.,
embeddable HTML). To produce that variant, add the -s flag:
$ echo 'content' | asciidoctor -s -
Or perhaps you want to include the doctitle as well:
$ echo -e '= Document Title\n\ncontent' | asciidoctor -s -a showtitle -
12/20/2018 Asciidoctor User Manual
https://asciidoctor.org/docs/user-manual/ 243/315
70. Running Asciidoctor Securely
Asciidoctor provides security levels that control the read and write access of attributes, the include directive, macros, and
scripts while a document is processing. Each level includes the restrictions enabled in the prior security level.
UNSAFE A safe mode level that disables any security features enforced by Asciidoctor. Ruby is still subject to its own
restrictions.
This is the default safe mode for the CLI. Its integer value is 0.
SAFE This safe mode level prevents access to files which reside outside of the parent directory of the source file. The
include directive is enabled, but paths to include files must be within the parent directory. This mode allows
assets (such as the stylesheet) to be embedded in the document.
Its integer value is 1.
SERVER A safe mode level that disallows the document from setting attributes that would affect conversion of the document.
This level trims docfile to its relative path and prevents the document from:
setting source-highlighter , doctype , docinfo and backend
seeing docdir
It allows icons and linkcss .
Its integer value is 10 .
SECURE A safe mode level that disallows the document from attempting to read files from the file system and including their
contents into the document. Additionally, it:
disables icons
disables the include directive
data can not be retrieved from URIs
prevents access to stylesheets and JavaScripts
sets the backend to html5
disables docinfo files
disables data-uri
disables docdir and docfile
disables source highlighting
Asciidoctor extensions may still embed content into the document depending whether they honor the safe mode
setting.
This is the default safe mode for the API. Its integer value is 20 .
You can set Asciidoctor’s safe mode level using the CLI or API.
70.1. Set the Safe Mode in the CLI
When Asciidoctor is invoked via the CLI, the safe mode is set to UNSAFE by default. You can change the safe level by executing one
of the following commands in the CLI.
-S , --safe-mode=SAFE_MODE
Sets the safe mode level of the document according to the assigned level ( UNSAFE , SAFE , SERVER , SECURE ).
--safe , asciidoctor-safe
Sets the safe mode level to SAFE . Provided for compatibility with the python AsciiDoc safe command.
70.2. Set the Safe Mode in the API
The default safe level in the API is SECURE .
12/20/2018 Asciidoctor User Manual
https://asciidoctor.org/docs/user-manual/ 244/315
In the API, you can set the safe mode using a string, symbol or integer value. The value must be set in the document constructor
using the :safe option.
result = Asciidoctor.convert_file('master.adoc', :safe => 'server')
or
result = Asciidoctor.convert_file('master.adoc', :safe => :server)
or
result = Asciidoctor.convert_file('master.adoc', :safe => 10)
70.3. Set Attributes Based on the Safe Mode
Asciidoctor provides access to the current safe mode through built-in attributes. You can use these attributes to enable or disable
content based on the current safe mode of the processor.
The safe mode can be referenced by one of the following attributes:
The value of the safe-mode-name attribute (e.g., unsafe, safe, etc.)
The value of the safe-mode-level attribute (e.g., 0, 10, etc.)
The presense of the safe-mode-<name> attribute, where <name> is the safe mode name.
The attributes in the next example define replacement text for features that are disabled in high security environments:
This feature is particularly handy for displaying content on GitHub, where the safe mode is set to its most restrictive setting,
secure.
ifdef::safe-mode-secure[]
Link to chapters instead of including them.
endif::safe-mode-secure[]
ASCIIDOC
12/20/2018 Asciidoctor User Manual
https://asciidoctor.org/docs/user-manual/ 245/315
Customizing Your Output
Asciidoctor provides a default stylesheet and built-in converters so you can quickly process and convert your document, but it
also lets you use custom stylesheets and converters. The Asciidoctor project includes alternative stylesheet themes from the
stylesheet factory and specialized backends. You can also create your own themes and backends.
12/20/2018 Asciidoctor User Manual
https://asciidoctor.org/docs/user-manual/ 246/315
71. Applying a Theme
A custom stylesheet can be stored in the same directory as your document or in a separate directory. Like the default stylesheet,
you can have the output document link to your custom stylesheet or embed it.
If the stylesheet is in the same directory as your document, you can apply it when converting your document to HTML from the
CLI.
$ asciidoctor -a stylesheet=mystyles.css mysample.adoc
1. Save your custom stylesheet in the same directory as mysample.adoc
2. Call the asciidoctor processor
3. Set -a ( --attribute ) and stylesheet
4. Assign the stylesheet file’s name to the stylesheet attribute
5. Enter your document file’s name.
Alternatively, let’s set the stylesheet attribute in the header of mysample.adoc .
When your document and the stylesheet are stored in different directories, you need to tell Asciidoctor where to look for the
stylesheet in relation to your document. Asciidoctor uses the relative or absolute path you assign to the stylesdir attribute to
find the stylesheet. Let’s move mystyles.css into mydocuments/mystylesheets/ . Our AsciiDoc document, mysample.adoc , is
saved in the mydocuments/ directory.
= My First Experience with the Dangers of Documentation
:stylesheet: mystyles.css
In my world, we don't have to worry about mutant, script-injecting warlocks.
No.
We have something far worse.
We're plagued by Wolpertingers.
== Origins
You may not be familiar with these https://en.wikipedia.org/wiki/Wolpertinger[ravenous beasts], but, trust me, they'll eat
12/20/2018 Asciidoctor User Manual
https://asciidoctor.org/docs/user-manual/ 247/315
After processing mysample.adoc , its HTML output ( mysample.html ), which includes the embedded mystyles.css stylesheet,
is created in the mydocuments/ directory.
You can also set stylesdir in the CLI.
$ asciidoctor -a stylesdir=mystylesheets/ -a stylesheet=mystyles.css mysample.adoc
If you don’t want to embed the mystyles.css stylesheet into your HTML output, make sure to set linkcss .
After your document is converted, notice that a copy of mystyles.css was not created in the mydocuments/ directory. Unlike
when you link to the default Asciidoctor stylesheet, any custom stylesheets you link to are not copied to the directory where your
output is saved.
Stylesheets and processing multiple nested documents
When you are running Asciidoctor once across a nested set of documents, it’s currently not possible to specify a single
relative path for the stylesdir attribute that would work for all of the documents. This is because the relative depth of the
stylesheet’s location differs for the documents in the subdirectories. One way to solve this problem is to maintain the path to
stylesdir in each document.
Let’s say you have three AsciiDoc documents saved in the following directory structure:
= My First Experience with the Dangers of Documentation
:stylesdir: mystylesheets/
:stylesheet: mystyles.css
In my world, we don't have to worry about mutant, script-injecting warlocks.
No.
We have something far worse.
We're plagued by Wolpertingers.
== Origins
You may not be familiar with these https://en.wikipedia.org/wiki/Wolpertinger[ravenous beasts], but, trust me, they'll eat
= My First Experience with the Dangers of Documentation
:stylesdir: mystylesheets/
:stylesheet: mystyles.css
:linkcss:
In my world, we don't have to worry about mutant, script-injecting warlocks.
No.
We have something far worse.
We're plagued by Wolpertingers.
== Origins
You may not be familiar with these https://en.wikipedia.org/wiki/Wolpertinger[ravenous beasts], but, trust me, they'll eat
12/20/2018 Asciidoctor User Manual
https://asciidoctor.org/docs/user-manual/ 248/315
For a.adoc and b.adoc , set stylesdir to:
For c.adoc , set stylesdir to:
If you’re serving your documents from a webserver, you can solve this problem by providing an absolute path to the
stylesheet.
/mydocuments
a.adoc
b.adoc
/mynesteddocuments
c.adoc
/mystylesheets
:stylesdir: mystylesheets
:stylesdir: ../mystylesheets
12/20/2018 Asciidoctor User Manual
https://asciidoctor.org/docs/user-manual/ 249/315
72. Stylesheet Factory
The Asciidoctor stylesheet factory (https://github.com/asciidoctor/asciidoctor-stylesheet-factory) is where themes are developed for styling
your documents. Specifically, these stylesheets can be used to quickly customize the look and feel of HTML 5 documents
generated by Asciidoctor.
To view the Asciidoctor themes in action, visit the theme showcase (http://themes.asciidoctor.org/preview/).
The Asciidoctor stylesheet factory is only compatible with Asciidoctor 0.1.2 and greater.
72.1. Setting up the Factory
The stylesheets in the Asciidoctor stylesheet factory are built using Compass (http://compass-style.org), a CSS authoring framework
that uses Sass (http://sass-lang.com) to generate CSS files. The styles and components are generated by Foundation 4
(https://foundation.zurb.com), an awesome and flexible CSS component framework that ensures your stylesheet is cross-browser and
mobile friendly.
72.1.1. Install the Gems
In order to build the stylesheets, you must download the Asciidoctor stylesheet factory repository and install the Compass and
Foundation gems.
1. Download or clone the Asciidoctor stylesheet factory repository (https://github.com/asciidoctor/asciidoctor-stylesheet-factory).
It does not matter where you save the project on your system.
2. Make sure you have Ruby and RubyGems (https://www.ruby-lang.org/en/downloads) installed, and, ideally, Bundler
(https://rubygems.org/gems/bundler).
3. Run Bundler to install the Compass and Foundation gems.
$ bundle install
The previous bundle command is equivalent to the following two commands:
$ gem install compass --version 0.12.2
$ gem install zurb-foundation --version 4.3.2
You don’t need to execute these gem install commands if you use Bundler.
Once you have the gems installed, you can build the stylesheets.
72.1.2. Build the Stylesheets
To build the stylesheets:
1. Navigate to the Asciidoctor stylesheet factory directory on your system.
2. Run Compass’s compile command.
$ compass compile
The stylesheets are compiled from the Sass source files in the sass/ folder and written to the stylesheets/ folder. You can reference
the stylesheets in stylesheets/ from your HTML file.
72.2. Creating a Theme
You can create your own themes to apply to your documents.
Themes go in the sass/ folder. To create a new theme, let’s call it hipster , start by creating two new files:
sass/hipster.scss
Imports the theme settings, which includes default variables and resets
12/20/2018 Asciidoctor User Manual
https://asciidoctor.org/docs/user-manual/ 250/315
Imports the AsciiDoc components
Defines any explicit customization
sass/settings/_hipster.scss
Sets variables that customize Foundation 4 and the AsciiDoc CSS components
Here’s a minimal version of sass/hipster.scss:
You don’t have to include the underscore prefix when importing files.
The awesome-icons component is only applicable to HTML generated by Asciidoctor > 0.1.2 with the icons
attribute set to font .
You can add any explicit customization below the import lines.
The variables you can set in sass/settings/_hipster.scss are a combination of the Foundation 4 built-in global settings
(https://github.com/asciidoctor/asciidoctor-stylesheet-factory/blob/master/sass/settings/_settings.scss.dist) and global settings and imports for
the AsciiDoc components (https://github.com/asciidoctor/asciidoctor-stylesheet-factory/blob/master/sass/settings/_defaults.scss).
Once you’ve created your custom theme, it’s time to apply it to your document.
72.3. Applying a Stylesheet
Let’s practice applying a stylesheet to a simple AsciiDoc file.
1. Create an AsciiDoc file like the one below.
2. Save the file as mysample.adoc.
Next, you’ll use the Asciidoctor processor to generate HTML and apply a stylesheet to it from the stylesheets/ directory.
72.4. Generate an HTML Document
Now it’s time to pick the stylesheet you want to apply to your content when it is rendered. In your file browser, navigate to the
stylesheets/ directory. Or, using a console, change to the stylesheets/ directory and list the available stylesheets using the ls
command.
$ ls
Console output of ls command
asciidoctor.css foundation-lime.css iconic.css riak.css
colony.css foundation-potion.css maker.css rubygems.css
foundation.css golo.css readthedocs.css
Let’s apply the colony.css stylesheet to the sample document.
1. Navigate to the directory where you saved mysample.adoc.
@import "settings/hipster";
@import "components/asciidoc";
@import "components/awesome-icons";
SCSS
= Introduction to AsciiDoc
Doc Writer <doc@example.com>
A preface about http://asciidoc.org[AsciiDoc].
== First Section
* item 1
* item 2
[source,ruby]
puts "Hello, World!"
ASCIIDOC
12/20/2018 Asciidoctor User Manual
https://asciidoctor.org/docs/user-manual/ 251/315
2. Call the asciidoctor processor.
3. Specify the stylesheet you want applied with the stylesheet attribute.
4. Tell the processor where the specified stylesheet is located with the stylesdir attribute.
$ asciidoctor -a stylesheet=colony.css -a stylesdir=../stylesheets mysample.adoc
Open a browser, navigate to mysample.html and checkout the result! If you inspect the mysample.html document, you should see
that the stylesheet is embedded in the converted document.
Stylesheet images
The Golo, Maker, and Riak themes include image assets. To apply these themes to your document correctly, the applicable
images must be copied into the same directory as the generated output.
For example, to apply the maker.css stylesheet to mysample.adoc:
1. Copy body-bh.png from the images/maker/ directory into the output directory.
2. Call the stylesheet and styledir attributes.
$ asciidoctor -a stylesheet=maker.css -a stylesdir=../stylesheets mysample.adoc
Navigate to mysample.html in your browser. The body-bh.png image should add a graph paper-like background to your
generated output.
72.5. External Preview
You may want to preview sample HTML files on another computer or device. To do that, you need to serve them through a web
server. You can quickly serve HTML files in the root directory of the project using the following command:
Using Python
$ python -m SimpleHTTPServer 4242
or
Using Ruby >= 1.9.3
$ ruby -run -e httpd . -p 4242
12/20/2018 Asciidoctor User Manual
https://asciidoctor.org/docs/user-manual/ 252/315
73. Slide Decks
In addition to generating normal documents from AsciiDoc (e.g., a book or article), you can also use AsciiDoc to create HTML-
based slide decks. The converters for creating HTML-based slides add some additional structure rules to the document for
defining slides. However, nothing in this structure restricts you from still being able to publish the content as a normal document
too.
The conversion from AsciiDoc to an HTML-based slide deck is handled by one of the following converters from the Asciidoctor
ecosystem:
Asciidoctor Reveal.js (https://github.com/asciidoctor/asciidoctor-reveal.js) — Converts an AsciiDoc document into a Reveal.js
presentation
Asciidoctor Bespoke (https://github.com/asciidoctor/asciidoctor-bespoke) — Converts an AsciiDoc document into a Bespoke
presentation
There’s also a converter for making deck.js slide decks, but we discourage using it as deck.js itself is very outdated.
12/20/2018 Asciidoctor User Manual
https://asciidoctor.org/docs/user-manual/ 253/315
74. Custom Backends
74.1. Storing Multiple Templates
Custom templates can be stored in multiple directories. That means you can build on an existing backend by copying only the
templates you want to modify. Then, just pass both the directory holding the original templates and the directory containing your
customized templates when you invoke Asciidoctor.
In the CLI, multiple template directories are specified by using the -T option multiple times.
$ asciidoctor -T /path/to/original/templates -T /path/to/modified/templates mysample.adoc
In the API, multiple template directories are specified by passing an array to the template_dirs option:
Asciidoctor.convert_file 'mysample.adoc', safe: :safe
template_dirs: %w(/path/to/original/templates /path/to/modified/templates)
RUBY
12/20/2018 Asciidoctor User Manual
https://asciidoctor.org/docs/user-manual/ 254/315
75. Using Asciidoctor with Other Languages
The built-in labels, messages, and syntax keywords in Asciidoctor are English by default. However, Asciidoctor is not restricted to
working with English-only content. Asciidoctor can process the full range of the UTF-8 character set. That means you can write
your document in any language, save the file with UTF-8 encoding, and expect Asciidoctor to convert the text properly.
Furthermore, you can customize the built-in labels (e.g., “Appendix”) to match the language in which you are writing.
There are some caveats to know about:
Currently, the official HTML and PDF converters only fully support left-to-right (and top-to-bottom) reading. Support for right-
to-left (RTL) is being worked on. See issue #1601 (https://github.com/asciidoctor/asciidoctor/issues/1601) for details. In the interim, you
can leverage the DocBook toolchain to get right-to-left support.
Attributes that store dates and times (e.g., docdatetime ) are always formatted like 2019-01-04 19:26:06 GMT+0000 .
Message (aka logging) strings are always in English.
Asciidoctor does not support the language conf files used by AsciiDoc Python. However, Asciidoctor does provide a translation
file (https://github.com/asciidoctor/asciidoctor/blob/master/data/locale/attributes.adoc) that can be used for a similar purpose.
75.1. Translating built-in labels
When converting to DocBook, you can rely on the DocBook toolchain to translate (most) built-in labels. To activate this feature,
simply set the lang attribute to a valid country code (which defaults to en for English). For example:
The list of supported languages, as well as additional language considerations for DocBook, are described in DocBook XSL: The
Complete Guide (http://www.sagehill.net/docbookxsl/Localizations.html).
The lang attribute does not enable automatic translation of built-in labels when converting directly to HTML or PDF. It’s merely
a hint to configure the DocBook toolchain. If you’re not using the DocBook toolchain for publishing, you must translate each built-
in label yourself. One way is to set the following attributes in the document header or by passing the attributes via the API or CLI:
Attributes that control built-in labels
Attribute name Used for Default
appendix-caption Appendix titles. Appendix
caution-caption CAUTION admonitions (when icons are not in
use).
Caution
chapter-label Prefix added to chapter titles (i.e., level-1 section
titles when doctype is book). (pdf converter only)
Chapter
example-caption Example titles. Example
figure-caption Automatically prefixed to figure titles. Figure
important-caption IMPORTANT admonitions (when icons are not in
use).
Important
last-update-label Label for when the document was last updated. Last updated
listing-caption The label for listing blocks. By default, listing
blocks do not have captions. If you specify
listing-caption, then you also turn on
captions for listing blocks.
not set
manname-title Label for the program name section in the man
page.
NAME
note-caption NOTE admonitions (when icons are not in use). Note
$ asciidoctor -a lang=es -b docbook article.adoc
12/20/2018 Asciidoctor User Manual
https://asciidoctor.org/docs/user-manual/ 255/315
Attribute name Used for Default
preface-title Title text used for the anonymous preface (when
the doctype is book).
not set
table-caption Automatically prefixed to table titles. Table
tip-caption TIP admonitions (when icons are not in use). Tip
toc-title Title of the table of contents. Table of Contents
untitled-label The document title, for documents that have
only body content.
Untitled
version-label The label preceding the revnumber in the
document’s byline.
Version
warning-caption WARNING admonitions (when icons are not in
use).
Warning
If you plan to support multiple languages, you’ll want to define the attributes for each language inside a conditional preprocessor
directive. For example:
Of course, you’re probably hoping this has already been done for you. Indeed, it has!
You can find an AsciiDoc file (https://github.com/asciidoctor/asciidoctor/blob/master/data/locale/attributes.adoc) in the Asciidoctor repository
that provides translations of these attributes for most major languages. The translations are defined using AsciiDoc attribute
entries inside conditional preprocessor blocks, just as suggested above.
To use this file to translate the built-in labels according the the value of the lang attribute (just like the DocBook toolchain does),
follow these steps:
1. Download the AsciiDoc file attributes.adoc (https://raw.githubusercontent.com/asciidoctor/asciidoctor/master/data/locale/attributes.adoc)
from the Asciidoctor repository.
2. Put the file in the folder locale relative to your document.
3. Add the following line to the header of your AsciiDoc document:
4. Set the language using the lang attribute. This attribute must be set before the include directive gets processed. For example:
-a lang=es
The built-in labels will now be translated automatically based on the value of the lang attribute.
There’s an ongoing discussion about how to make language support even simpler (issue #1129
(https://github.com/asciidoctor/asciidoctor/issues/1129)). Input is welcome.
75.2. Translation
Asciidoctor (or DocBook) currently does not support translation of content out of the box. There’s a proposal to integrate gettext
(discussion (http://discuss.asciidoctor.org/Professional-providers-translating-Asciidoc-tt2692.html#none)), but suggestions are welcome.
ifeval::["{lang}" == "de"]
:caution-caption: Achtung
...
endif::[]
ASCIIDOC
include::locale/attributes.adoc[]
ASCIIDOC
12/20/2018 Asciidoctor User Manual
https://asciidoctor.org/docs/user-manual/ 257/315
76. Static Website Generators
76.1. Front Matter Added for Static Site Generators
Many static site generators (i.e., Jekyll, Middleman, Awestruct) rely on "front matter" added to the top of the document to
determine how to convert the content. Front matter typically starts on the first line of a file and is bounded by block delimiters
(e.g., --- ).
Here’s an example of a document that contains front matter:
1Front matter delimiters
2Front matter data
The static site generator removes these lines before passing the document to the AsciiDoc processor to be converted. Outside of
the tool, however, these extra lines can throw off the processor.
If the skip-front-matter attribute is set via the CLI or API (e.g., -a skip-front-matter ), Asciidoctor (as of 0.1.4) will
recognize the front matter and consume it before parsing the document. Asciidoctor stores the content it removes in the front-
matter attribute to make it available for integrations. Asciidoctor also removes front matter when reading include files.
Awestruct can read front matter directly from AsciiDoc attributes defined in the document header, thus
eliminating the need for this feature.
76.1.1. Conguring Attributes for Awestruct
Awestruct defines a set of default attributes that it passes to the API in its /default-site.yml file. One of the attributes in that
configuration is imagesdir . The value there is set to /images. That means the value in your document is skipped due to the
precedence rules.
Fortunately, there is one additional place you can override the attribute. This gives you the opportunity to set your own default
and to flip the precedence order so that the document wins out. If an attribute value that is passed to the API ends with an @
symbol, it makes that assignment have a lower precedence than an assignment in the document.
You can define attributes you want to pass to the API in the _config/site.yml file. Here’s an example entry for Asciidoctor:
The second-level keys (safe and attributes, in this case) must have colons on both sides of the key name. The
rest of the keys only have a colon after the key.
With this configuration added, you should observe that the imagesdir attribute in your document is now respected.
---
layout: default
---
= Document Title
content
ASCIIDOC
1
2
1
asciidoctor:
:safe: safe
:attributes:
imagesdir: /assets/images@
icons: font
...
YAML
12/20/2018 Asciidoctor User Manual
https://asciidoctor.org/docs/user-manual/ 258/315
Using Asciidoctor’s API
In addition to the command line interface, Asciidoctor provides a Ruby API. The API is intended for integration with other
software projects and is suitable for server-side applications, such as Rails, Sinatra and GitHub.
Asciidoctor also has a Java API that mirrors the Ruby API. The Java API calls through to the Ruby API using an embedded JRuby
runtime. See the AsciidoctorJ project for more information.
12/20/2018 Asciidoctor User Manual
https://asciidoctor.org/docs/user-manual/ 259/315
77. Require the Library
To use Asciidoctor in your application, you first need to require the gem:
This statement makes all of the public APIs in Asciidoctor (https://www.rubydoc.info/gems/asciidoctor/Asciidoctor) available to your
script or application. You are now ready to start processing AsciiDoc documents.
The main entry points in the Asciidoctor API are the static methods to load or convert AsciiDoc documents, which we’ll cover the
next two chapters.
require 'asciidoctor'
RUBY
12/20/2018 Asciidoctor User Manual
https://asciidoctor.org/docs/user-manual/ 260/315
78. Load and Convert Files
To parse a file into an Asciidoctor::Document object:
You can get information about the document:
More than likely, you will want to convert the document. To convert a file containing AsciiDoc markup to HTML 5, use:
The command will output to the file mysample.html in the same directory.
You can convert the file to DocBook 5.0 by setting the :backend option to 'docbook' :
The command will output to the file mysample.xml in the same directory. If you’re on Linux, you can view the file using Yelp
(https://wiki.gnome.org/action/show/Apps/Yelp).
doc = Asciidoctor.load_file 'mysample.adoc'
RUBY
puts doc.doctitle
puts doc.attributes
RUBY
Asciidoctor.convert_file 'mysample.adoc'
RUBY
Asciidoctor.convert_file 'mysample.adoc', backend: 'docbook'
RUBY
12/20/2018 Asciidoctor User Manual
https://asciidoctor.org/docs/user-manual/ 261/315
79. Load and Convert Strings
To parse an AsciiDoc-formatted string into a document object model, use:
To convert the AsciiDoc-formatted string instead, use:
When converting a string, Asciidoctor does not output a standalone document by default. Instead, it generates embeddable
output. Let’s learn why that is and how to control it.
79.1. Embeddable output
When you pass a string to Asciidoctor.convert to convert it to a backend format, such as HTML, this method only returns the
converted content for those blocks. It does not include the shell around that content (i.e., the header and footer) that is needed to
make a standalone document. Instead, it makes an embeddable document. This default was chosen to make Asciidoctor consistent
with other lightweight markup processors like Markdown.
Here’s what’s included in an embeddable document:
The document title, but only if the showtitle attribute is set (no attribution and revision information)
The table of contents if the toc attribute is enabled (and not macro or preamble)
The converted document body
The footnotes unless the nofootnotes attribute is set
You can still generate a standalone document when converting a string. To go from an AsciiDoc string to a standalone output
document, you need to explicitly set the :header_footer option to true .
Now you’ll get back a full HTML 5 file.
You can get the same behavior when converting a file by setting the :header_footer option to false . However, most of the
time you’ll want to generate a standalone document when converting a file (which is the default).
Another way to implicitly enable the shell is to output the result to a file. In this case, the default output behavior changes from
embeddable to standalone.
When converting a string, the TOC is only included by default when using the :header_footer option as shown above.
However, you can force it to be included without the header and footer by setting the toc attribute with a value of macro and
using the toc::[] macro in the string itself.
79.2. Convert inline markup only
If you only want the inline markup to be returned, set the :doctype option to 'inline' :
In this mode, Asciidoctor will only process the first block (e.g., paragraph) in the document and ignore the rest.
79.3. Convert to DocBook
You can produce DocBook 5.0 by setting the backend option to 'docbook' . Since embeddable DocBook isn’t that useful, we also
enable the shell (i.e., header and footer) by setting the :header_footer option to true .
doc = Asciidoctor.load '*This* is Asciidoctor.'
RUBY
puts Asciidoctor.convert '*This* is Asciidoctor.'
RUBY
puts Asciidoctor.convert '*This* is Asciidoctor.', header_footer: true
RUBY
puts Asciidoctor.convert '*This* is Asciidoctor.', to_file: 'out.html'
RUBY
puts Asciidoctor.convert '*This* is Asciidoctor.', :doctype => 'inline'
RUBY
12/20/2018 Asciidoctor User Manual
https://asciidoctor.org/docs/user-manual/ 262/315
Let’s say you don’t like some (or all) of the output that Asciidoctor produces. That’s no problem. You can change it. And yes, any of
it! Let’s find out how to customize the output Asciidoctor spits out in the next chapter.
puts Asciidoctor.convert '*This* is Asciidoctor.', :header_footer => true,
:backend => 'docbook'
RUBY
12/20/2018 Asciidoctor User Manual
https://asciidoctor.org/docs/user-manual/ 263/315
80. Provide Custom Templates
Asciidoctor allows you to override the converter methods used to convert almost any individual AsciiDoc element. If you provide
a directory of Tilt (https://github.com/rtomayko/tilt)-compatible templates, named in such a way that Asciidoctor can figure out which
template goes with which element, Asciidoctor will use the templates in this directory instead of its built-in templates for any
elements for which it finds a matching template. It will fallback to its default templates for everything else.
The Document and Section templates should begin with document and section , respectively. The file extension is used by Tilt to
determine which view framework it will use to use to interpret the template. For instance, if you want to write the template in
ERB, you’d name these two templates document.html.erb and section.html.erb . The first file extension, .html , maps to the
converter and the second, .erb maps to the template engine. To use Haml as the template engine, you’d name the templates
document.html.haml and section.html.haml .
Templates for block elements, like a paragraph or sidebar, are named after the block they handle. For instance, to override the
default paragraph template with an ERB template, put a file named paragraph.html.erb in the template directory you pass to
the Document constructor using the :template_dir option.
For more usage examples, see the asciidoctor-backends (https://github.com/asciidoctor/asciidoctor-backends), the O’Reilly htmlbook
(https://github.com/oreillymedia/asciidoctor-htmlbook) project and the (massive) test suite
(https://github.com/asciidoctor/asciidoctor/tree/master/test).
puts Asciidoctor.convert '*This* is Asciidoctor.', :header_footer => true,
:template_dir => 'templates'
RUBY
12/20/2018 Asciidoctor User Manual
https://asciidoctor.org/docs/user-manual/ 264/315
Extensions
Extensions have proven to be central to the success of AsciiDoc because they open up the language to new use cases. However, the
way extensions are implemented in AsciiDoc Python presents a number of problems:
They are challenging to write because they work at such a low-level (read as: nasty regular expressions).
They are fragile since they often rely on system commands to do anything significant.
They are hard to distribute due to the lack of integration with a formal distribution system.
Asciidoctor addresses these issues by introducing a proper extension API that offers a superset of the extension points that
AsciiDoc Python provides. As a result, extensions in Asciidoctor are easier to write, more powerful, and simpler to distribute.
The goal for Asciidoctor has always been to allow extensions to be written using the full power of a programming language
(whether it be Ruby, Java, Groovy or JavaScript), similar to what we’ve done with the backend (conversion) mechanism. That way,
you don’t have to shave yaks to get the functionality you want, and you can distribute the extension using defacto-standard
packaging mechanisms like RubyGems or JARs.
The extension API in Asciidoctor is stable with the exception of inline macros. Since inline content is not parsed
until the convert phase, the inline macro processor must return converted text (e.g., HTML) rather than an AST
node. Once Asciidoctor is changed to process inline content during the parse phase
(https://github.com/asciidoctor/asciidoctor/issues/61), the inline macro processor will need to return an inline node.
When that switch occurs, there will either be some sort of adapter or required migration for inline macro
processors, but that has yet to be determined.
12/20/2018 Asciidoctor User Manual
https://asciidoctor.org/docs/user-manual/ 265/315
81. Extension Points
Here are the extension points that are available in Asciidoctor 0.1.4.
Preprocessor
Processes the raw source lines before they are passed to the parser.
TreeProcessor
Processes the Asciidoctor::Document (AST) once parsing is complete.
Postprocessor
Processes the output after the document has been converted, but before it’s written to disk.
DocinfoProcessor
Adds additional content to the header or footer regions of the generated document.
Block processor
Processes a block of content marked with a custom block style (i.e., [custom] ). (similar to an AsciiDoc filter)
Block macro processor
Registers a custom block macro and processes it (e.g., gist::12345[] ).
Inline macro processor
Registers a custom inline macro and processes it (e.g., SaveSave ).
Include processor
Processes the include::<filename>[] directive.
These extensions are registered per document using a callback that feels sort of like a DSL:
Extension classes must be defined outside of the register block. Once an extension class is registered, it is
frozen, preventing further modification. If you define an extension class inside the register block, it will result
in an error on subsequent invocations.
You can register more than one processor of each type, though you can only have one processor per custom block or macro. Each
registered class is instantiated when the Asciidoctor::Document is created.
There is currently no extension point for processing a built-in block, such as a normal paragraph. Look for that
feature in a future Asciidoctor release.
[ ]
Asciidoctor::Extensions.register dodo |document|
preprocessor FrontMatterPreprocessor
tree_processor ShellSessionTreeProcessor
postprocessor CopyrightFooterPostprocessor
docinfo_processor TrackingCodeDocinfoProcessor ifif document.basebackend? 'html'
block ShoutBlock
block_macro GistBlockMacro ifif document.basebackend? 'html'
inline_macro ManInlineMacro
include_processor UriIncludeProcessor
endend
RUBY
12/20/2018 Asciidoctor User Manual
https://asciidoctor.org/docs/user-manual/ 266/315
82. Example Extensions
Below are several examples of extensions and how they are registered.
82.1. Preprocessor Example
Purpose
Skim off front matter from the top of the document that gets used by site generators like Jekyll and Awestruct.
sample-with-front-matter.adoc
FrontMatterPreprocessor
Usage
82.2. Tree Processor Example
Purpose
Detect literal blocks that contain shell commands, strip the prompt character and style the command using CSS in such a way
that the prompt character cannot be selected (as seen on help.github.com).
sample-with-shell-session.adoc
---
tags: [announcement, website]
---
= Document Title
content
[subs="attributes,specialcharacters"]
.Captured front matter
....
---
{front-matter}
---
....
ASCIIDOC
require 'asciidoctor'
require 'asciidoctor/extensions'
classclass FrontMatterPreprocessorFrontMatterPreprocessor < Asciidoctor::Extensions::Preprocessor
defdef processprocess document, reader
lines = reader.lines
# get raw lines
returnreturn reader ifif lines.empty?
front_matter = []
ifif lines.first.chomp == '---'
original_lines = lines.dup
lines.shift
whilewhile !lines.empty? && lines.first.chomp != '---'
front_matter << lines.shift
endend
ifif (first = lines.first).nil? || first.chomp != '---'
lines = original_lines
elseelse
lines.shift
document.attributes['front-matter'] = front_matter.join.chomp
# advance the reader by the number of lines taken
(front_matter.length + 2).times { reader.advance }
endend
endend
reader
endend
endend
RUBY
Asciidoctor::Extensions.register dodo
preprocessor FrontMatterPreprocessor
endend
Asciidoctor.convert_file 'sample-with-front-matter.adoc', :safe => :safe
RUBY
12/20/2018 Asciidoctor User Manual
https://asciidoctor.org/docs/user-manual/ 267/315
ShellSessionTreeProcessor
Usage
82.3. Postprocessor Example
Purpose
Insert copyright text in the footer.
CopyrightFooterPostprocessor
Usage
$ echo "Hello, World!"
> Hello, World!
$ gem install asciidoctor
ASCIIDOC
classclass ShellSessionTreeProcessorShellSessionTreeProcessor < Asciidoctor::Extensions::TreeProcessor
defdef processprocess document
returnreturn unlessunless document.blocks?
process_blocks document
nil
endend
defdef process_blocksprocess_blocks node
node.blocks.each_with_index dodo |block, i|
ifif block.context == :literal &&
(((first_line = block.lines.first).start_with? '$ ') ||
(first_line.start_with? '> '))
node.blocks[i] = convert_to_terminal_listing block
elseelse
process_blocks block ifif block.blocks?
endend
endend
endend
defdef convert_to_terminal_listingconvert_to_terminal_listing block
attrs = block.attributes
attrs['role'] = 'terminal'
prompt_attr = (attrs.has_key? 'prompt') ?
%( data-prompt="#{block.sub_specialchars attrs['prompt']}") : nil
lines = block.lines.map dodo |line|
line = block.sub_specialchars line.chomp
ifif line.start_with? '$ '
%(<span class="command"#{prompt_attr}>#{line[2..-1]}</span>)
elsifelsif line.start_with? '> '
%(<span class="output">#{line[5..-1]}</span>)
elseelse
line
endend
endend
create_listing_block block.document, lines * EOL, attrs, subs: nil
endend
endend
RUBY
Asciidoctor::Extensions.register dodo
treeprocessor ShellSessionTreeProcessor
endend
Asciidoctor.convert_file 'sample-with-shell-session.adoc', :safe => :safe
RUBY
classclass CopyrightFooterPostprocessorCopyrightFooterPostprocessor < Asciidoctor::Extensions::Postprocessor
defdef processprocess document, output
content = (document.attr 'copyright') || 'Copyright Acme, Inc.'
ifif document.basebackend? 'html'
replacement = %(<div id="footer-text">\\1<br>\n#{content}\n</div>)
output = output.sub(/<div id="footer-text">(.*?)<\/div>/m, replacement)
elsifelsif document.basebackend? 'docbook'
replacement = %(<simpara>#{content}</simpara>\n\\1)
output = output.sub(/(<\/(?:article|book)>)/, replacement)
endend
output
endend
endend
RUBY
12/20/2018 Asciidoctor User Manual
https://asciidoctor.org/docs/user-manual/ 268/315
82.4. Docinfo Processor Example
Purpose
Appends the Google Analytics tracking code to the bottom of an HTML document.
GoogleAnalyticsDocinfoProcessor
Usage
82.5. Block Processor Example
Purpose
Register a custom block style named shout that uppercases all the words and converts periods to exclamation points.
sample-with-shout-block.adoc
ShoutBlock
Usage
Asciidoctor::Extensions.register do
postprocessor CopyrightFooterPostprocessor
end
Asciidoctor.convert_file 'sample-with-copyright-footer.adoc', :safe => :safe
ASCIIDOC
classclass GoogleAnalyticsDocinfoProcessorGoogleAnalyticsDocinfoProcessor < Asciidoctor::Extensions::DocinfoProcessor
use_dsl
at_location :footer
defdef processprocess document
returnreturn unlessunless (ga_account_id = document.attr 'google-analytics-account')
%(<script>
(function(i,s,o,g,r,a,m){i['GoogleAnalyticsObject']=r;i[r]=i[r]||function(){
(i[r].q=i[r].q||[]).push(arguments)},i[r].l=1*new Date();a=s.createElement(o),
m=s.getElementsByTagName(o)[0];a.async=1;a.src=g;m.parentNode.insertBefore(a,m)
})(window,document,'script','https://www.google-analytics.com/analytics.js','ga');
ga('create','#{ga_account_id}','auto');
ga('send','pageview');
</script>)
endend
endend
RUBY
Asciidoctor::Extensions.register dodo
docinfo_processor GoogleAnalyticsDocinfoProcessor
endend
Asciidoctor.convert_file 'sample.adoc', :safe => :safe,
:attributes => 'UA-ABCXYZ123'
RUBY
[shout]
The time is now. Get a move on.
ASCIIDOC
require 'asciidoctor'
require 'asciidoctor/extensions'
classclass ShoutBlockShoutBlock < Asciidoctor::Extensions::BlockProcessor
PeriodRx = /\.(?= |$)/
use_dsl
named :shout
on_context :paragraph
name_positional_attributes 'vol'
parse_content_as :simple
defdef processprocess parent, reader, attrs
volume = ((attrs.delete 'vol') || 1).to_i
create_paragraph parent, (reader.lines.map {|l| l.upcase.gsub PeriodRx, '!' * volume }), attrs
endend
endend
RUBY
12/20/2018 Asciidoctor User Manual
https://asciidoctor.org/docs/user-manual/ 269/315
82.6. Block Macro Processor Example
Purpose
Create a block macro named gist for embedding a gist.
sample-with-gist-macro.adoc
GistBlockMacro
Usage
82.7. Inline Macro Processor Example
Purpose
Create an inline macro named man that links to a man page.
sample-with-man-link.adoc
ManpageInlineMacro
Asciidoctor::Extensions.register dodo
block ShoutBlock
endend
Asciidoctor.convert_file 'sample-with-shout-block.adoc', :safe => :safe
RUBY
.My Gist
gist::123456[]
ASCIIDOC
require 'asciidoctor'
require 'asciidoctor/extensions'
classclass GistBlockMacroGistBlockMacro < Asciidoctor::Extensions::BlockMacroProcessor
use_dsl
named :gist
defdef processprocess parent, target, attrs
title_html = (attrs.has_key? 'title') ?
%(<div class="title">#{attrs['title']}</div>\n) : nil
html = %(<div class="openblock gist">
#{title_html}<div class="content">
<script src="https://gist.github.com/#{target}.js"></script>
</div>
</div>)
create_pass_block parent, html, attrs, subs: nil
endend
endend
RUBY
Asciidoctor::Extensions.register dodo
block_macro GistBlockMacro ifif document.basebackend? 'html'
endend
Asciidoctor.convert_file 'sample-with-gist.adoc', :safe => :safe
RUBY
See man:gittutorial[7] to get started.
ASCIIDOC
12/20/2018 Asciidoctor User Manual
https://asciidoctor.org/docs/user-manual/ 270/315
Usage
82.8. Include Processor Example
Purpose
Include a file from a URI.
Asciidoctor supports including content from a URI out of the box if you set the allow-uri-read attribute (not
available if the safe mode is secure ).
sample-with-uri-include.adoc
UriIncludeProcessor
Usage
require 'asciidoctor'
require 'asciidoctor/extensions'
classclass ManInlineMacroManInlineMacro < Asciidoctor::Extensions::InlineMacroProcessor
use_dsl
named :man
name_positional_attributes 'volnum'
defdef processprocess parent, target, attrs
text = manname = target
suffix = ''
target = %(#{manname}.html)
suffix = ifif (volnum = attrs['volnum'])
"(#{volnum})"
elseelse
nil
endend
parent.document.register :links, target
%(#{(create_anchor parent, text, type: :link, target: target).convert}#{suffix})
endend
endend
RUBY
Asciidoctor::Extensions.register dodo
inline_macro ManInlineMacro
endend
Asciidoctor.convert_file 'sample-with-man-link.adoc', :safe => :safe
RUBY
:source-highlighter: coderay
.Gemfile
[source,ruby]
----
include::https://raw.githubusercontent.com/asciidoctor/asciidoctor/master/Gemfile[]
----
ASCIIDOC
require 'asciidoctor'
require 'asciidoctor/extensions'
require 'open-uri'
classclass UriIncludeProcessorUriIncludeProcessor < Asciidoctor::Extensions::IncludeProcessor
defdef handles?handles? target
(target.start_with? 'http://') oror (target.start_with? 'https://')
endend
defdef processprocess doc, reader, target, attributes
content = (open target).readlines
reader.push_include content, target, target, 1, attributes
reader
endend
endend
RUBY
Asciidoctor::Extensions.register dodo
include_processor UriIncludeProcessor
endend
Asciidoctor.convert_file 'sample-with-uri-include.adoc', :safe => :safe
RUBY
12/20/2018 Asciidoctor User Manual
https://asciidoctor.org/docs/user-manual/ 273/315
83. Java
AsciidoctorJ (https://github.com/asciidoctor/asciidoctorj) is the official library for running Asciidoctor on the JVM. Using AsciidoctorJ,
you can convert AsciiDoc content or analyze the structure of a parsed AsciiDoc document from Java and other JVM languages. For
details see Getting Started with Asciidoctor in Java using AsciidoctorJ (https://asciidoctor.org/docs/asciidoctorj).
12/20/2018 Asciidoctor User Manual
https://asciidoctor.org/docs/user-manual/ 274/315
84. Gradle
The Asciidoctor Gradle Plugin (https://github.com/asciidoctor/asciidoctor-gradle-plugin) is the official means of using Asciidoctor to
convert all your AsciiDoc documentation using Gradle. For details see Getting Started with the Asciidoctor Gradle Plugin
(https://asciidoctor.org/docs/asciidoctor-gradle-plugin/).
12/20/2018 Asciidoctor User Manual
https://asciidoctor.org/docs/user-manual/ 275/315
85. Maven
The Asciidoctor Maven Plugin (https://github.com/asciidoctor/asciidoctor-maven-plugin) is the official way to convert your AsciiDoc
documentation using Asciidoctor from an Apache Maven build. For details see Installing and Using the Asciidoctor Maven Plugin
(https://asciidoctor.org/docs/asciidoctor-maven-plugin).
12/20/2018 Asciidoctor User Manual
https://asciidoctor.org/docs/user-manual/ 276/315
86. Apache Ant
The asciidoctor-ant task is an all-in-one solution for running Asciidoctor from Ant. It is based on AsciidoctorJ and JRuby, both
of which are encapsulated in a single jar file.
Usage is:
For more details, see asciidoctor-ant on GitHub (https://github.com/asciidoctor/asciidoctor-ant#asciidoctor-ant-task).
<project xmlns:asciidoctor="antlib:org.asciidoctor.ant">
...
<target name="doc">
<taskdef uri="antlib:org.asciidoctor.ant"
resource="org/asciidoctor/ant/antlib.xml"
classpath="lib/asciidoctor-ant.jar"/>
<asciidoctor:convert sourceDirectory="src/asciidoc" outputDirectory="target"/>
</target>
...
</project>
XML
12/20/2018 Asciidoctor User Manual
https://asciidoctor.org/docs/user-manual/ 277/315
87. JavaDoc
Using the Asciidoctor doclet (https://github.com/asciidoctor/asciidoclet), you can write your Javadoc comments using all the features of
Asciidoctor including tables, lists, code examples with syntax highlighting, and pictures.
If you want to incorporate your Javadoc into another document instead, there is an experimental doclet that exports them to
AsciiDoc files. See the exportdoclet project (https://github.com/johncarl81/exportdoclet) and the related discussion thread
(http://discuss.asciidoctor.org/Export-Javadoc-strings-td4172.html) for details.
12/20/2018 Asciidoctor User Manual
https://asciidoctor.org/docs/user-manual/ 278/315
88. JavaScript
Asciidoctor.js (https://github.com/asciidoctor/asciidoctor.js) is a JavaScript port of Asciidoctor, transpiled directly from the Ruby version.
Asciidoctor.js brings the AsciiDoc syntax to the browser and the Node.js ecosystem. For details see Installing and Using
Asciidoctor.js (https://asciidoctor.org/docs/install-and-use-asciidoctorjs).
12/20/2018 Asciidoctor User Manual
https://asciidoctor.org/docs/user-manual/ 279/315
Conversions and Migrations
In this part, you’ll learn how to migrate documents written in other documentation languages to AsciiDoc. We’ll start with the
simplest migration, switching from AsciiDoc Python, the original implementation of AsciiDoc, to Asciidoctor, the modern
implementation. We’ll then cover how to move to AsciiDoc from other documentation languages like DocBook, Markdown and
HTML. In addition to differences in the syntax, many of the sections also suggest tools you can use to ease the migration.
12/20/2018 Asciidoctor User Manual
https://asciidoctor.org/docs/user-manual/ 280/315
89. Migrating from AsciiDoc Python
The purpose of this section is to help you migrate legacy AsciiDoc documents written for AsciiDoc Python to the modern AsciiDoc
syntax supported by Asciidoctor and to learn about equivalent tools and extensions.
The differences are minor, so most documents will need very few changes, if any. Once you’ve made the necessary changes, this
section also describes how to take advantage of the new features provided in Asciidoctor.
This section specifically covers migration from AsciiDoc Python 8 to Asciidoctor 1.5.x. The content assumes
you’ve already updated any content that is deprecated as of AsciiDoc Python 8.
89.1. Command Line Interface
Asciidoctor was designed from the outset to be a (must faster) drop-in replacement for AsciiDoc Python. For most documents, you
can simply replace the call to AsciiDoc Python:
$ asciidoc document.adoc
with an equivalent call to Asciidoctor:
$ asciidoctor -a compat-mode document.adoc
If you run into trouble, check out the differences below, namely Deleted and Deprecated Syntax and Attributes.
Keep in mind you can also run Asciidoctor on the JVM using AsciidoctorJ (https://github.com/asciidoctor/asciidoctorj)
or with JavaScript using Asciidoctor.js (https://github.com/asciidoctor/asciidoctor.js).
89.1.1. Help Topics
In both AsciiDoc Python and Asciidoctor, the --help CLI option shows the command usage by default. They differ in how they
handle the optional topic argument.
In AsciiDoc Python, the --help syntax topic shows a syntax cheatsheet and the --help manpage topic shows a plaintext
version of the man page.
Asciidoctor only supports the manpage help topic. However, it outputs the formatted man page rather than the plaintext version.
Therefore, to view it, you need to pipe the result to the man command as follows:
$ asciidoctor --help manpage | man /dev/stdin
or
$ asciidoctor --help manpage | man -l -
If you want to view the plaintext version, you can route the output through the col command as follows:
$ asciidoctor --help manpage | man -l - | col -bx
You can also view the man page for Asciidoctor online at asciidoctor(1) (https://asciidoctor.org/man/asciidoctor).
To get help with the AsciiDoc syntax in Asciidoctor, refer to the AsciiDoc Syntax Quick Reference
(https://asciidoctor.org/docs/asciidoc-syntax-quick-reference/).
89.1.2. Conguration Files
Asciidoctor does not use .conf files or filters, so --conf-file , --dump-conf , and --filter are not implemented. Asciidoctor
provides an extension API that replaces the configuration-based extension and filter mechanisms in AsciiDoc Python.
89.1.3. Internationalization
12/20/2018 Asciidoctor User Manual
https://asciidoctor.org/docs/user-manual/ 281/315
AsciiDoc Python has built-in .conf files that are used to translate built-in labels. You load the .conf file for a given language by
setting the lang attribute to a supported language code (e.g., -a lang=<language code> ). In Asciidoctor, you must define the
translations for these labels explicitly. See Using Asciidoctor with Other Languages for details.
89.1.4. Themes
AsciiDoc Python provides a theming mechanism that encapsulates CSS, JavaScript and images. The --theme option activates one
of these themes, which is resolved from your home directory. In Asciidoctor, you control the theme using CSS (i.e., a stylesheet)
only, which you can specify using -a stylesheet=<stylesheet> .
If you require more advanced theming, you can inject additional resources using a docinfo file or use a postprocessor extension.
89.1.5. Default HTML Backend
AsciiDoc Python uses XHTML 1.1 as its default output (the xhtml11 backend), though it supports HTML5 output as well (the html5
backend). Asciidoctor defaults to creating HTML5 output (the html5 backend), which closely adheres to the backend by the same
name in AsciiDoc Python. The web has moved forward since AsciiDoc Python was created, so the switch to HTML5 is
recommended anyway.
89.1.6. Doctest
AsciiDoc Python --doctest runs units tests. See Tests (https://github.com/asciidoctor/asciidoctor/tree/master/test) for how to run the
Asciidoctor unit tests.
Asciidoctor also has a doctest tool (https://github.com/asciidoctor/asciidoctor-doctest) which you can use when creating custom HTML or
XML-based converters.
89.2. Changed Syntax
These changes are not backward-compatible, but if you set the compat-mode attribute, Asciidoctor will accept the AsciiDoc
Python syntax. For the long term, you should update to the Asciidoctor syntax. Consult the Migration Guide
(https://asciidoctor.org/docs/migration/) to get the full details and learn how to migrate smoothly.
AsciiDoc syntax affected by compat mode
Feature AsciiDoc Python (or Asciidoctor in
compat mode)
Asciidoctor (no compat mode)
italic text 'italic text' or _italic text_ _italic text_
monospaced text +monospaced text+ `monospaced text`
monospaced text (literal) `{asciidoc-version}` `+{asciidoc-version}+`
``double quotes'' ``double quotes''
not available in compat mode
"`double quotes`" or insert the Unicode
quote characters using your editor
`single quotes' `single quotes'
not available in compat mode
'`single quotes`' or insert the Unicode
quote characters using your editor
Document title Title or = Title
=====
= Title
Asciidoctor accepts the two-line heading style to set the document title. However, by using it, you implicitly set compat-mode . If
you want to use the new Asciidoctor syntax, make sure to use the single-line style for the document title or unset the compat-
mode attribute explicitly.
The following changes are not affected by the compat-mode attribute:
AsciiDoc syntax not affected by compat mode
Feature AsciiDoc Python Asciidoctor
Underlined titles Underline length must match
title length +/- 2 characters.
Underline length must match title length +/- 1 character
(Underlined titles are deprecated anyway. See Sections.)
ifeval::[] Evaluates any Python
expression.
Evaluates simple logical expressions testing the value of
attributes. See ifeval directive.
[1]
[1]
12/20/2018 Asciidoctor User Manual
https://asciidoctor.org/docs/user-manual/ 282/315
Feature AsciiDoc Python Asciidoctor
Block delimiters Delimiter lines do not have
to match in length.
The length of start and end delimiter lines must match
exactly.
AsciiDoc table cell a| or asciidoc| a| only
Table cell separator A Python regular expression. One or more literal characters or \t for tab.
89.3. Deleted and Deprecated Syntax and Attributes
These are attributes that either no longer exist, work differently, or have better alternatives.
Deleted and deprecated syntax and attributes
AsciiDoc Python Asciidoctor Notes
big , small ,
underline ,
overline , line-
through , colors
deprecated Character attributes to apply formatting directly. Usually better to apply a
role, then apply the formatting based on that role by using a stylesheet.
halign , valign for
table cells
Column and cell
specifiers
See Cell Formatting.
infile not implemented Provides the name and directory of the current document. (Distinct from
docfile , because infile may be an included document, and docfile
is always the master document.) No Asciidoctor equivalent.
indir
asciidoc asciidoctor AsciiDoc Python sets asciidoc to show that it is the current processor.
Asciidoctor sets asciidoctor instead.
toc2 toc Combined in a single attribute, see Table of Contents.
toc-placement
toc-position
options="pgwide" not implemented DocBook attribute to make tables full page width, whatever the current
indent. No Asciidoctor equivalent.
options="unbreakable" In Asciidoctor, this only works for tables, not paragraphs.
plaintext not implemented AsciiDoc Python uses this to suppress inline substitutions and retain block
indents when importing large blocks of plain text. Asciidoctor deliberately
does not implement it; the closest Asciidoctor equivalent is a passthrough
block.
replacements2 post_replacements Renamed.
presubs - Not required.
showcomments not implemented In AsciiDoc Python, turns single line comments into DocBook <remark>
elements. Asciidoctor considers this an inappropriate use of comments. If
you want to send remarks to the output, use an extension, or:
specialwords not implemented In AsciiDoc Python, applies special formatting to named text. In
Asciidoctor this could be implemented using an extension.
ifdef::showcomments+basebackend-docbook[]
++++
<remark>Your comment here</remark>
++++
endif::[]
12/20/2018 Asciidoctor User Manual
https://asciidoctor.org/docs/user-manual/ 283/315
AsciiDoc Python Asciidoctor Notes
tabsize (in-document
and include directive)
in-document only AsciiDoc Python replaces tabs with spaces in all text, using a default tab
size of 8. Asciidoctor only replaces tabs with spaces in verbatim content
blocks (listing, literal, etc), and the attribute has no default. In other words,
tabs are not expanded in verbatim content blocks unless this attribute is
set on the block or the document. For all other text, Asciidoctor tabs are
fixed at 4 spaces by the CSS. See Normalize Block Indentation for more
detail.
89.4. Default HTML Stylesheet
You’ll notice that the AsciiDoc Python and Asciidoctor stylesheets look quite different. However, they are compatible (for the most
part) since the formatting is based on the same HTML structure and CSS classes. If you happen to prefer the AsciiDoc Python
stylesheet, you can use it by copying it from the AsciiDoc Python stylesheets directory and instructing Asciidoctor to apply it using:
$ asciidoctor -a stylesheet=asciidoc.css document.adoc
Keep in mind that the default stylesheet in Asciidoctor is just that, a default. If you don’t like its appearance,
you can either customize it or choose another stylesheet. You can find a collection of alternative themes in the
Asciidoctor Stylesheet Factory (http://themes.asciidoctor.org).
Unlike AsciiDoc Python, Asciidoctor loads some resources from a CDN. It’s possible to configure Asciidoctor to
load all resources from local files. For instance, you can unset the webfonts attribute so that the generated
HTML does not use fonts from Google Fonts. There are similar attributes to control how additional resources
are resolved.
89.5. Mathematical Expressions
Both AsciiDoc Python and Asciidoctor can convert embedded LaTeX and AsciiMath expressions (e.g., asciimath:[expression] ,
latexmath:[expression] , etc), but with Asciidoctor you need to activate STEM support first using the stem attribute (see
Activating stem support).
For block content, AsciiDoc Python uses a [latex] style delimited block. In Asciidoctor, use a stem passthrough block instead.
See Block Stem Content.
89.6. AsciiDoc Python Extensions
The extension mechanism is completely different in Asciidoctor, but the ‘standard’ extensions have been re-implemented, so they
should work with minor changes.
Standard extensions
AsciiDoc Python Asciidoctor
source You can choose from a number of highlighters Syntax Highlighting Source Code.
Highlighters are built-in, not separately installed.
src_numbered , src_tab , args are not implemented directly, but check the highlighter you are
using for what features it has and how to configure them.
music Not implemented.
latex (block macro) Use a stem passthrough block Block Stem Content.
graphviz Incorporated into Asciidoctor Diagram (https://github.com/asciidoctor/asciidoctor-diagram/).
89.7. Custom Extensions
AsciiDoc Python custom extensions will not work with Asciidoctor because AsciiDoc Python extensions are essentially Python
commands, and the Asciidoctor extensions are Ruby (or Java) classes. To re-write your extensions, see Extensions.
89.8. Features Introduced by Asciidoctor
12/20/2018 Asciidoctor User Manual
https://asciidoctor.org/docs/user-manual/ 284/315
89.8.1. New Syntax
Asciidoctor has shorthand for id, role, style and options. See Setting Attributes on an Element for details.
The following longhand syntax in AsciiDoc Python:
can be written using the shorthand supported by Asciidoctor:
The longhand forms still work, but you should use the new forms for future compatibility, convenience and readability.
89.8.2. Enhancements
There are lots of new features and improvements Asciidoctor. These are some of the more interesting ones when migrating:
Partial includes
Additional safe modes
Icon-based fonts and inline icons
Asciidoctor Diagram (https://github.com/asciidoctor/asciidoctor-diagram/)
A detailed list of the improvements is shown in Differences between Asciidoctor and AsciiDoc Python
(https://asciidoctor.org/docs/asciidoc-asciidoctor-diffs/).
89.8.3. Recommended Practices
See the AsciiDoc Style Guide and Recommended Practices (https://asciidoctor.org/docs/asciidoc-recommended-practices/) for ways to make
your documents clearer and more consistent.
[[id]]
[style,role="role",options="option1,option2"]
ASCIIDOC
[style#id.role%option1%option2]
ASCIIDOC
12/20/2018 Asciidoctor User Manual
https://asciidoctor.org/docs/user-manual/ 285/315
90. Convert DocBook XML to AsciiDoc
One of the things Asciidoctor excels at is converting AsciiDoc source into valid and well-formed DocBook XML content.
What if you’re in the position where you need to go the other way: migrate all your legacy DocBook XML content to AsciiDoc? The
prescription (℞) you need to get rid of your DocBook pains could be DocBookRx (https://github.com/opendevise/docbookrx).
DocBookRx is an early version of a DocBook to AsciiDoc converter written in Ruby. This converter is far from perfect at the
moment, but it improves with each document it converts.
The plan is to evolve it into a robust library for performing this conversion in a reliable way. You can read more about this
initiative in the README (https://github.com/opendevise/docbookrx/blob/master/README.adoc).
The best thing about this tool is all the active users who are putting it through its paces. The more advanced the DocBook XML this
tool tackles, and the more feedback we receive, the better the tool will become. Use it today to escape from XML hell!
12/20/2018 Asciidoctor User Manual
https://asciidoctor.org/docs/user-manual/ 286/315
91. Convert Markdown to AsciiDoc
Asciidoctor recognizes a fair amount of Markdown syntax, thus allowing you to migrate from Markdown to AsciiDoc gradually.
See Markdown Compatibility (https://asciidoctor.org/docs/asciidoc-syntax-quick-reference/#markdown-compatibility) to learn what syntax is
shared. The syntax you must change is listed in A selection of AsciiDoc language features compared to Markdown.
12/20/2018 Asciidoctor User Manual
https://asciidoctor.org/docs/user-manual/ 287/315
92. Convert Conuence XHTML to AsciiDoc
You can convert Atlassian Confluence XHTML pages to Asciidoctor using this Groovy (http://www.groovy-lang.org/download.html)
script.
The script calls Pandoc (https://pandoc.org/) to convert single or multiple HTML files exported from Confluence to AsciiDoc files.
You’ll need Pandoc installed before running this script.
If you have trouble running this script, you can use the Pandoc command referenced inside the script to
convert XHTML files to AsciiDoc manually.
convert.groovy
The script is designed to be run locally on HTML files or directories containing HTML files exported from Confluence.
Usage
1. Save the script contents to a convert.groovy file in a working directory.
2. Make the file executable according to your specific OS requirements.
3. Place individual files, or a directory containing files into the working directory.
4. Run groovy convert filename.html to convert a single file.
5. Confirm the output file meets requirements
6. Recurse through a directory by using this command pattern: groovy convert directory/*.html
This script was created by Cédric Champeau (melix (https://gist.github.com/melix)). You can find the source of this script hosted at this
GitHub Gist (https://gist.github.com/melix/6020336).
@Grab('net.sourceforge.htmlcleaner:htmlcleaner:2.4')
importimport org.htmlcleaner.*
defdef src = newnew File('html').toPath()
defdef dst = newnew File('asciidoc').toPath()
defdef cleaner = newnew HtmlCleaner()
defdef props = cleaner.properties
props.translateSpecialEntities = false
defdef serializer = newnew SimpleHtmlSerializer(props)
src.toFile().eachFileRecurse { f ->
defdef relative = src.relativize(f.toPath())
defdef target = dst.resolve(relative)
ifif (f.isDirectory()) {
target.toFile().mkdir()
} elseelse ifif (f.name.endsWith('.html')) {
defdef tmpHtml = File.createTempFile('clean', 'html')
println "Converting $relative"
defdef result = cleaner.clean(f)
result.traverse({ tagNode, htmlNode ->
tagNode?.attributes?.remove 'class'
ifif ('td' == tagNode?.name || 'th'==tagNode?.name) {
tagNode.name='td'
String txt = tagNode.text
tagNode.removeAllChildren()
tagNode.insertChild(0, newnew ContentNode(txt))
}
true
} asas TagNodeVisitor)
serializer.writeToFile(
result, tmpHtml.absolutePath, "utf-8"
)
"pandoc -f html -t asciidoc -R -S --normalize -s $tmpHtml -o ${target}.adoc".execute().waitFor()
tmpHtml.delete()
}
/* else {
"cp html/$relative $target".execute()
}*/
}
GROOVY
12/20/2018 Asciidoctor User Manual
https://asciidoctor.org/docs/user-manual/ 290/315
94. Copyright and License
Copyright © 2012-2018 Dan Allen, Sarah White, and Ryan Waldron. Free use of this software is granted under the terms of the
MIT License.
See the LICENSE (https://github.com/asciidoctor/asciidoctor/blob/master/LICENSE) file for details.
12/20/2018 Asciidoctor User Manual
https://asciidoctor.org/docs/user-manual/ 291/315
95. Authors
Asciidoctor was written by Dan Allen (https://github.com/mojavelinux), Sarah White (https://github.com/graphitefriction), Ryan Waldron
(https://github.com/erebor), Jason Porter (https://github.com/lightguard), Nick Hengeveld (https://github.com/nickh) and other contributors
(https://github.com/asciidoctor/asciidoctor/graphs/contributors).
The initial code from which Asciidoctor emerged was written by Nick Hengeveld (https://github.com/nickh) to process the git man
pages for the Git project site (https://github.com/github/gitscm-next). Refer to the commit history of asciidoc.rb
(https://github.com/github/gitscm-next/commits/master/lib/asciidoc.rb) to view the initial contributions.
AsciiDoc was written by Stuart Rackham and has received contributions from many other individuals.
12/20/2018 Asciidoctor User Manual
https://asciidoctor.org/docs/user-manual/ 292/315
96. Troubleshooting
1. Part way through the document, the blocks stop rendering correctly. What went wrong?
When content is not rendered as you expect in the later part of a document, it’s usually due to a delimited block missing its
closing delimiter line. The most devious culprit is the open block. An open block doesn’t have any special styling, but its
contents have the same restrictions as other delimited blocks, i.e. it can not contain section titles.
To solve this problem, first look for missing delimiter lines. Syntax highlighting in your text editor can help with this. Also look
at the rendered output to see if the block styles are extending past where you intended. When working with open blocks, you
may need to add custom styles (such as a red border) to the class openblock so you can see its boundaries.
2. Why don’t URLs containing underscores ( _) or carets ( ^) work after they’re converted?
This problem occurs because the markup parser interprets parts of the URL (i.e., the link target) as valid text formatting
markup. Most lightweight markup languages have this issue because they don’t use a grammar-based parser. Asciidoctor
plans to handle URLs more carefully in the future (see issue #281 (https://github.com/asciidoctor/asciidoctor/issues/281)), which may
be solved by moving to a grammar-based parser (see issue #61 (https://github.com/asciidoctor/asciidoctor/issues/61)). Thankfully,
there are many ways to include URLs of arbitrary complexity using the AsciiDoc passthrough mechanisms.
Solution A
The simplest way to get a link to behave is to assign it to an attribute.
Asciidoctor won’t break links with underscores when they are assigned to an attribute because inline formatting
markup is substituted before attributes. The URL remains hidden while the rest of the document is being formatted
(strong, emphasis, monospace, etc).
Solution B
Another way to solve formatting glitches is to explicitly specify the formatting you want to have applied to a span of text.
This can be done by using the inline pass macro. If you want to display a URL, and have it preserved, put it inside the
pass macro and enable the macros substitution, which is what substitutes links.
The pass macro removes the URL from the document, applies the macros substitution to the URL, and then restores the
processed URL to its original location once the substitutions are complete on the whole document.
Alternatively, you can use ++ around the URL only. However, when you use this approach, Asciidoctor won’t recognize
it as a URL any more, so you have to use the explicit link prefix.
For more information, see issue #625 (https://github.com/asciidoctor/asciidoctor/issues/625).
= Document Title
:link-with-underscores: https://asciidoctor.org/now_this__link_works.html
This URL has repeating underscores {link-with-underscores}.
ASCIIDOC
This URL has repeating underscores pass:macros[https://asciidoctor.org/now_this__link_works.html].
ASCIIDOC
This URL has repeating underscores link:++https://asciidoctor.org/now_this__link_works.html++[].
ASCIIDOC
12/20/2018 Asciidoctor User Manual
https://asciidoctor.org/docs/user-manual/ 293/315
Glossary
admonition
a callout paragraph or block that has a label or icon indicating its priority.
backend
a moniker for the expected output format; used as a key to select which converter to use; often used interchangeably with the
name of a converter (i.e., the "html5" backend").
block attribute
an attribute associated with a delimited block or paragraph; these attributes can affect processing of the block, and are
available to block processors, but cannot be referenced using an attribute reference.
built-in attribute
a document attribute that controls processing, integrations, styling, and localization.
cross reference
a link from one location in the document to another location marked by an anchor.
document attribute
an attribute associated with the document (node); in other words, an attribute in the global document attributes dictionary; the
value of these attributes can be referenced using an attribute reference; if defined in the header, the document attribute is
known as a header attribute.
environment attribute
a dynamic document attribute that pertains to, or gives information about, the runtime environment.
header attribute
a document attribute defined in the document header; visible from all nodes in the document; often required for global settings
such as the source highlighter or icons mode.
list continuation
a plus sign ( +) on a line by itself that connects adjacent lines of text to a list item.
macro attribute
an attribute associated with a block or inline macro; these attributes can affect processing of the macro, and are available to
macro processors, but cannot be referenced using an attribute reference.
predefined attribute
a document attribute defined for convenience; often used for inserting special content characters.
quoted text
text which is enclosed in special punctuation to give it emphasis or special meaning.
user-defined attribute
a document attribute defined by the content author; used for storing reusable content, and controlling conditional inclusion.
12/20/2018 Asciidoctor User Manual
https://asciidoctor.org/docs/user-manual/ 294/315
Appendix A: Catalog of Document Attributes
This appendix catalogs all the recognized document attributes in Asciidoctor. It includes environment, built-in and predefined
(aka character reference) attributes. Authors may define any number of additional attributes (aka user-defined attributes) for
their own purposes.
A.1. Environment Attributes
Asciidoctor automatically assigns values to various document attributes whenever a document is loaded or converted. These
attributes, termed environment attributes, provide information about the runtime environment, such as how, where and when
the document is being processed. Like other document attributes, environment attributes can be referenced whereever attribute
references are permitted. It’s recommended that you treat these attributes as read only.
Environment attributes
Attribute Description Example Value
asciidoctor Set if the current processor is Asciidoctor.
asciidoctor-version Asciidoctor version. 1.5.7.1
backend Backend used to create the output file. html5
basebackend The backend value minus any trailing numbers. For
example, if the backend is docbook5 , the
basebackend is docbook .
html
docdate Last modified date of the source document. 2019-01-04
docdatetime Last modified date and time of the source
document.
2019-01-04 19:26:06 UTC
docdir Full path of the directory that contains the source
document.
/home/user/docs
docfile Full path of the source document. /home/user/docs/userguide.adoc
docfilesuffix File extension of the source document, including
the leading period. Introduced in 1.5.6.
.adoc
docname Root name of the source document (no leading path
or file extension).
userguide
doctime Last modified time of the source document. 19:26:06 UTC
doctype Document type (article, book or manpage). article
docyear Year that the document was last modified. 2018
embedded Set if content is being converted to an embeddable
document (body only).
filetype File extension of the output file name (without
leading period).
html
htmlsyntax Syntax used when generating the HTML output
(html or xhtml).
html
localdate Date when the document was converted. 2019-02-17
localdatetime Date and time when the document was converted. 2019-02-17 19:31:05 UTC
localtime Time when the document was converted. 19:31:05 UTC
localyear Year when the document was converted. 2018
outdir Full path of the output directory. /home/user/docs/dist
[1,2]
[1,2]
[1,2]
[1,2]
[2]
[2]
[2]
[2]
12/20/2018 Asciidoctor User Manual
https://asciidoctor.org/docs/user-manual/ 295/315
Attribute Description Example Value
outfile Full path of the output file. /home/user/docs/dist/userguide.html
outfilesuffix File extension of the output file (starting with a
period) as determined by the backend ( .html for
html , .xml for docbook , etc.). (The value is not
updated to match the file extension of the output
file when one is specified explicitly). Safe to modify.
.html
safe-mode-level Numeric value of the safe mode setting. (UNSAFE=0,
SAFE=10, SERVER=10, SECURE=20).
20
safe-mode-name Textual value of the safe mode setting. SERVER
safe-mode-unsafe Set if the safe mode is UNSAFE.
safe-mode-safe Set if the safe mode is SAFE.
safe-mode-server Set if the safe mode is SERVER.
safe-mode-secure Set if the safe mode is SECURE.
user-home Home directory of the current user. Resolves to . if
the safe mode is SERVER or greater.
/home/user
Only reflects the last modified time of the source document file. It does not consider the last modified time of files which are
included.
If the SOURCE_DATE_EPOCH environment variable is set, the value assigned to this attribute is built from a UTC date object that
corresponds to the timestamp (as an integer) stored in that environment variable. This override offers one way to make the
conversion reproducible. See https://reproducible-builds.org/specs/source-date-epoch/ for more information about the
SOURCE_DATE_EPOCH environment variable. Otherwise, the date is expressed in the local time zone, which is reported as a time
zone offset (e.g., -0600 ) or UTC if the time zone offset is 0). To force the use of UTC, set the TZ=UTC environment variable when
invoking Asciidoctor.
A.2. Built-in Attributes
Built-in document attributes can be set anywhere in the document using an attribute entry line. However, there are some rules to
keep in mind regarding the impact of that assignment.
Many attributes can only be defined in the document header (or via the API or CLI). Otherwise, they won’t have the desired
impact. These are called header attributes. This requirement is marked in the table below.
To set an attribute that does not accept a value, simply use an empty value (as indicated by empty in the table).
If you set an attribute from the command line or API, it’s defined for the whole document and cannot be changed in the body
unless @ is added to the end of the value. (The one exception to this rule is the sectnums attribute, which can always be
changed).
If you set an attribute in the body (anywhere after the document header), the attribute is visible from the point it is set until it
is unset (assuming it is not locked as a result of being set from the command line or API).
Several attributes from AsciiDoc Python have been removed (or deprecated) in Asciidoctor and therefore are
not included in this section. See Migrating from AsciiDoc Python if you are updating an older document.
Built-in document attributes
Attribute
name
Description Default value Allowed
values
Header
only
See also
Compliance
attribute-
missing
Controls how missing references are
handled.
skip skip, drop,
drop-line or
warn
[catch-a-missing-or-undefined-attribu
[1]
[2]
[1]
12/20/2018 Asciidoctor User Manual
https://asciidoctor.org/docs/user-manual/ 296/315
Attribute
name
Description Default value Allowed
values
Header
only
See also
attribute-
undefined
Controls how expressions that undefine
an attribute are handled.
drop-line drop or drop-
line
[catch-a-missing-or-undefined-attribu
compat-mode Controls whether the legacy parser is
used to parse the document.
not set (Modern
parser is used).
empty
(Legacy
parser is
used).
Migrating from AsciiDoc Python
experimental Enable experimental extensions. The
features behind this attribute are
subject to change and may even be
removed in a future version. Currently
enables the UI macros (button, menu
and kbd).
not set empty User Interface Macros
reproducible If set, prevents the last-updated date
from being added to the HTML footer
or DocBook info element. Alternatively,
you can use the SOURCE_DATE_EPOCH
environment variable to fix the value.
Useful if you want to store the output in
a source code control system as it
prevents spurious changes every time
you convert the document.
not set empty
Internationalization and numbering
appendix-
caption
Sets the text used to prefix appendix
titles.
Appendix any Appendix, Translating built-in labels
appendix-
number
Stores the number (aka letter) for the
current appendix.
Aletter
appendix-
refsig
Sets the signifier added to the title of
appendices in cross reference text.
Unset to disable.
Appendix any Book Parts and Chapters, Sections, Tra
built-in labels
caution-
caption
Sets the text used to label CAUTION
admonitions when icons are not
enabled.
Caution any Admonition, Translating built-in label
chapter-
number
Stores the number for the current
chapter.
2integer
chapter-refsig Sets the signifier added to the title of
numbered chapters in cross reference
text. Unset to disable.
Chapter any Book Parts and Chapters, Sections, Tra
built-in labels
chapter-label Sets the prefix added to chapter titles
(i.e., level-1 section titles when doctype
is book). (pdf converter only)
Chapter any Book Parts and Chapters, Sections, Tra
built-in labels
example-
caption
Sets the text used to label example
blocks.
Example any Translating built-in labels
example-
number
Stores the number for the current
numbered example.
5integer
figure-caption Sets the text used to label figures. Figure any Images, Translating built-in labels
[1]
[2]
[2]
[2]
12/20/2018 Asciidoctor User Manual
https://asciidoctor.org/docs/user-manual/ 297/315
Attribute
name
Description Default value Allowed
values
Header
only
See also
figure-
number
Stores the number for the current
numbered figure.
3integer
important-
caption
Sets the text used to label IMPORTANT
admonitions when icons are not
enabled.
Important any Admonition, Translating built-in label
lang Set the value of the lang attribute on
the root element of the output
document.
en Valid XML
country code
Translating built-in labels
last-update-
label
Text label for the “Last updated” time
in the footer. Unsetting it will remove
the label and time from the footer.
Last updated any Footer docinfo files, Translating built-
listing-caption Sets the text used to label listing blocks. not set any Translating built-in labels
listing-
number
Stores the number for the current
numbered listing.
5integer
manname-
title
Label for the program name section in
the man page.
NAME any Translating built-in labels
nolang Prevents the lang attribute from being
added to root element of the output
document.
not set empty
note-caption Sets the text used to label NOTE
admonitions when icons are not
enabled.
Note any Admonition, Translating built-in label
preface-title Sets the title text for an anonymous
preface when the doctype is book.
not set any Preface
section-refsig Sets the signifier added to the title of
numbered sections in cross reference
text. Unset to disable.
Section any Book Parts and Chapters, Sections, Tra
built-in labels
table-caption Text of the label that is automatically
prefixed to table titles. To turn off table
caption labels and numbers, add the
table-caption attribute to the
document header with an empty value.
Table any Translating built-in labels
table-number Stores the number for the current
numbered table.
5integer
tip-caption Sets the text used to label TIP
admonitions when icons are not
enabled.
Tip any Admonition, Translating built-in label
toc-title Title for the table of contents. Table of Contents any Table of Contents, Translating built-in
untitled-label Used as the default document title if the
document does not have a document
title.
Untitled any Translating built-in labels
version-label The label preceding the revnumber in a
converted document’s byline
Version any Revision Number, Date and Remark, T
built-in labels
[1]
[2]
[2]
[2]
12/20/2018 Asciidoctor User Manual
https://asciidoctor.org/docs/user-manual/ 298/315
Attribute
name
Description Default value Allowed
values
Header
only
See also
warning-
caption
Sets the text used to label TIP
admonitions when icons are not
enabled.
Warning any Translating built-in labels
Header and metadata
app-name Application name (for mobile devices).
If set, adds an application-name meta
element inside the HTML document
head.
not set any
author Sets the document’s main author. Can
be set automatically via the author info
line.
not set any Header
authorinitials Sets the author’s initials (e.g., JD).
Derived automatically from the author
attribute by default.
not set any Header
authors Sets the document authors as a comma-
separated list. Can be set automatically
via the author info line. If set, adds an
author meta element inside the HTML
document head.
not set any Metadata
copyright If set, adds a copyright meta element
inside the HTML document head.
not set any Metadata
doctitle Sets the document title. Set
automatically to section title if
document begins with level-0 section.
Based on content. any Document Title
description If set, adds a description meta
element inside the HTML document
head.
not set any Metadata
email Sets the author’s email address. Can be
set automatically via the author info
line. Can be any inline macro, such as a
URL.
not set any Header
favicon Adds a link to a favicon to the HTML
<head>.
not set any Favicon
firstname Sets the author’s first name. Can be set
automatically via the author info line.
not set any Header
front-matter If skip-front-matter is set via the CLI
or API, any YAML-style frontmatter
skimmed from the top of the document
is stored in this attribute.
Front matter
content, if
captured.
any Front Matter Added for Static Site Gen
keywords If set, adds a keywords meta element
inside the HTML document head.
not set any Metadata
lastname Sets the author’s last name. Can be set
automatically via the author info line.
not set any Header
middlename Sets the author’s middle name or
initial. Can be set automatically via the
author info line.
not set any Header
[1]
12/20/2018 Asciidoctor User Manual
https://asciidoctor.org/docs/user-manual/ 299/315
Attribute
name
Description Default value Allowed
values
Header
only
See also
orgname If set, add an <orgname> element with
this value to the DocBook info element.
not set any Metadata
revdate Sets the revision date. Can be set
automatically via the revision info line.
not set any Header
revremark Sets the revision description. Can be set
automatically via the revision info line.
not set any Header
revnumber Sets the revision number. Can be set
automatically via the revision info line.
not set any Header
title Sets the value of the <title> element
in the HTML <head> or main DocBook
<info> of the output document. Also
used as a fallback when the document
title is not specified. Since this is a
reserved attribute that has special
behavior, you should avoid using it for
any other purpose!
not set any Document Title
Section titles and table of contents
idprefix Sets prefix used for auto-generated
section IDs.
_ Valid XML ID
start
character.
Auto-generated IDs
idseparator Sets word separator used in auto-
generated section IDs.
_ Valid XML ID
character.
Auto-generated IDs
leveloffset Pushes the level of subsequent
headings down, to make file inclusion
more useful.
0 (+/-)0–5. (A
leading + or -
makes it
relative).
Partitioning large documents and usin
sectanchors If set, adds an anchor in front of the
section title when the mouse cursor
hovers over it.
not set (No
anchors).
empty Anchors
sectids If set, generates and assigns an ID to
any section that does not have one.
empty (Assigns
section ID if not
specified).
empty Auto-generated IDs
sectlinks Turns section titles into self-referencing
links.
not set empty Links
sectnums If set, numbers sections to depth
specified by sectnumlevels.
not set (Sections
are not
numbered).
empty Numbering
sectnumlevels controls the depth of section
numbering
3 0–5 Numbering depth
title-separator The character used to separate the
main title and subtitle in the document
title.
:any Subtitle Partitioning
toc Switches the table of contents on, and
defines its location.
not set auto, left,
right, macro
or preamble
Table of Contents
toclevels Maximum section level to display. 2 1–5 Table of Contents
[1]
12/20/2018 Asciidoctor User Manual
https://asciidoctor.org/docs/user-manual/ 300/315
Attribute
name
Description Default value Allowed
values
Header
only
See also
fragment Hints to parser that document is a
fragment and it should not enforce
proper section nesting.
not set empty
General content and formatting
asset-uri-
scheme
Controls which protocol is used for
assets hosted on a CDN.
https empty, http
or https
cache-uri If set, cache content read from URIs. not set empty Caching URI Content
data-uri Embed graphics as data-uri elements in
HTML elements so the file is completely
self-contained.
not set (Images
are linked, not
embedded).
empty Managing Images
docinfo Read input from one or more DocBook
info files.
not set Comma-
separated list
of the
following
values:
shared,
private,
shared-head,
private-head,
shared-
footer or
private-
footer
Naming docinfo files
docinfodir The location where docinfo files are
resolved.
The base
directory.
Directory Locating docinfo files
docinfosubs The AsciiDoc substitutions that get
applied to docinfo content.
attributes Comma-
separated list
of
substitution
names. Set
value to
empty or
none to
disable
substitutions.
Attribute substitution in docinfo files
doctype Set the output document type. article article, book,
inline or
manpage
Document Types
eqnums Controls automatic equation
numbering on LaTeX blocks in HTML
output (MathJax). If the value is AMS,
only LaTeX content enclosed in an
\begin{equation}...\end{equation}
container will be numbered. If the
value is all, then all LaTeX blocks will
be numbered.
not set (Equation
numbering is off)
empty (alias
for AMS),
AMS, all or
none
Equations and Formulas, Equation nu
MathJax
(https://docs.mathjax.org/en/v2.5-
latest/tex.html#automatic-equation-numbe
hardbreaks Preserve hard line breaks in the input. not set empty Line Breaks
hide-uri-
scheme
Hides the URI scheme for all raw links. not set empty URLs
[1]
12/20/2018 Asciidoctor User Manual
https://asciidoctor.org/docs/user-manual/ 301/315
Attribute
name
Description Default value Allowed
values
Header
only
See also
linkattrs Parse attributes inside the link macro. not set (Do not
parse).
empty URLs
media Specifies the media type of the output,
which may enable behavior specific to
that media type.
screen screen or
print
nofooter Suppresses output of the footer. not set empty Footer docinfo files
nofootnotes Turn off display of footnotes. not set empty Footnotes
noheader Suppresses output of the header. not set empty Header
outfilesuffix File extension of the output file
(starting with a period).
Determined by
the backend
(.html for
html , .xml for
docbook , etc).
File
extension
Navigating Between Source Files
pagewidth Page width, used to calculate the
absolute width of tables in the DocBook
output.
425 Number
relfileprefix The path prefix to add to relative xrefs. empty Path segment Navigating Between Source Files
show-link-uri Prints the URI of a link after the linked
text. (pdf converter only)
not set empty
showtitle If set, displays an embedded
document’s title. Mutually exclusive
with the notitle attribute.
not set empty Document Title
stem Enables mathematics processing or sets
the processor used.
not set empty
(defaults to
asciimath),
asciimath or
latexmath
Inline Stem Content
tabsize If set, converts tabs to spaces in
verbatim content blocks (e.g., listing,
literal).
not set 0 or more -
webfonts Control whether webfonts are loaded,
and which ones, when using the default
stylesheet. The value populates the
family query string parameter in the
Google Fonts URL.
empty (use
default fonts)
empty or a
Google Fonts
collection
spec
Applying a Theme and issue #410
(https://github.com/asciidoctor/asciidoctor.
xmlns The XML namespace to add to the
DocBook 4.5 document. (The DocBook 5
document always declares a
namespace).
not set empty (alias
for the
DocBook
namespace)
or a valid
XML
namespace.
DocBook
xrefstyle The formatting style to apply to cross
reference text. Introduced in 1.5.6.
not set full, short, or
basic
Customizing the Cross Reference Text
Images and icons
[1]
12/20/2018 Asciidoctor User Manual
https://asciidoctor.org/docs/user-manual/ 302/315
Attribute
name
Description Default value Allowed
values
Header
only
See also
iconfont-cdn Overrides the CDN used to resolve the
Font Awesome stylesheet. Only used
when icons attribute is set to font .
cdnjs URI Icons
iconfont-
name
Overrides the name of the icon font
stylesheet. Only used when icons
attribute is set to font .
font-awesome any Icons
iconfont-
remote
If set, allows use of a CDN for resolving
the icon font. Only used when icons
attribute is set to font .
empty empty Icons
icons Chooses icons instead of text for
admonitions.
not set (image) font or image Icons
iconsdir Where icons are stored. Only used
when icons attribute is set to image .
{imagesdir}/icons
(or ./images/icons
if imagesdir is
not set)
Directory Icons
icontype File type for image icons. Only used
when icons attribute is set to image .
png any, but
typically jpg,
tiff, etc.
Icons
imagesdir Where image files are resolved. not set (Same
directory as
document).
Directory Images
Code highlighting and formatting
coderay-css Controls whether CodeRay uses CSS
classes or inline styles.
class class or style CodeRay
coderay-
linenums-
mode
Sets how CodeRay inserts line numbers
into source listings.
table table or
inline
CodeRay
coderay-
unavailable
If set, tells the processor not to attempt
to load CodeRay.
not set empty CodeRay
highlightjsdir Location of the highlight.js source code
highlighter library.
not set Directory highlight.js
highlightjs-
theme
Sets the name of the theme used by the
highlight.js source code highlighter.
github A style name
recognized
by
highlight.js.
highlight.js
prettifydir Location of the prettify source code
highlighter library.
not set (Uses
CDN).
Directory Syntax Highlighting Source Code
prettify-
theme
Sets the name of the theme used by the
prettify source code highlighter.
prettify A style name
recognized
by prettify.
Syntax Highlighting Source Code
prewrap Wrap wide code listings. Sets the
default behavior only; you can still
switch off wrapping on specific listings.
empty (Code
listing will wrap
long lines, not
scroll).
empty To Wrap or to Scroll
pygments-css Controls whether Pygments uses CSS
classes or inline styles.
class class or style Pygments
[1]
12/20/2018 Asciidoctor User Manual
https://asciidoctor.org/docs/user-manual/ 303/315
Attribute
name
Description Default value Allowed
values
Header
only
See also
pygments-
linenums-
mode
Sets how Pygments inserts line
numbers into source listings.
table table or
inline
Pygments
pygments-
style
Sets the name of the style used by the
Pygments source code highlighter
default A style name
recognized
by Pygments.
Pygments
pygments-
unavailable
If set, tells the processor not to attempt
to load Pygments.
not set empty Pygments
source-
highlighter
Source code highlighter to use. not set coderay,
highlightjs,
prettify or
pygments
Syntax Highlighting Source Code
source-indent Normalize block indentation in code
listings.
not set
(Indentation is
not modified).
Number Normalize Block Indentation
source-
language
Set the default language for source
code listings.
not set Code
language
name in
lowercase.
Syntax Highlighting Source Code
source-
linenums-
option
Turns on line numbers option by
default for source code listings.
Introduced in 1.5.6.
not set empty Syntax Highlighting Source Code
HTML styling
copycss If set, copy the CSS files to the output. empty (File is
copied if
linkcss is set).
Empty or the
location of
the custom
stylesheet (if
used)
Applying a Theme
css-signature If set, assign the value to the id
attribute of the <body> element
(HTML only). The preferred approach
is to assign an ID to the document title.
not set Valid XML ID
linkcss If set, link to the stylesheet instead of
embedding it. Cannot be unset in
SECURE safe mode.
not set (when
safe mode <
SECURE)
set (when safe
mode is SECURE)
empty Styling the HTML with CSS
max-width Constrain the maximum width of the
document body. Not recommended.
Use custom CSS instead.
not set CSS length
(e.g. 55em,
12cm, etc)
stylesdir Location for resolving CSS stylesheets. . (Same directory
as document).
Directory Creating a Theme
stylesheet Name of a CSS stylesheet to replace the
default one.
not set (The
default stylesheet
is used).
File name Applying a Theme
toc-class The CSS class on the table of contents
container.
toc Valid CSS
class name
Table of Contents
[1]
12/20/2018 Asciidoctor User Manual
https://asciidoctor.org/docs/user-manual/ 304/315
Attribute
name
Description Default value Allowed
values
Header
only
See also
Manpage attributes (relevant only when using the manpage doctype and/or converter)
mantitle Metadata for manpage output. Based on content. any Man Pages
manvolnum Metadata for manpage output. Based on content. any Man Pages
manname Metadata for manpage output. Based on content. any Man Pages
manpurpose Metadata for manpage output. Based on content. any Man Pages
man-linkstyle Style the links in the manpage output. blue R <> Link format
sequence
Man Pages
mansource The source (e.g., application and
version) to which the man page
pertains.
not set any Man Pages
manmanual Manual name displayed in the man
page footer.
not set any Man Pages
Secure attributes (can only be set from the command line or API, typically for security reasons)
allow-uri-read If set, allows data to be read from URIs
(via include directive, image macro
when embedding images, etc.).
not set empty CLI or
API
Include Content from a URI
max-
attribute-
value-size
Limits the maximum size (in bytes) of a
resolved attribute value. Since
attributes can reference other
attributes, it would be possible to
create an output document
disproportionately larger than the
input document without this limit in
place.
4096 (secure
mode), not set
(other modes)
0 or greater CLI or
API
max-include-
depth
Safety feature to curtail infinite include
loops and to limit the opportunity to
exploit nested includes to compound
the size of the output document.
64 0 or greater CLI or
API
Include Directive
skip-front-
matter
If set, consume YAML-style frontmatter
at the top of the document and store it
in the front-matter attribute.
not set empty CLI or
API
Front Matter Added for Static Site Gen
The default value isn’t necessarily the value you will get by entering {name} . It may be the fallback value which Asciidoctor
uses if the attribute is not defined. The effect is the same either way.
The -number attributes are created and managed automatically by Asciidoctor for numbered blocks. They are only used if the
corresponding -caption attribute is set (e.g., listing-caption ) and the block has a title. In the current version of Asciidoctor,
setting the -number attributes will influence the number used for subsequent numbered blocks of that type. However, you
should not rely on this behavior as it may change in future versions.
A.3. Predened Attributes for Character Replacements
Predefined attributes for character replacements
Attribute name Replacement text Appearance
blank nothing
empty nothing
sp single space
[1]
[1]
[2]
[1][2][3]
12/20/2018 Asciidoctor User Manual
https://asciidoctor.org/docs/user-manual/ 305/315
Attribute name Replacement text Appearance
nbsp  
zwsp ​
wj ⁠
apos ' '
quot " "
lsquo ‘ ‘
rsquo ’ ’
ldquo “ “
rdquo ” ”
deg ° °
plus + +
brvbar ¦ ¦
vbar ||
amp &&
lt <<
gt >>
startsb [[
endsb ]]
caret ^^
asterisk **
tilde ~~
backslash \\
backtick ``
two-colons :: ::
two-semicolons ;; ;;
cpp C++ C++
Some replacements are Unicode characters, whereas others are numeric character references (e.g., "). These character
references are used whenever the use of the Unicode character could interfere with the AsciiDoc syntax or confuse the renderer
(i.e., the browser). It’s up to the converter to transform the reference into something the renderer understands (something both
the man page and PDF converter handle).
Asciidoctor does not prevent you from reassigning predefined attributes. However, it’s best to treat them as read-only unless
the output format requires the use of a different encoding scheme. These attributes are an effective tool for decoupling content
and presentation.
Asciidoctor allows you to use any of the named character references (aka named entities) defined in HTML (e.g., €
resolves to €). However, using named character references can cause problems when generating non-HTML output such as PDF
because the lookup table needed to resolve these names may not be defined. Our recommendation is avoid using named
[4]
[5]
[1]
[2]
[3]
12/20/2018 Asciidoctor User Manual
https://asciidoctor.org/docs/user-manual/ 306/315
character references— with the exception of those defined in XML (i.e., lt, gt, amp, quot and apos). Instead, use numeric character
references (e.g., €).
The Zero Width Space (ZWSP) is a code point in Unicode that shows where a long word can be split if necessary.
The word joiner (WJ) is a code point in Unicode that prevents a line break at its position.
[4]
[5]
12/20/2018 Asciidoctor User Manual
https://asciidoctor.org/docs/user-manual/ 307/315
Appendix B: CLI Options
B.1. Security Settings
-B, --base-dir=DIR
Base directory containing the document and resources. Defaults to the directory containing the source file, or the working
directory if the source is read from a stream. When combined with the safe mode setting, can be used to chroot the execution
of the program.
-S, --safe-mode=SAFE_MODE
Set safe mode level: unsafe, safe, server or secure. Disables potentially dangerous macros in source files, such as include::[] .
If not set, the safe mode level defaults to unsafe when Asciidoctor is invoked using this script.
--safe
Set safe mode level to safe. Enables include directives, but prevents access to ancestor paths of source file. Provided for
compatibility with the asciidoc command. If not set, the safe mode level defaults to unsafe when Asciidoctor is invoked using
this script.
B.2. Document Settings
-a, --attribute=ATTRIBUTE
Define, override or delete a document attribute. Command-line attributes take precedence over attributes defined in the source
file unless the value ends with @.
ATTRIBUTE is normally formatted as a key-value pair, in the form NAME=VALUE. Alternate acceptable forms are NAME (where
the VALUE defaults to an empty string), NAME! (unassigns the NAME attribute) and NAME=VALUE@ (where VALUE does not
override value of NAME attribute if it’s already defined in the source document). Values containing spaces should be enclosed
in quotes.
This option may be specified more than once.
-b, --backend=BACKEND
Backend output file format: html5, docbook5, docbook45 and manpage are supported out of the box. You can also use the
backend alias names html (aliased to html5) or docbook (aliased to docbook5). Other values can be passed, but if Asciidoctor
cannot resolve the backend to a converter, it will fail. Defaults to html5.
-d, --doctype=DOCTYPE
Document type: article, book, manpage or inline. Sets the root element when using the docbook backend and the style class on
the HTML body element when using the html backend. The book document type allows multiple level-0 section titles in a single
document. The manpage document type enables parsing of metadata necessary to produce a man page. The inline document
type allows the content of a single paragraph to be formatted and returned without wrapping it in a containing element.
Defaults to article.
B.3. Document Conversion
-D, --destination-dir=DIR
Destination output directory. Defaults to the directory containing the source file, or the working directory if the source is read
from a stream. If specified, the directory is resolved relative to the working directory.
-E, --template-engine=NAME
Template engine to use for the custom converter templates. The gem with the same name as the engine will be loaded
automatically. This name is also used to build the full path to the custom converter templates. If a template engine is not
specified, it will be auto-detected based on the file extension of the custom converter templates found.
-e, --eruby
Specifies the eRuby implementation to use for executing the custom converter templates written in ERB. Supported values are
erb and erubis. Defaults to erb.
-I, --load-path=DIRECTORY
Add the specified directory to the load path, so that -r can load extensions from outside the default Ruby load path. This option
may be specified more than once.
12/20/2018 Asciidoctor User Manual
https://asciidoctor.org/docs/user-manual/ 308/315
-n, --section-numbers
Auto-number section titles. Synonym for --attribute sectnums.
-o, --out-file=OUT_FILE
Write output to file OUT_FILE. Defaults to the base name of the input file suffixed with backend extension. The file is resolved
relative to the working directory. If the input is read from standard input or a named pipe (fifo), then the output file defaults to
stdout. If OUT_FILE is -, then the output file is written to standard output.
-R, --source-dir=DIR
Source directory. Currently only used if the destination directory is also specified. Used to preserve the directory structure of
files converted within this directory in the destination directory. If specified, the directory is resolved relative to the working
directory.
-r, --require=LIBRARY
Require the specified library before executing the processor, using the standard Ruby require. This option may be specified
more than once.
-s, --no-header-footer
Output an embeddable document, which excludes the header, the footer, and everything outside the body of the document.
This option is useful for producing documents that can be inserted into an external template.
-T, --template-dir=DIR
A directory containing custom converter templates that override one or more templates from the built-in set. (requires tilt gem)
If there is a subfolder that matches the engine name (if specified), that folder is appended to the template directory path.
Similarly, if there is a subfolder in the resulting template directory that matches the name of the backend, that folder is
appended to the template directory path.
This option may be specified more than once. Matching templates found in subsequent directories override ones previously
discovered.
B.4. Processing Information
--failure-level=LEVEL
The minimum logging level that triggers a non-zero exit code (failure). If this option is not set (default: FATAL), the program
exits with a status code zero even if warnings or errors have been logged.
-q, --quiet
Silence warnings.
--trace
Include backtrace information on errors. Not enabled by default.
-v, --verbose
Verbosely print processing information and configuration file checks to stderr.
-t, --timings
Display timings information (time to read, parse and convert).
B.5. Program Information
-h, --help [TOPIC]
Print the help message. Show the command usage if TOPIC is not specified (or not recognized). Dump the Asciidoctor man page
(in troff/groff format) if TOPIC is manpage.
-V, --version
Print program version number.
-v can also be used if no other flags or arguments are present.
12/20/2018 Asciidoctor User Manual
https://asciidoctor.org/docs/user-manual/ 309/315
Appendix C: Ruby API Options
Ruby API options
Name Description Default value Allowed values CLI equivalent
:attributes Sets additional document
attributes, which override
equivalently-named
attributes defined in the
document unless the
name or value ends with
@. When using the Hash
form, a nil value unsets
the attribute and a false
value soft unsets the
attribute.
not set Any number of built-in or
user-defined attributes in
one of the following
formats:
Hash:
{'name'=>'value'}
Array:
['name=value']
String:
'name=value'
-a , --
attributes
:backend Selects the converter to
use (as registered with
this keyword).
html5 html5, docbook5,
docbook45, manpage, or
any backend registered
through an active
converter
-b , --backend
:base_dir Sets the base (aka
working) directory
containing the document
and resources.
The directory
of the source
file, or the
working
directory if the
source is read
from a stream.
file path -B , --base-dir
:catalog_assets If true, tells the parser to
capture images and links
in the reference table.
(Normally only IDs,
footnotes and indexterms
are included). The
reference table is
available via the
references property on
the document AST object.
(Experimental).
false boolean n/a
:converter Specifies a user-supplied
Asciidoctor::Converter
instance, used in place of
the converter that is
automatically resolved
from the backend value.
not set Asciidoctor::Converter
instance
n/a (Can be
emulated using a
combination of -
r and -b ).
:doctype Sets the document type. article article, book, manpage,
inline
-d , --doctype
:eruby Specifies the eRuby
implementation to use for
executing the converter
templates written in ERB.
erb erb, erubis -e , --eruby
12/20/2018 Asciidoctor User Manual
https://asciidoctor.org/docs/user-manual/ 310/315
Name Description Default value Allowed values CLI equivalent
:extensions A Ruby block that
registers (and possibly
defines) Asciidoctor
extensions for this
instance of the processor.
not set A Ruby block that
conforms to the
Asciidoctor extensions API
(the same code that would
be passed to the
Extensions.register
method).
n/a (Can be
emulated using -
r).
:extensions_registry Overrides the extensions
registry instance. Instead
of providing a Ruby block
containing extensions to
register, this option lets
you replace the extension
registry itself, giving you
complete control over
how extensions are
registered for this
processor.
not set Extensions::Registry
instance
n/a
:header_footer If true, add the document
header and footer (i.e.,
framing) around the body
content in the output.
NOTE: The default value
for this option is opposite
of the default value for
the CLI.
false boolean -s , --no-
header-footer
:mkdirs If true, the processor will
create the necessary
output directories if they
don’t yet exist.
false boolean n/a (Implicitly
enabled).
:parse If true, the source is
parsed eagerly (i.e., as
soon as the source is
passed to the load or
load_file API). If false,
parsing is deferred until
the parse method is
explicitly invoked.
true boolean n/a
:safe Sets the safe mode. :secure :unsafe, :safe, :server,
:secure
-S , --safe-
mode
:sourcemap Keeps track of the file and
line number for each
parsed block. (Useful for
tooling applications
where the association
between the converted
output and the source file
is important).
false boolean n/a
12/20/2018 Asciidoctor User Manual
https://asciidoctor.org/docs/user-manual/ 311/315
Name Description Default value Allowed values CLI equivalent
:template_cache If true, enables the built-in
cache used by the
template converter when
reading the source of
template files. Only
relevant if the
:template_dirs option is
specified.
true boolean n/a
:template_dir Specifies a directory of
Tilt-compatible templates
to be used instead of the
default built-in templates.
Deprecated. Please use
:template_dirs
instead.
not set file path -T , --
template-dir
:template_dirs An array of directories
containing Tilt-compatible
converter templates to be
used instead of the default
built-in templates.
not set An array of file paths -T , --
template-dir
:template_engine Template engine to use for
the custom converter
templates. The gem with
the same name as the
engine will be loaded
automatically. This name
is also used to build the
full path to the custom
converter templates.
auto
(Set based on
the file
extension of
the custom
converter
templates
found).
Template engine name
(e.g., slim, haml, erb, etc.)
-E , --
template-
engine
:template_engine_options Low-level options passed
directly to the template
engine.
not set A nested Hash of options
with the template engine
name as the top-level key
and the option name as
the second-level key.
n/a
:timings Capture time taken to
read, parse, and convert
document. Internal use
only.
not set Asciidoctor::Timings
instance
-t , --timings
:to_file The name of the output
file to write, or true to use
the default output file
(docname +
outfilesuffix ).
not set true, file path -o , --out-file
:to_dir Destination directory for
output file(s), relative to
base_dir.
The directory
containing the
source file, or
the working
directory if the
source is read
from a stream.
file path -D , --
destination-
dir
12/20/2018 Asciidoctor User Manual
https://asciidoctor.org/docs/user-manual/ 312/315
Appendix D: Application Messages
All warning, error, and failure messages emitted by the Asciidoctor CLI (i.e., asciidoctor ) are listed in the table below. These
messages are written to the console via stderr (i.e., standard error). Most messages also apply to the API, though keep in mind
they’re written directly to stderr.
Placeholders
<docname>
represents the basename of the source file being processed (e.g., sample.adoc ).
<file>
represents a path to the input file or other referenced file.
<uri>
represents a URI being referenced.
<x> or <y>
placeholders for other contextual information in the message.
Categories
ERROR
Errors do not stop conversion, but the output document will almost certainly be wrong.
FAILURE
Failures are fatal; no output document will be produced.
WARNING
Warnings do not stop conversion, but they indicate possible problems, and the output may not be what you were expecting.
List of Application Messages
Category Message Cause See also
ERROR input file <file> missing or cannot be read Check that the file exists and that the
filename is not misspelled.
Using the Command
Line Interface
ERROR include file has illegal reference to ancestor
of jail, auto-recovering
The safe mode is restricting access to
an include file outside of the base
directory.
Running Asciidoctor
Securely
ERROR input file and output file cannot be the same:
<file>
Choose a different output directory
or filename.
ERROR partintro block can only be used when
doctype is book and it's a child of a part
section. Excluding block content.
Invalid book document structure. Book Parts and
Chapters
ERROR unmatched macro: endif::<x>[] endif::[] with no unclosed
preceding ifdef::<x>[] .
ifdef Directive
ERROR <docname> dropping cell because it exceeds
specified number of columns
Tables
ERROR <docname> illegal block content outside of
partintro block
Invalid book document structure. Book Parts and
Chapters
ERROR <docname> invalid part, must have at least
one section (e.g., chapter, appendix, etc.)
Invalid book document structure. Book Parts and
Chapters
ERROR <docname> malformed manpage title Invalid man page document
structure.
Man Pages
12/20/2018 Asciidoctor User Manual
https://asciidoctor.org/docs/user-manual/ 313/315
Category Message Cause See also
ERROR <docname> malformed name section body Invalid man page document
structure.
Man Pages
ERROR <docname> maximum include depth of 64
exceeded
Does your file include itself, directly
or indirectly?
ERROR <docname> mismatched macro: endif::<x>[],
expected endif::<y>[]
ifdef/endif blocks must be strictly
nested.
ifdef Directive
ERROR <docname> name section expected Invalid man page document
structure.
Man Pages
ERROR <docname> name section title must be at
level 1
Invalid man page document
structure.
Man Pages
ERROR <docname> only book doctypes can contain
level 0 sections
Illegal use of a level-0 section when
doctype is not book.
Sections
ERROR <docname> table missing leading separator,
recovering automatically
Check for missing cell separator
characters at the start of the line.
Tables
FAILED missing converter for backend '<x>'.
Processing aborted. (RuntimeError)
You used -b with an invalid or
missing backend.
FAILED 'tilt' could not be loaded You must have the tilt gem installed
(gem install tilt) to use custom
backend templates
WARNING abstract block cannot be used in a document
without a title when doctype is book.
Excluding block content.
Invalid book document structure. Abstract
WARNING cannot retrieve contents of <x> at URI: <uri>
(allow-uri-read attribute not enabled)
Reading from a URI is only allowed
in certain safe modes and the allow-
uri-read attribute must be passed to
the application.
Include Content from
a URI
WARNING could not retrieve contents of <x> at URI:
<uri>
Web address not found.
WARNING could not retrieve image data from URI: <uri> Web address not found. Only occurs
with allow-uri-read and data-
uri . Check the URI.
Include Images by
Full URL
WARNING dropping line containing reference to missing
attribute: <x>
An attribute cannot be resolved and
the attribute-missing attribute is
set to drop-line .
[catch-a-missing-or-
undefined-attribute]
WARNING file does not exist or cannot be read: <file> You specified a stylesheet (-a
stylesheet=<file>) but <file> does
not exist or is not readable.
WARNING gem 'thread_safe' is not installed. This gem is
recommended when registering custom
converters.
You have registered a custom
converter, and you have not installed
the thread_safe gem.
WARNING gem 'thread_safe' is not installed. This gem is
recommended when using custom backend
templates.
You are using custom templates (-T
<template_dir>), but you have not
installed the thread_safe gem.
WARNING image to embed not found or not readable:
<file>
You used :data-uri: but the file
could not be found.
Managing Images
12/20/2018 Asciidoctor User Manual
https://asciidoctor.org/docs/user-manual/ 314/315
Category Message Cause See also
WARNING include file not readable: <file> You do not have permission to access
the file.
AsciiDoc vs non-
AsciiDoc files
WARNING input path <file> is a <x>, not a file The path is not a file (perhaps it is a
socket or a block device).
AsciiDoc vs non-
AsciiDoc files
WARNING optional gem 'asciimath' is not installed.
Functionality disabled.
asciimath is one of the libraries used
for equations.
Equations and
Formulas
WARNING optional gem 'coderay' is not installed.
Functionality disabled.
CodeRay is used for source code
highlighting.
CodeRay
WARNING skipping reference to missing attribute: <x> An attribute cannot be resolved and
the attribute-missing attribute is
set to skip .
[catch-a-missing-or-
undefined-attribute]
WARNING tables must have at least one body row Tables
WARNING tag '<x>' not found in include file: <file> You tried to include by tagged region,
but the included document does not
have that tag.
Select Portions of a
Document to Include
WARNING <docname>: id assigned to <type> already in
use: <id>
<id> is a duplicate ID, meaning it has
already been assigned to a node of
<type> (e.g., section, block, anchor). If
you don’t see the problem in
<docname>, check that the duplicate
ID isn’t coming from a file which is
being included.
WARNING <docname> callout list item index: expected
<x> got <y>
Callouts are expected to be in
numerical order, just like any
ordered list.
Callouts
WARNING <docname> include <x> not readable: <y> If <y> is a file, do you have read
permissions for it? If it is a URI and -
a allow-uri-read is set, does it
exist?
WARNING <docname> include file not found: <file> Probably a typo or missing file. If not,
make sure you understand the
search process.
Include Directive,
File resolution
WARNING <docname> invalid empty <x> detected in
style attribute
The first positional attribute in the
block attributes could not be parsed.
Options
WARNING <docname> invalid style for <x> block: <y> You have added a custom style to a
block, but you haven’t registered a
custom block extension to handle it.
WARNING <docname> invalid style for paragraph: <x> You have a line [xxx] before a
paragraph, but xxx isn’t one of the
built-in styles.
Style
WARNING <docname> list item index: expected <x>, got
<y>
You gave explicit numbers on an
ordered list, but they were not
sequential. Asciidoctor renumbers
them for you, and gives this warning.
Ordered Lists
WARNING <docname> multiple ids detected in style
attribute
Multiple IDs cannot be specified in
the block style (e.g., [#cat#dog]).
Id
12/20/2018 Asciidoctor User Manual
https://asciidoctor.org/docs/user-manual/ 315/315
Category Message Cause See also
WARNING <docname> no callouts refer to list item <x> The callout is missing or not
recognized. In source listings, is the
callout the last thing on the line?
Callouts
WARNING <docname> section title out of sequence Invalid document structure. Check
section levels.
Sections
1. See https://www.w3.org/TR/2014/REC-html5-20141028/embedded-content-0.html#dimension-attributes
Last updated 2018-12-20 03:15:25 UTC
