Awesome Asciidoctor: Source Syntax Highlighting With Prism

Asciidoctor has built-in support for a couple of source syntax highlighting libraries like Coderay, Pygments, highlight.js and prettify. In this post we learn how to use the Javascript library Prism to do the syntax highlighting for our source blocks. Because Prism is a Javascript library we must remember this only works for the HTML backend of Asciidoctor.

Continue reading

Awesome Asciidoctor: Use Counters in Markup

In Asciidoctor we can create a document attribute as a counter attribute. The attribute is automatically incremented each time we use it in our markup. We can choose to use numbers or characters. Only latin characters from ‘a’ to ‘z’ or ‘A’ to ‘Z’ are allowed. By default the counter will start at 1, but we can define another start value when we use the counter attribute for the first time.

Continue reading

Awesome Asciidoctor: Using Admonition Icons On GitHub

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.

Continue reading

Javaland 2016 Conference Report

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).

The first day started with an explanation about the program, talks, different community events from the organization. Next we attended a session about how to visualize relations between Wikipedia articles from James Weaver. He showed a Spring application backend with an Angular frontend running on Cloudfoundry. Next up was Rob Brinkman with his excellent talk on how he added electronics to an “old” VW van, so he could save his trips and tracking information. He showed the software architecture he used with Vert.x 3, Redis, Java 8 and Angular to make it all work together. It was time for lunch and that was very good organized. A lot of different things to choose from and it tasted very well. After lunch we attended a short talk about streams and reactive programming that was very informative given by Jan Carsten Lohmüller. In the afternoon we stayed a while at the community floor and stumbled upon a nice small presentation from Andres Almiray about a JSR for desktop applications. The setting was very informative and I really liked this aspect of the conference. Furthermore we attended a session about Lombok to reduce the boilerplate code in Java presented by Roel Spilker and Reinier Zwitserloot. Bert Jan Schrijver gave a good presentation about performance testing with Gatling. He even did live Scala coding on stage! Gatling looks like a very nice tool to define scenario’s for simulating multiple users accessing your application.

At night the park was open and some attractions were open, especially the roller coaster rides. Also there was a good diner organized at different locations.

The second day of the conference started for me with a talk by Josh Long about Spring Cloud. The Spring Cloud project has a lot of very useful subprojects to work with microservices in a distributed manner. Even though the session could only last 40 minutes Josh managed to show a lot of cool stuff with live coding small applications. At lunch time I attended a good talk which started with a cool Lego demo by Johan Janssen and Martin Kanters. They managed to control Lego trains and a fairy wheel from their browser. And it all worked as well. They used Akka on Raspberry Pi’s to make it all work and explained the software architecture.

After another tasteful lunch I learned more about monads in Java 8. Normally this is a very theoretical subject, but presenter Oleg Shelajev did a good job and showed real code on how monads appear in Java. The last session of the day was about using Groovy as a system scripting language by Andrey Adamovich. He showed the cool stuff of Groovy to make as script developer so much easier. Instead of relying on Bash or another script language, just use Groovy and all the Java libaries we already know.

The final day of the conference was a tutorial/workshop day. I attended a Vert.x 3 workshop given by Jochen Mader. Although it was in German I could still follow it very well. He presented some theory and then we could make small exercises in Vert.x 3. Then we would look at possible solutions for the exercise given by Jochen. I learned a lot during this day.

It was the first time I went to Javaland and it was a very good experience. The location, the organization and the content are all excellent. Although I already know I cannot make it next year, I still want to come back during the next years.

Original blog post

Awesome Asciidoctor: Using Asciidoctor In Javadoc Comments

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.

Continue reading

Awesome Asciidoctor: Leave Section Titles Out of Table Of Contents

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.

Continue reading

Awesome Asciidoctor: Display Keyboard Shortcuts

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.

Continue reading

Awesome Asciidoctor: Adding Custom Content to Head and Footer

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

Greach 2015 Conference Report

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.

Continue reading