Asciidoc is fully documented, and its documentation is actively maintained. This document contains some information on asciidoc markup to get you started.
For details and additional options:
-
Asciidoc/asciidoctor writers' guide: https://asciidoctor.org/docs/asciidoc-writers-guide/
-
Asciidoc quick reference: http://asciidoctor.org/docs/asciidoc-syntax-quick-reference/
-
Asciidoctor user manual: http://asciidoctor.org/docs/user-manual/
In addition, you have the option of asking questions in the asciidoctor discussion list:
As is true of any complex process, asciidoc/asciidoctor has some quirks. Please be certain to make use of these templates because they provide you with files that will result in fully featured pdf output.
Best practice is to test the pdf build frequently to ensure that you have not accidentally introduced something that breaks the build.
|
Warning
|
PDFs require the use of Ruby 2.7.2. |
In asciidoc you cannot jump directly from a Head 1 to a Head 3 or 4. Your headers must appear in numerical sequence from Head 1 to Head 2, and onward. If you skip over a header in the sequence, asciidoctor throws an error.
= Title head (book or report title)
[colophon]
= Colophon head (in frontmatter, used for preface)
[[chapter_title]]
== Head 1 (chapter)
=== Head 2 (section)
==== Head 3 (subsection)
===== Head 4 (sub-subsection)
[appendix]
== Appendix title
[index]
Index|
Note
|
Settings in the header file trigger auto-generation of Appendix prefixes and of the Index (among other things). |
Asciidoc/asciidoctor supports code blocks with syntax highlighting for many languages. You can use either periods or dashes to indicate code blocks, and use macros to indicate that the block contains code in the specified language, as in the following example:
[source,python]
....
mono-spaced code block
add a1,a2,a3; # do an ADD
....renders as follows:
mono-spaced code block
add a1,a2,a3; # do an ADDAsciidoctor automates some linking as follows:
-
Asciidoctor recognizes hyperlinks to Web pages and shortens them for readability.
-
Asciidoctor automatically creates an anchor for every section and discrete heading.
To create highlighted links, use the pattern in the following example:
https://asciidoctor.org[Asciidoctor]You can set attributes for your external links
Use macros for cross references (links within a document) as in the following example:
<<Index markers>> describes how index markers work.This renders as:
[Index markers] describes how index markers work.
The book_header.adoc file in the docs-templates repo sets the full cross reference attribute to enable the display of captions from targets in the anchors. This allows you to set captions for tables, blocks, and illustrations. If no caption is provided, Asciidoctor defaults to the basic cross reference style.
To set a caption for a table or image, use the pattern as follows:
The table below, <<trapcharacteristics,Characteristics of traps>> shows the characteristics of each
kind of trap.[[trapcharacteristics,Characteristics of traps]]
.Characteristics of traps.
[cols="<,^,^,^,^",options="header",]
|===
| |Contained |Requested |Invisible |Fatal
|Execution terminates |No |Nolatexmath:[$^{1}$] |No |Yes
|Software is oblivious |No |No |Yes |Yeslatexmath:[$^{2}$]
|Handled by environment |No |Yes |Yes |Yes
|===The table below, Characteristics of traps shows the characteristics of each kind of trap.
| Contained | Requested | Invisible | Fatal | |
|---|---|---|---|---|
Execution terminates |
No |
No\(^{1}\) |
No |
Yes |
Software is oblivious |
No |
No |
Yes |
Yes\(^{2}\) |
Handled by environment |
No |
Yes |
Yes |
Yes |
The :stem: latexmath setting makes use of asciidoctor-mathematical for asciidoctor-pdf output.
Asciidoctor Mathematical is a Ruby gem that uses native extensions. It has a few system prerequisites which limit installation to Linux and macOS. Please refer to the README in the RISC-V docs-templates repo for information on the asciidoctor-mathematical install.
[stem]
++++
sqrt(4) = 2
++++In some cases, you might want to make use of unicode characters. Keep in mind that asciidoctor-pdf currently only supports decimal character references. See asciidoctor/asciidoctor-pdf#486
Hexadecimal unicode looks like it has problems in the pdf. This is gnarley.
Updates to asciidoctor-pdf: https://github.com/asciidoctor/asciidoctor-pdf