In Asciidoctor we can configure syntax highlighting for our source code listings.
We can choose from the built-in support for Coderay, Pygments, highlight.js and prettify.
The syntax highlighter libraries Coderay and Pygments support extra highlighting of lines, so we can add extra attention to those lines.
In this post we see how to use the line highlighting feature in Asciidoctor.
First we must add the document attribute source-highlighter and use the value coderay or pygments.
When we use Coderay we must also enable the line numbers for the source code listing, because Coderay will highlight the line numbers in the output.
Pygments highlight the whole line, with or without line numbers in the output.
Therefore we choose Pygments in our example.
To highlight certain lines in the source code output we use the highlight attribute for the source code block.
We can specify single line numbers separated by a comma (,) or semi colon (;).
If we use a comma we must enclose the value of the highlight attribute in quotes.
To define a range of line numbers we can define the start and end line numbers with a hyphen in between (eg. 5-10 to highlight lines 5 to 10).
To unhighlight a line we must prefix it with a exclamation mark (!).
For example the following value for the highlight attribute highlights the lines 2, 3 to 7 and not 5: [source,highlight=1;3-7;!5].
Continue reading →
Asciidoctor has several captions and labels that can be overridden with document attributes.
We need to define a document attribute and assign a new value to override a default caption or label.
We can use UTF-8 characters as the value.
The following list shows captions and labels we can override:
:appendix-caption::caution-caption::example-caption::figure-caption::important-caption::last-update-label::manname-title::note-caption::table-caption::tip-caption::toc-title::untitled-label::version-label::warning-caption:
Continue reading →
When we use the include directive to include another document we can must make sure the included document fits the levels of our main document.
For example the included document shouldn't have level 0 headings if the main document already contains a level 0 heading.
We can change the level offset in the main document before including another document.
This will change the heading levels for the included document so all heading rules are okay.
To change the level offset we use the document attribute leveloffset.
It is best to use a relative value, so if the included document also contains included document the output will still be okay and the heading rules still apply.
Alternatively we can use the leveloffset attribute for the include directive.
In the following sample document we include other files with a level 0 heading:
Continue reading →
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.
In the following markup we have two source code listings in Java and Groovy:
Continue reading →
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.
To define a counter attribute we must prefix the attribute name with counter:.
Each time we use this syntax with the counter: prefix the value is incremented and displayed.
To only display the current value, without incrementing, we simply refer to the document attribute without the counter: prefix.
For example if we want to add a counter attribute with the name steps we would use the following markup in Asciidoctor: {counter:steps}.
Continue reading →
With Asciidoctor we can use text to describe a symbol in our markup.
The text is automatically transformed to a Unicode replacement.
For example if we use the text (C) it is converted to © which is the copyright symbol: ©.
In the following sample we see all the symbol replacements:
Continue reading →
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 →
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 →
