To use font icons from FontAwesome we set the document attribute
icons with the value
font. The default link to the CSS location is
https://cdnjs.cloudflare.com/ajax/libs/font-awesome/4.1.0/css/font-awesome.min.css. We can change the location for the FontAwesome CSS with document attributes.
Asciidoctor is a great tool for writing technical documentation. If we have source code in the Asciidoc markup we can set the document attribute
highlightjs. When we use highlight.js we can also add an extra document attribute
highlightjs-theme with the value of a highlight.js theme. If we do not specify the
highlightjs-theme the default theme github is used.
We can add comments to our Asciidoc markup. The comments will not be added to generated output. We can add both single and multiline comments in the markup. Single line comments start with a double slash (
//). Multiline comments are enclosed in a block of four forward slashes (
Since Asciidoctor 1.5.0 we can use the document attribute
hide-uri-scheme to turn URLs into links, where the link text is displayed without the URI scheme. This can save typing when we simply want to add a URL without any special description.
In Asciidoc markup we can include or exclude text based on the existence of document attributes or based on the value of a document attribute. Therefore we use the macros
ifeval. If we want to include some content if the document attribute sample is set we can use the following syntax:
ifdef::sample[Content is shown when sample attribute is set]
Content is shown when sample attribute is set
If we want to include some content if the attribute is not set we use
ifndef::sample[Content is shown when sample attribute is NOT set]
Content is shown when sample attribute is NOT set
In a previous post we learned how to include partial content from included files. We needed to enclose the content we want to include between start and end tags and reference those tags in our documentation markup. But Andres Almiray already mentioned in a tweet we can use line numbers as well:
Writing documentation with Asciidoc is such a treat. We can add markers to our code where we want to explain something in our code. The markers have numbers and are enclosed in
> brackets. The explanation for the markers follows a code listing in a callout list. Here we use the same marker and add extra text to explain the code. We can put the markers in comments in our code so we can use the markers in existing code.
Writing technical documentation with Asciidoc and Asciidoctor is so much fun. Especially the
include macro makes inserting changing content, like source files, a breeze. We only need to maintain the original source file and changes will automatically appear in the generated documentation. We can include only a part of source file using tags. In the source file we add a comment with the following format
tag::tagName to start the section. We end the section with
end::tagName. Now in our Asciidoc document we can indicatie the tags we want to include with