Asciidoctor is a great tool for writing technical documentation. The documentation to our Java source is what we write in Javadoc comments. Wouldn’t it be nice if we could use Asciidoctor in our Javadoc comments? Of course! We can achieve this with the Asciidoclet Javadoc doclet. The doclet processes the Javadoc comments as Asciidoctor source and generates HTML in the final Javadoc documentation. We can use all of Asciidoc syntax like tables, lists, include directives, styling and more. We can even use Asciidoctor extensions like asciidoctor-diagram.
Section titles in our document (titles start with two or more equals signs) are part of the document hierarchy and therefore can be used in a generated table of contents. If we don’t want to include a section title in the table of contents we must make the title discrete. The title is styled like a normal section title, but it is no longer part of the document structure as title. Therefore the section title will not be generated in the table of contents. To make a title discrete we must use the attribute
discrete for the title.
Creating a list with Asciidoctor markup is easy. To create an unordered we need to start a line with an asterisk (
*) or hypen (
-). We can add some extra markup to create a checked list. If we add two square brackets (
) to the list item we have a checklist. To have an unchecked item we use a space, for a checked item we can use a lowercase x (
x) or an asterisk (
With Asciidoctor we can create numbered lists easily. When we want to change the number the list starts with we use the
start attribute when we define the list.
Document attributes are like variables for your Asciidoctor document. Normally when we reference an attribute that is not set in our Asciidoctor markup the reference is still in the output. This is very handy, because we immediately see that a document attribute is not set. But we can customize this behavior with the document attribute
attribute-missing. We can use the default value
skip, which leaves the reference in the output. Another option is
drop, which means the reference is dropped from the output. Finally we can set the value to
drop-line, where the complete line with the attribute reference is dropped from the output.
In our Asciidoc markup we can include delimited blocks, like sidebars, examples, listings and admonitions. A delimited block is indicated by a balanced pair of delimiter characters. For example a sidebar starts and ends with four asterisk characters (
****). If we want to nest another delimited block of the same type we must add an extra delimiter character at the start and end of the nested block. So when we want to nest another sidebar block inside an existing sidebar block we must use five asterisk characters (
With Asciidoctor we can repeat cell contents if we prefix the cell separator pipe symbol (
|) with the number of times we want to repeat the cell followed by an asterisk (
When we transform our Asciidoc source files to HTML Asciidoctor will print the date and time the document was last updated in the footer. If we want to disable the Last updated text we disable the document attribute
Normally all Asciidoc files are processed and transformed to output files by Asciidoctor. But if we start the file name with an underscore (
_) the file is not transformed to an output file. This is very useful, because we can define some Asciidoc document fragments and include them in other Asciidoc files, but in the output directory the document fragment is not generated.