To make an image linkable in Asciidoctor when formatted to HTML we must use the link attribute when we use the image macro. The value of the link attribute is the address where the user goes when clicking on the image. We can also specify extra link attributes like window to specify the target window for the link to open in.
In the following example we use the link attribute for a block and inline image, with and without an extra window attribute:
Continue reading →
To write a (nested) ordered lists in Asciidoctor is easy.
We need to start the line with a dot (.) followed by a space and the list item text.
The number of dots reflects the levels of nesting.
So with two dots (..) we have a nested list item.
By default each nested level has a separate numbering style.
The first level has arabic numbering, the second lower case alphanumeric, the third upper case alphanumeric, the fourth lower case roman and the fifth (which is maximum depth of nested levels in Asciidoctor) has style upper case roman.
But we can change this by setting a block style for each nested level block.
The name of the block style is arabic, loweralpha, upperalpha, lowerromann or upperroman.
With the HTML5 backend we can also use decimal and lowergreek.
In the following example we have an ordered list where we set different block styles for the nested level:
Continue reading →
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 (*****).
In the following example Asciidoc source we have several blocks with nested blocks:
Continue reading →
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.
In the following example Asciidoc file we disable the Last update label in the footer:
Continue reading →
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.
Let's create two Asciidoc files. One is _attrs.adoc which is a document fragment file that is used in sample.doc:
Continue reading →
We can change the frames and grid of tables we define in Asciidoctor. We use the frames attribute to change the outside frame of a table. We can choose between topbot for top and bottom, sides for only a frame at the sides of the table, none if we don't want a frame. The default value all create a frame around our table with top, sides and bottom.
To change the inner grid of a table we use the grids table attribute. The default value all displays a grid for columns and rows inside the table. The value cols only displays a grid between columns, value rows display a grid between rows and with value none there will be no grid inside our table.
Continue reading →
With Asciidoctor we can create tables where the header and rows are in CSV (Comma Separated Values) and DSV (Delimiter Separated Values) format. Normally we use a pipe-symbol (|) to separate cell values. This is actually PSV (Prefix Separated Values) :-).
In the following Asciidoctor markup we create a very simple table with a header and two rows using CSV:
Continue reading →
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:
Continue reading →
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:
Continue reading →
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:
Continue reading →
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!
----
Continue reading →
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:
Continue reading →
