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
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.
When we define the document attribute
icons with the value
font the FontAwesome fonts are loaded in the generated HTML page. In the
head section of the HTML document a
link element to the FontAwesome CSS on
cdnjs.cloudflare.com server is generated. We can change the value of the scheme from
http by setting the attribute
cdnjs.cloudflare.com server. Remember this might provide a problem if the HTML page is opened locally.
Gradle has some sophisticated progress logging on the console. For example we can see how much percentage of the building process is done. The percentage value is updated on the same console line. The following snippet is a sample of such output
> Building 0% > :dependencies > Resolving dependencies ':compile'. The information is updated on the same line, which is really nice. But sometimes we might need to run Gradle builds on a system that doesn’t support this mechanism on the console or terminal, possibly an continuous integration server. To disable the progress logging we can set the environment variable
TERM to the value
When we write technical documentation with Asciidoctor we can easily include source code listings. When we use the
pygments source code highlighter we can also include line numbers. We must add the attribute
linenums to the listing block in our markup. This attribute is used by the source highlighters to create and format the line numbers. We can specify that the line numbers must be generated in table mode or inline mode. When the line numbers are in table mode we can select the source code without the line numbers and copy it to the clipboard. If we use
inline mode the line numbers are selectable and are copied together with the selected source code to the clipboard. To specify which mode we want to use for the line numbers we use the document attribute
pygments-linenums-mode depending on the source highlighter we use. We can use the values
table (default) or
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.
MarkupTemplateEngine added in Groovy 2.3 is very powerful. We can define layout templates with common markup we want to be used in multiple other templates. In the layout template we define placeholders for variables and content blocks surrounded by shared markup. We define values for these variables and content blocks in the actual template. We even can choose to propagate model attributes from the template to the layout template.
In most of our projects we have dependencies on other code, like libraries or other projects. Gradle has a nice DSL to define dependencies. Dependencies are grouped in dependency configurations. These configuration can be created by ourselves or added via a plugin. Once we have defined our dependencies we get a nice overview of all dependencies in our project with the
dependencies task. We can add the optional argument
--configuration to only see dependencies for the given configuration. But we can even check for a specific dependency where it is used, any transitive dependencies and how the version is resolved.