Just a small reminder. Javascript allows you to call methods based on their name. So if a DOM element has a addClass and removeClass which both take the same argument we could write:
var someClass = 'some-class';
var hasClass = element.hasClass(someClass);
if(hasClass){
element.addClass(someClass);
} else {
element.removeClass(someClass);
}
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.
We have the following Asciidoc markup for a document stored on GitHub:
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.
If we want to use a different CDN to serve the CSS we can set the document attribute iconfont-cdn and set the URI as a value:
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 https://cdnjs.cloudflare.com/ajax/libs is added. Also when we use the highlight.js or Prettify source highlighter a link to the Javascript files on the cdnjs.cloudflare.com server is generated. We can change the value of the scheme from https to http by setting the attribute asset-uri-scheme to http. Or we can leave out the scheme so a scheme-less URI is generated for the links. A scheme-less URI provides the benefit that the same protocol of the origin HTML page is used to get the CSS or Javascript files from the cdnjs.cloudflare.com server. Remember this might provide a problem if the HTML page is opened locally.
In the next sample Asciidoc markup we change the scheme to http:
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 dumb.
Written with Gradle 2.0.
When we write technical documentation with Asciidoctor we can easily include source code listings. When we use the coderay or 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 coderay-linenums-mode or pygments-linenums-mode depending on the source highlighter we use. We can use the values table (default) or inline.
= Source code listing
Code listings look cool with Asciidoctor and {source-highlighter}.
[source,groovy,linenums]
----
// File: User.groovy
class User {
String username
}
----
[source,asciidoc,linenums]
----
# Hello world
Asciidoc(tor) is aweseome!
----
Asciidoctor is a great tool for writing technical documentation. If we have source code in the Asciidoc markup we can set the document attribute source-highlighter to pigments, coderay, prettify and 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 use the following Asciidoc markup to see how the HTML output is when we transform the markup using the HTML backend:
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 (////).
The following sample markup defines Asciidoc markup with comments:
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 the next Asciidoc syntax we first define URLs without the hide-uri-scheme attribute, followed by URLs after the attribute is set:
The 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. Let's first create a layout template with the name main.tpl:
// File: main.tpl
html {
head {
// Use pageTitle layout property.
title(pageTitle)
}
body {
section(id: 'main') {
// Render mainContents layout property.
mainContents()
}
section(id: 'actions') {
// Render actions layout property.
actions()
}
footer {
// A template is also Groovy code, we can
// define new variables or methods.
// pubDate should be set via original template
// model.
def generatedOn = pubDate ?: new Date()
p("Generated on ${dateFormat(generatedOn)}")
}
}
}
def dateFormat(date) {
date.format('dd-MM-yyyy')
}
