Asciidoctor User Manual
Sarah White
@graphitefriction
Dan Allen
@mojavelinux
Table of Contents
Titlepage
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 Benefits
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
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. Alignment
18.2. Line Breaks
18.3. 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. Defining 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
28.2. Processing
28.3. File resolution
28.4. Partitioning large documents and using leveloffset
28.5. AsciiDoc vs non-AsciiDoc files
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
28.11. Using an Include in a List Item
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
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. Rouge
46.5. Pygments
46.6. CodeRay
46.7. 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 files
49.2. Footer docinfo files
49.3. Naming docinfo files
49.4. Enabling docinfo
49.5. Locating docinfo files
49.6. Attribute substitution in docinfo files
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
61.1. Externalizing a Footnote
61.2. Footnotes in Headings
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
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. Generate an HTML TOC
81. Provide Custom Templates
Extensions
82. Extension Points
83. Example Extensions
83.1. Preprocessor Example
83.2. Tree Processor Example
83.3. Postprocessor Example
83.4. Docinfo Processor Example
83.5. Block Processor Example
83.6. Compound Block Processor Example
83.7. Block Macro Processor Example
83.8. Inline Macro Processor Example
83.9. Include Processor Example
Build Integrations and Implementations
84. Java
85. Gradle
86. Maven
87. Apache Ant
88. JavaDoc
89. JavaScript
Conversions and Migrations
90. Migrating from AsciiDoc Python
90.1. Command Line Interface
90.2. Changed Syntax
90.3. Deleted and Deprecated Syntax and Attributes
90.4. Default HTML Stylesheet
90.5. Mathematical Expressions
90.6. AsciiDoc Python Extensions
90.7. Custom Extensions
90.8. Features Introduced by Asciidoctor
91. Convert DocBook XML to AsciiDoc
92. Convert Markdown to AsciiDoc
93. Convert Confluence XHTML to AsciiDoc
94. Convert MS Word to AsciiDoc
Resources
95. Copyright and License
96. Authors
97. Troubleshooting
Glossary
Appendix A: Catalog of Document Attributes
A.1. Environment Attributes
A.2. Built-in Attributes
A.3. Predefined 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
Introduction to Asciidoctor