Dear Diary: Using AsciiDoc to write Papers
False expectations take away joy, according to Sandra Bullock. Such was my feeling when I tried to write a full-fledged document using AsciiDoc. I thought I would be a pleasant journey. Could I be wrong?
Asciidoc
Awesome Asciidoctor: Image As Link Reference
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:
Awesome Asciidoctor: Change Number Style For Ordered Lists
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:
Awesome Asciidoctor: Nested Delimited Blocks
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:
Awesome Asciidoctor: Disable Last Updated Text in Footer
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:
Awesome Asciidoctor: Using Document Fragments
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:
Awesome Asciidoctor: Changing the Grid and Frame of Tables
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.
Awesome Asciidoctor: CSV and DSV Tables
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:
Awesome Asciidoc: Conditional Directive to Check If Document is On GitHub
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:
Awesome Asciidoc: Changing the FontAwesome CSS Location
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:
Awesome Asciidoc: Change URI Scheme for Assets
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:
Awesome Asciidoc: Adding Line Numbers to Source Code Listings
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!
----
