Asciidoctor User Manual
User Manual:
Open the PDF directly: View PDF 
.
Page Count: 315
| Download | |
| Open PDF In Browser | View PDF |
12/20/2018
Asciidoctor User Manual
Asciidoctor User Manual
Sarah White
@graphitefriction (https://github.com/graphitefriction)
Dan Allen
@mojavelinux (https://github.com/mojavelinux)
https://asciidoctor.org/docs/user-manual/
1/315
12/20/2018
Asciidoctor User Manual
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 Bene ts
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
https://asciidoctor.org/docs/user-manual/
2/315
12/20/2018
Asciidoctor User Manual
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. De ning 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
https://asciidoctor.org/docs/user-manual/
3/315
12/20/2018
Asciidoctor User Manual
28.2. Processing
28.3. File resolution
28.4. Partitioning large documents and using levelo set
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
https://asciidoctor.org/docs/user-manual/
4/315
12/20/2018
Asciidoctor User Manual
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
https://asciidoctor.org/docs/user-manual/
5/315
12/20/2018
Asciidoctor User Manual
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
https://asciidoctor.org/docs/user-manual/
6/315
12/20/2018
Asciidoctor User Manual
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 Con uence 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. Prede ned 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
https://asciidoctor.org/docs/user-manual/
7/315
12/20/2018
Asciidoctor User Manual
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.
https://asciidoctor.org/docs/user-manual/
8/315
12/20/2018
Asciidoctor User Manual
Introduction to Asciidoctor
https://asciidoctor.org/docs/user-manual/
9/315
12/20/2018
Asciidoctor User Manual
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 Bene ts
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
https://asciidoctor.org/docs/user-manual/
10/315
12/20/2018
Asciidoctor User Manual
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
https://asciidoctor.org/docs/user-manual/
11/315
12/20/2018
Asciidoctor User Manual
Language
Markdown
AsciiDoc
Feature
Bold
(constrained)
Bold
(unconstrained)
Italic
(constrained)
Italic
**bold**
**b**old
*italic*
MARKDOWN
MARKDOWN
MARKDOWN
n/a
(constrained)
Monospace
(unconstrained)
Link with label
Relative link
File link
Cross reference
`monospace`
`m`onospace
[AsciiDoc](http://asciidoc.org)
[user guide](user-guide.html)
MARKDOWN
MARKDOWN
MARKDOWN
MARKDOWN
MARKDOWN
[get the PDF]({% raw %}{{ site.url }}{% endraw
%}/assets/mydoc.pdf)
See link:#_usage[Usage].
MARKDOWN
Usage
Block ID /
anchor
Inline anchor
Inline image w/
alt text
Block image w/
heading*
Blockquote*
_italic_
Usage
`monospace`
``m``onospace
http://asciidoc.org[AsciiDoc]
link:user-guide.html[user guide]
xref:user-guide.adoc[user guide]
MARKDOWN
n/a
MARKDOWN
n/a
> Quoted text.
>
> Another paragraph in quote.
ASCIIDOC
ASCIIDOC
ASCIIDOC
ASCIIDOC
ASCIIDOC
ASCIIDOC
ASCIIDOC
See <<_usage>>.
[#usage]
== Usage
image:logo.png[Logo]
image::logo.png[Logo]
## Heading 2
ASCIIDOC
link:{site-url}/assets/mydoc.pdf[get the PDF]
. [[step-1]]Download the software
ASCIIDOC
ASCIIDOC
== Usage
alt text
Section
**b**old
__i__talic
(unconstrained)
Monospace
*bold*
MARKDOWN
MARKDOWN
== Heading 2
____
Quoted text.
ASCIIDOC
ASCIIDOC
ASCIIDOC
ASCIIDOC
ASCIIDOC
ASCIIDOC
Another paragraph in quote.
____
Literal block
$ gem install asciidoctor
MARKDOWN
Indented (by 1 or more spaces)
$ gem install asciidoctor
ASCIIDOC
Delimited
....
$ gem install asciidoctor
....
https://asciidoctor.org/docs/user-manual/
ASCIIDOC
12/315
12/20/2018
Asciidoctor User Manual
Language
Markdown
AsciiDoc
Feature
Code block*
Unordered list
Ordered list
Thematic break
(aka horizontal
rule)*
```java
public class Person {
private String name;
public Person(String name) {
this.name = name;
}
}
```
* apples
* orange
* temple
* navel
* bananas
1. first
2. second
3. third
***
MARKDOWN
MARKDOWN
MARKDOWN
MARKDOWN
[source,java]
---public class Person {
private String name;
public Person(String name) {
this.name = name;
}
}
----
ASCIIDOC
ASCIIDOC
* apples
* oranges
** temple
** navel
* bananas
ASCIIDOC
. first
. second
. third
ASCIIDOC
'''
* * *
--- - ___
_ _ _
Typographic
Enabled through an extension switch, but offer little
quotes (aka
control in how they are applied.
“smart quotes”)
Document
header
Slapped on as “front matter”
--layout: docs
title: Writing posts
prev_section: defining-frontmatter
next_section: creating-pages
permalink: /docs/writing-posts/
---
Admonitions
n/a
Sidebars
n/a
ASCIIDOC
The `'90s popularized a new form of music known
as "`grunge`" rock.
It's influence extended well beyond music.
Native support!
MARKDOWN
= Writing posts
:awestruct-layout: base
:showtitle:
:prev_section: defining-frontmatter
:next_section: creating-pages
ASCIIDOC
ASCIIDOC
TIP: You can add line numbers to source
listings by adding the word `numbered` in the
attribute list after the language name.
Lightweight Markup
Writing languages that let you type less and
express more.
Block titles
n/a
Grocery list
Milk
Eggs
Bread
Includes
n/a
https://asciidoctor.org/docs/user-manual/
include::intro.adoc[]
ASCIIDOC
13/315
12/20/2018
Asciidoctor User Manual
Language
Markdown
AsciiDoc
Feature
URI reference
[home]: https://example.org "Home"
MARKDOWN
Go [home].
Custom CSS
n/a
classes
:home: https://example.org
ASCIIDOC
Go {home}[Home].
[.path]_Gemfile_
ASCIIDOC
* 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/)
https://asciidoctor.org/docs/user-manual/
14/315
12/20/2018
Asciidoctor User Manual
Quick Starts
https://asciidoctor.org/docs/user-manual/
15/315
12/20/2018
Asciidoctor User Manual
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
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 .
https://asciidoctor.org/docs/user-manual/
16/315
12/20/2018
Asciidoctor User Manual
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:
require 'asciidoctor'
RUBY
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:
doc = Asciidoctor.load_file 'mysample.adoc'
RUBY
You can get information about the document:
puts doc.doctitle
puts doc.attributes
RUBY
More than likely, you will want to convert the document. To convert a file containing AsciiDoc markup to HTML 5, use:
Asciidoctor.convert_file 'mysample.adoc'
RUBY
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' :
Asciidoctor.convert_file 'mysample.adoc', backend: 'docbook'
RUBY
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.
https://asciidoctor.org/docs/user-manual/
17/315
12/20/2018
Asciidoctor User Manual
Getting Started
https://asciidoctor.org/docs/user-manual/
18/315
12/20/2018
Asciidoctor User Manual
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.
https://asciidoctor.org/docs/user-manual/
19/315
12/20/2018
Asciidoctor User Manual
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
https://asciidoctor.org/docs/user-manual/
20/315
12/20/2018
Asciidoctor User Manual
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.
https://asciidoctor.org/docs/user-manual/
21/315
12/20/2018
Asciidoctor User Manual
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.
https://asciidoctor.org/docs/user-manual/
22/315
12/20/2018
Asciidoctor User Manual
7. Extensions and Integrations
See Extensions.
https://asciidoctor.org/docs/user-manual/
23/315
12/20/2018
Asciidoctor User Manual
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.
https://asciidoctor.org/docs/user-manual/
24/315
12/20/2018
Asciidoctor User Manual
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
https://asciidoctor.org/docs/user-manual/
25/315
12/20/2018
Asciidoctor User Manual
Special characters
Special words
Attribute references
Inline macros
https://asciidoctor.org/docs/user-manual/
26/315
12/20/2018
Asciidoctor User Manual
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
ASCIIDOC
That is *strong* stuff!
to format a sequence of words,
When there are multiple words
ASCIIDOC
That is *really strong* stuff!
or to format a word adjacent to punctuation, like an exclamation mark.
When the word is adjacent to punctuation
ASCIIDOC
This stuff sure is *strong*!
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
ASCIIDOC
She spells her name with an "`h`", as in Sara**h**.
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__
Sarah
Unconstrained
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.
https://asciidoctor.org/docs/user-manual/
27/315
12/20/2018
Asciidoctor User Manual
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-5
Constrained
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
"```endpoints```"
ASCIIDOC
You might start with the following syntax:
"`endpoints`"
ASCIIDOC
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.
"``endpoints``"
ASCIIDOC
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.
"```endpoints```"
ASCIIDOC
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
"[.code]``endpoints``" or \"``endpoints``"
ASCIIDOC
Another example is a possessive, monospaced phrase that ends in an “s”. In this case, you must switch the monospaced phrase to
unconstrained formatting.
The ``class```' static methods make it easy to operate on files and directories.
ASCIIDOC
Rendered possessive, monospaced phrase
https://asciidoctor.org/docs/user-manual/
28/315
12/20/2018
Asciidoctor User Manual
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.
The `class`’ static methods make it easy to operate on files and directories.
ASCIIDOC
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:
The __kernel qualifier can be used with the __attribute__ keyword...
#`CB###2`# and #`CB###3`#
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:
:dbl_: __
:3H: ###
The {dbl_}kernel qualifier can be used with the {dbl_}attribute{dbl_} keyword...
#`CB{3H}2`# and #`CB{3H}3`#
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:
The +__kernel+ qualifier can be used with the +__attribute__+ keyword...
#`+CB###2+`# and #`+CB###3+`#
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.
https://asciidoctor.org/docs/user-manual/
29/315
12/20/2018
Asciidoctor User Manual
The pass:c[__kernel] qualifier can be used with the pass:c[__attribute__] keyword...
#`pass:c[CB###2]`# and #`pass:c[CB###3]`#
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.
https://asciidoctor.org/docs/user-manual/
30/315
12/20/2018
Asciidoctor User Manual
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
https://asciidoctor.org/docs/user-manual/
31/315
12/20/2018
Asciidoctor User Manual
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:
= Document Title
:imagesdir: new/path/to/images
ASCIIDOC
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:
https://asciidoctor.org/docs/user-manual/
32/315
12/20/2018
Asciidoctor User Manual
!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
:name: value
ASCIIDOC
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
ASCIIDOC
:name:
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
:!name:
ASCIIDOC
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)
https://asciidoctor.org/docs/user-manual/
33/315
12/20/2018
Asciidoctor User Manual
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:
:toc:
ASCIIDOC
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.
:toc: right
ASCIIDOC
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
:imagesdir: ./images
:iconsdir: ./icons
:stylesdir: ./styles
ASCIIDOC
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
:url-fedpkg: https://apps.fedoraproject.org/packages/rubygem-asciidoctor
ASCIIDOC
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
ASCIIDOC
Did you know there's an https://apps.fedoraproject.org/packages/rubygem-asciidoctor[Asciidoctor package for Fedora]?
https://asciidoctor.org/docs/user-manual/
34/315
12/20/2018
Asciidoctor User Manual
We can replace the target side of the link macro with a reference to our attribute.
url-fedpkg attribute usage example
Did you know there's an {url-fedpkg}[Asciidoctor package for Fedora]?
ASCIIDOC
To save even more typing, you can store the whole link in an attribute value.
Link attribute entry
:link-fedpkg: https://apps.fedoraproject.org/packages/rubygem-asciidoctor[Asciidoctor package for Fedora]
ASCIIDOC
Now you insert this link anywhere in the document using an attribute reference.
link-fedpkg attribute usage example
Did you know there's an {link-fedpkg}?
ASCIIDOC
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
:link-fedpkg: pass:m[https://apps.fedoraproject.org/packages/rubygem-asciidoctor[Asciidoctor package for Fedora]]
ASCIIDOC
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:
:cols: pass:[.>2,.>4]
ASCIIDOC
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:
:app-name: pass:quotes[MyApp^2^]
ASCIIDOC
Internally, the value is stored as MyApp2 . You can inspect the value stored in an attribute using this trick:
[subs=attributes+]
---{app-name}
----
You can also specify the substitution using the single-character alias, q .
https://asciidoctor.org/docs/user-manual/
35/315
12/20/2018
Asciidoctor User Manual
:app-name: pass:q[MyApp^2^]
ASCIIDOC
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:
:app-name: MyApp^2^
ASCIIDOC
[subs="specialchars,attributes,quotes,replacements,macros,post_replacements"]
The application is called {app-name}.
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
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
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)
: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
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
:haiku: Write your docs in text, + \
AsciiDoc makes it easy, + \
Now get back to work!
ASCIIDOC
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:
https://asciidoctor.org/docs/user-manual/
36/315
12/20/2018
Asciidoctor User Manual
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.
image::sunset.jpg[Sunset,300,400]
ASCIIDOC
image::sunset.jpg[alt=Sunset,width=300,height=400]
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.
https://asciidoctor.org/docs/user-manual/
37/315
12/20/2018
Asciidoctor User Manual
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= .
ASCIIDOC
[#goals]
* Goal 1
* Goal 2
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:
[quote#roads, Dr. Emmett Brown]
____
Roads? Where we're going, we don't need roads.
____
ASCIIDOC
The order of ID and role values in the shorthand syntax does not matter.
Inline Assignment
https://asciidoctor.org/docs/user-manual/
38/315
12/20/2018
Asciidoctor User Manual
The id ( # ) shorthand can be used on inline quoted text.
Quoted text block with id assignment using Asciidoctor shorthand
[#free_the_world]*free the world*
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= .
ASCIIDOC
[.summary]
* Review 1
* Review 2
[role="summary"]
* Review 1
* Review 2
ASCIIDOC
To specify multiple roles using the shorthand syntax, separate them by dots.
[.summary.incremental]
* Review 1
* Review 2
[role="summary,incremental"]
* Review 1
* Review 2
ASCIIDOC
ASCIIDOC
Inline Assignment
The role ( . ) shorthand can be used on inline quoted text.
Quoted text with role assignments using traditional AsciiDoc syntax
[big goal]*free the world*
ASCIIDOC
Quoted text with role assignments using Asciidoctor shorthand
[.big.goal]*free the world*
ASCIIDOC
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:
[.rolename]`monospace text`
ASCIIDOC
the following HTML is produced:
monospace text
HTML
Using the shorthand notation, an id (i.e., anchor) can also be specified:
https://asciidoctor.org/docs/user-manual/
39/315
12/20/2018
Asciidoctor User Manual
[#idname.rolename]`monospace text`
ASCIIDOC
which produces:
monospace text
HTML
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=
3. Specifying the value with options= .
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
[%header%footer%autowidth]
|===
| Cell A | Cell B
|===
ASCIIDOC
Here’s how the options are assigned to the table using options .
Traditional AsciiDoc syntax
[options="header,footer,autowidth"]
|===
| Cell A | Cell B
|===
ASCIIDOC
Let’s consider the options when combined with other attributes.
Shorthand Asciidoctor block syntax
[horizontal.properties%step]
property 1:: does stuff
property 2:: does different stuff
ASCIIDOC
Traditional AsciiDoc block syntax
[horizontal, role="properties", options="step"]
property 1:: does stuff
property 2:: does different stuff
ASCIIDOC
10.6. Assigning Document Attributes Inline
Document attributes can be assigned using the following syntax:
{set:[!][:]}
For example:
{set:sourcedir:src/main/java}
ASCIIDOC
is effectively the same as:
https://asciidoctor.org/docs/user-manual/
40/315
12/20/2018
Asciidoctor User Manual
: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 Unde ned 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-nomore!} ). 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:
ASCIIDOC
Hello, {name}!
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
asciidoctor: WARNING: skipping reference to missing attribute: name
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
https://asciidoctor.org/docs/user-manual/
41/315
12/20/2018
Asciidoctor User Manual
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.
Unde ned 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:
ASCIIDOC
{set:name!}
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.
https://asciidoctor.org/docs/user-manual/
42/315
12/20/2018
Asciidoctor User Manual
Building a Document
https://asciidoctor.org/docs/user-manual/
43/315
12/20/2018
Asciidoctor User Manual
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.
https://asciidoctor.org/docs/user-manual/
44/315
12/20/2018
Asciidoctor User Manual
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:
http://asciidoc.org[AsciiDoc] is a _lightweight_ markup language...
ASCIIDOC
Processing it with the options doctype=inline and backend=html5 produces:
AsciiDoc is a lightweight markup language…
HTML
The inline doctype allows the Asciidoctor processor to cover the full range of applications, from unstructured (inline) text to full,
standalone documents!
https://asciidoctor.org/docs/user-manual/
45/315
12/20/2018
Asciidoctor User Manual
13. Basic Document Anatomy
https://asciidoctor.org/docs/user-manual/
46/315
12/20/2018
Asciidoctor User Manual
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
= The Dangerous and Thrilling Documentation Chronicles
ASCIIDOC
This journey begins on a bleary Monday morning.
Result: Rendered document title
https://asciidoctor.org/docs/user-manual/
47/315
12/20/2018
Asciidoctor User Manual
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
= The Dangerous and Thrilling Documentation Chronicles
ASCIIDOC
{doctitle} begins on a bleary Monday morning.
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
= The Dangerous and Thrilling Documentation Chronicles: A Tale of Caffeine and Words
ASCIIDOC
It began on a bleary Monday morning.
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
= A Cautionary Tale: The Dangerous and Thrilling Documentation Chronicles: A Tale of Caffeine and Words
ASCIIDOC
It began on a bleary Monday morning.
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.
https://asciidoctor.org/docs/user-manual/
48/315
12/20/2018
Asciidoctor User Manual
Document with a subtitle using a custom separator
:title-separator: {sp}|
= The Dangerous and Thrilling Documentation Chronicles | A Tale of Caffeine and Words
ASCIIDOC
It began on a bleary Monday morning.
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.
= The Dangerous and Thrilling Documentation Chronicles
Kismet Rainbow Chameleon
ASCIIDOC
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}
Result: Rendered author and email information displayed on the byline and referenced in the document’s body
https://asciidoctor.org/docs/user-manual/
49/315
12/20/2018
Asciidoctor User Manual
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.
= The Unbearable Lightness of Nomenclature
Jan Hendrik van_den_Berg
ASCIIDOC
My first name is {firstname}.
My middle name is {middlename}.
My last name is {lastname}.
My initials are {authorinitials}.
Result: Rendered author information when author has a compound name
https://asciidoctor.org/docs/user-manual/
50/315
12/20/2018
Asciidoctor User Manual
Alternatively, the author and email attributes can be set explicitly in the header.
= The Dangerous and Thrilling Documentation Chronicles
:author: Kismet Rainbow Chameleon
:email: kismet@asciidoctor.org
ASCIIDOC
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}
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.
https://asciidoctor.org/docs/user-manual/
51/315
12/20/2018
Asciidoctor User Manual
= The Dangerous and Thrilling Documentation Chronicles
Kismet Rainbow Chameleon ; Lazarus het_Draeke
ASCIIDOC
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}.
1
Until our next adventure!
{authorinitials} & {authorinitials_2}
1
To 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
= Document Title
:author_name: ACME Industries
:author_email: info@acme.com
:author: {author_name}
:email: {author_email}
ASCIIDOC
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.
https://asciidoctor.org/docs/user-manual/
52/315
12/20/2018
Asciidoctor User Manual
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.
= The Dangerous and Thrilling Documentation Chronicles
Kismet Chameleon
1
2
3
v1.0, October 2, 2013: First incarnation
ASCIIDOC
This journey begins...
== Colophon
Version: {revnumber}
Version Date: {revdate}
Version Notes: {revremark}
1
revnumber and revdate must be separated by a comma ( , ).
2
revdate can contain words, letters, numbers, and symbols.
3
The 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.
https://asciidoctor.org/docs/user-manual/
53/315
12/20/2018
Asciidoctor User Manual
= The Dangerous and Thrilling Documentation Chronicles
Kismet Chameleon
:revnumber: 1.0 1
:revdate: 10-02-2013
:revremark: The first incarnation of {doctitle} 2
:version-label!: 3
ASCIIDOC
This journey begins...
== Colophon
Version: {revnumber}
Version Date: {revdate}
Version Notes: {revremark}
1
When explicitly set, any characters preceding the version number are not dropped.
2
The revremark can contain attribute references.
3
The 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
= Main Title: Subtitle
ASCIIDOC
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
= Main Title: Main Title Continued: Subtitle
https://asciidoctor.org/docs/user-manual/
ASCIIDOC
54/315
12/20/2018
Asciidoctor User Manual
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
[separator=::]
= Main Title:: Subtitle
ASCIIDOC
You can also set the separator using a document attribute, either in the document:
A document title with an explicit title separator
= Main Title:: Subtitle
:title-separator: ::
ASCIIDOC
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
RUBY
title_parts = document.doctitle partition: true
puts title_parts.title
puts title_parts.subtitle
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
RUBY
title_parts = document.doctitle partition: '::'
puts title_parts.title
puts title_parts.subtitle
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 section of an HTML
document.
14.5.1. Description
You can include a description of the document using the description attribute.
= The Dangerous and Thrilling Documentation Chronicles
Kismet Rainbow Chameleon ; Lazarus het_Draeke
:description: A story chronicling the inexplicable hazards and vicious beasts a \ 1
documentation team must surmount and vanquish on their journey to finding an \
open source project's true power.
ASCIIDOC
This journey begins on a bleary Monday morning.
1
If 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 tag.
HTML output
https://asciidoctor.org/docs/user-manual/
55/315
12/20/2018
Asciidoctor User Manual
XML
The Dangerous and Thrilling Documentation Chronicles