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: