Awesome Asciidoctor: Using Asciidoctor In Javadoc Comments

Posted on November 6, 2015 by mrhaki

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.

Continue reading →

Awesome Asciidoctor: Leave Section Titles Out of Table Of Contents

Posted on September 11, 2015 by mrhaki

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.

Continue reading →

Awesome Asciidoctor: Creating a Checklist

Posted on March 4, 2015 by mrhaki

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 (*).

Continue reading →

Awesome Asciidoctor: Change Start Number for Numbered List

Posted on March 3, 2015 by mrhaki

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.

Continue reading →

Awesome Asciidoctor: Customize How Missing Attributes Are Handled

Posted on March 2, 2015 by mrhaki

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.

Continue reading →

Awesome Asciidoctor: Nested Delimited Blocks

Posted on December 11, 2014 by mrhaki

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 (*****).

Continue reading →

Awesome Asciidoctor: Repeating Cell Contents

Posted on December 3, 2014 by mrhaki

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 (*).

Continue reading →

Awesome Asciidoctor: Disable Last Updated Text in Footer

Posted on December 2, 2014 by mrhaki

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 last-update-label.

Continue reading →

Awesome Asciidoctor: Using Document Fragments

Posted on November 27, 2014 by mrhaki

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.

Continue reading →

Awesome Asciidoc: Conditional Directive to Check If Document is On GitHub

Posted on September 1, 2014 by mrhaki

In a previous blog post we learned about the conditional directives in Asciidoctor. Dan Allen mentioned a conditional directive that we can use to see if the document is used on GitHub. The conditional directive is called env-github.

Continue reading →