GitHub supports Asciidoctor markup.
We can add a document to GitHub with the extension adoc and it is parsed and the resulting HTML is shown when we view the document in our web browser in a GitHub repository.
In March 2016 Dan Allen tweeted about enabling admonition icons on GitHub.
A follow-up tweet by Ted Bergeron mentioned more examples.
In this post we see an example on how to use their suggestions.
Normally we wouldn't see an icon, but we can use document attributes and assign an emoji for each admonition type.
For example a note admonition icon is set with the document attribute note-caption.
We can use a condition check to see if the document is rendered on GitHub and only then use the document attributes.
In the following example we assign icons to the different admonitions:
Continue reading →
It has already been a week since Javaland 2016 started on Tuesday March 8th. Javaland is 3-day community driven conference in the amusement park Phantasialand in Brühl, Germany. I had the fortune to attend the conference this year and speak about Asciidoctor on the first day with my talk "Writing documentation in Asciidoctor is Awesome". The code and examples from the presentation are on Github. Also my colleague Rob Brinkman was at the conference for this talk about "Westy Tracking (turning a VW van into a Tesla)" and his presentation is online as well.
What I really liked about the conference is a lot of technical talks about all kind of Java subjects. Even for a non-German person there were a lot of talks in English to follow. Also the atmosphere was very nice, people are approachable and in between talks there was a nice community and sponsor exhibition room. The organization uses the knowledge and experience of 29 JUGs from Germany, Austria and Switzerland. And then the location is also great to have a conference. The amusement park wasn't open for the public so we as Java developers had part of the park for ourselves. The location of the talks were partially in theaters and in business rooms. And at Tuesday night we were allowed to go on rides as well. (Remember: first rides, then eat and drink, if you alter the order you might get in trouble).
Continue reading →
Asciidoctor is a great tool for writing technical documentation. The documentation to our Java source is what we write in Javadoc comments. Wouldn't it be nice if we could use Asciidoctor in our Javadoc comments? Of course! We can achieve this with the Asciidoclet Javadoc doclet. The doclet processes the Javadoc comments as Asciidoctor source and generates HTML in the final Javadoc documentation. We can use all of Asciidoc syntax like tables, lists, include directives, styling and more. We can even use Asciidoctor extensions like asciidoctor-diagram.
In the following Java source code we have Javadoc comments with Asciidoctor syntax. We have document attributes, list, styling, include macro, table and asciidoctor-diagram code in our Javadoc. Notice that we don't have the clutter of HTML tags we normally we would have if we write Javadoc.
Continue reading →
Section titles in our document (titles start with two or more equals signs) are part of the document hierarchy and therefore can be used in a generated table of contents. If we don't want to include a section title in the table of contents we must make the title discrete. The title is styled like a normal section title, but it is no longer part of the document structure as title. Therefore the section title will not be generated in the table of contents. To make a title discrete we must use the attribute discrete for the title.
In the following document we first have a simple document with two section titles. When we generate the HTML for this document we see both titles in the table of contents.
Continue reading →
When we want to explain in our documentation which keys a user must press to get to a function we can use the keyboard macro in Asciidoctor. The macro will output the key nicely formatted as a real key on the keyboard. The syntax of the macro is kbd:[key]. To get the desired output we must set the document attribute experimental otherwise the macro is not used.
In the next Asciidoctor example file we use the keyboard macro:
Continue reading →
When we convert our Asciidoctor markup to HTML we automatically get a head and footer element. We can add custom content to the HTML head element and to the HTML div with id footer. We must set a document attribute and create the files that contain the HTML that needs to be added to the head or footer. We have three different document attributes we can set to include the custom content files:
:docinfo: include document specific content. Files to be included must be named <docname>-docinfo.html for head element and <docname>-docinfo-footer.html for footer content.:docinfo1: include general custom content. Files to be included must be named docinfo.htmtl for head element and docinfo-footer.html for footer content.:docinfo2: include document specific and general custom content. Files to be included must be named <docname>-docinfo.html and docinfo.html for head element and <docname>-docinfo-footer.html and docinfo-footer.html for footer content.
Continue reading →
So this year I got the opportunity to speak and visit Greach 2015 in Madrid, Spain. I've never been in Spain before, but after visiting I definitely want to go back. Although the trip to Madrid was more cumbersome than planned, because of the strikes in France, I arrived at the speaker's dinner on time. Just go to mention that the Madrid metro is a very pleasant way to go around in Madrid. It was good to see old and new faces and to catch up and just have fun. Friday April 10th was the first day of the conference. The conference is held at the university in the south of Madrid. Jochen Theodorou, one of the Groovy core developers, opened the day with the keynote about Groovy's past, present and future. He gave a very nice overview of how Groovy evolved over the years and Groovy has been around already for a long time. Of course the latest news this year is Pivotal's hands off of Groovy and Grails. Jochen explained he first gets a good vacation and then decides what to do himself. Groovy is now in the process of getting an Apache project so the continuity of the development of the language should be saved. Then the rest of the day two tracks were presented at the same time. And there were difficult choices to make. Fortunately all talks are recorded and they will be added to the Greach Youtube channel.
I went to the talk Groovy and Scala: Friends or Foes by Marco Vermeulen. He showed how we can use Spock with Groovy to test Scala code using a Gradle build. So both worlds can live together and we can intermingle where possible. The application written in Scala was pragmatic and that is something I missed when I looked at Scala for the first time. This talk really got me interested to learn more about Scala. Next up was the talk AST - Groovy Transformers: More than meets the eye! by one of the conference organizers Iván López. He showed a lot of the (local) AST transformation that are already available in Groovy and that we can use everyday in our programs. Each AST transformation was clearly explained and he showed samples on how to use them. After his talk it was my time to present Grails Goodness. In this talk I live coded a selection of the blog posts about Grails I did write. Somehow there is always to little time to show everything I wanted, but still I think I was able to show some nice features of Grails.
Continue reading →
One of the great features of Asciidoctor is the support for extensions. If we want to have some special feature we want to use, but is not supported by Asciidoctor, we can add our own extension. On the Java platform we can write those extensions in for example Java and Groovy. When we use Gradle as the build tool with the Asciidoctor plugin we can write the code for the extension in our Gradle build file with the Groovy extension DSL.
Suppose we want to write a new inline macro that will transform the following markup issue:PRJ-100[] into a link that points to the web page for issue PRJ-100. First we create our Asciidoctor source document:
Continue reading →
Creating a list with Asciidoctor markup is easy. To create an unordered we need to start a line with an asterisk (*) or hypen (-). We can add some extra markup to create a checked list. If we add two square brackets ([]) to the list item we have a checklist. To have an unchecked item we use a space, for a checked item we can use a lowercase x (x) or an asterisk (*).
In the next example we define a shopping cart list with Asciidoctor markup:
Continue reading →
With Asciidoctor we can create numbered lists easily. When we want to change the number the list starts with we use the start attribute when we define the list.
== Numbered List
.Default
. Makes writing easy
.. Keep focus
.. Syntax
. Different output formats
// Start this list from 10.
[start=10]
.Start from 10
. Makes writing easy
// We can use it on all levels.
[start=10]
.. Keep focus
.. Syntax
. Different output formats
Continue reading →
Document attributes are like variables for your Asciidoctor document. Normally when we reference an attribute that is not set in our Asciidoctor markup the reference is still in the output. This is very handy, because we immediately see that a document attribute is not set. But we can customize this behavior with the document attribute attribute-missing. We can use the default value skip, which leaves the reference in the output. Another option is drop, which means the reference is dropped from the output. Finally we can set the value to drop-line, where the complete line with the attribute reference is dropped from the output.
In the following sample Asciidoctor markup we set the three values for the attribute attribute-missing:
Continue reading →
When we define a table in Asciidoctor we might want to span a cell over multiple columns or rows, instead of just a single column or row. We can do this using a cell specifier with the following format: column-span.row-span+. The values for column-span and row-span define the number of columns and rows the cell must span. We put the cell specifier before the pipe symbol (|) in our table definition.
In the following example Asciidoctor markup we have three tables. In the first table we span a cell over 2 columns, the second table spans a cell over 2 rows and in the final table we span a cell over both 2 columns and rows.
Continue reading →
