Asciidoc and Hugo Website Improvements

Tags:
2024 03 03 head

The static website build tool Hugo is awesome.

The extensive built-in feature set of Hugo and the feature-rich typesetting that Asciidoc offers provide a blogging experience composed of easy content management and fun writing experience.

Source code highlighting and diagrams are extensively supported.

Hugo supports natively Asciidoc syntax. Asciidoc files are automatically compiled with Asciidoctor, so we do not need to configure anything. Have it installed and you are ready to go.

The Hugo theme Docsy is ideal to create a good-looking software documentation site. This theme is currently the best match I found to combine product documentation with blogging.

I can generate the whole static website and publish it in less than two minutes. All artifacts are under version control.

Major activities are easy to perform.

blog-journey

In this article I want to share some improvements I made to my website using features of Asciidoc and Hugo.

Include Common Blocks

Quite a few articles are part of a series. All related articles share common references. To avoid duplication, I use the include directive to include a common block of references.

The huge advantage is I only need to update the common block when a new article is published in the series. All articles are updated without manual intervention.

This approach is easy to maintain and avoid errors. It shows the power of Asciidoc and Hugo.

These techniques are not possible with regular blogging platforms.

Bibliography

I use the asciidoctor-bibtex plugin to include references in my articles.

The reference file is a regular bibtex file. I use JabRef to manage my references. To simplify the life of my readers, I include a link to the amazon page of the book so that they can easily have a quick look at the referenced publication.

The link is defined as a regular attribute in the bibtex file.

I am very satisfied with the result. I acknowledge that the importance of professional references is triggered by the fact that I am a technical university lecturer.

Taxonomies

I use taxonomies to categorize my articles. Taxonomy support in Hugo is very powerful. You can define multiple orthogonal taxonomies.

I use only one taxonomy dimension to categorize my articles.

I had to adapt slightly the Docsy theme to nicely display the taxonomies in the sidebar.

Diagrams as Code

I use plantUML to generate UML or C4 diagrams and mindmaps.

The Mermaid plugin provides additional diagram types:

  • Customer journey maps

  • pie, quadrant and XY charts

  • Timelines

  • C4 diagrams as with plantUML

I use the asciidoctor-kroki extension to generate all diagrams without installing any diagram generation software on my machine.

If you work for a paranoid organization, you can install a local kroki server. The responsible for the project provide Docker images.

This approach guarantees that no data is sent to an external server.

RevealJS

I regularly give presentations at technical universities and internal workshops. I was looking for a way to use Asciidoc power to create and publish my slides on my website. Asciidoctor provides a nice converter to reveal.js.

I can now create my slides in Asciidoc and publish them on my website. The command to generate the slides for a presentation is:

bundle exec asciidoctor-revealjs
    -r asciidoctor-diagram -r asciidoctor-bibtex -r asciidoctor-kroki          (1)
    -a revealjsdir=https://cdn.jsdelivr.net/npm/reveal.js@5.5.0.4              (2)
    <folder>/<presenation>.adoc                                                (3)
1 Load the diagram, bibtex and kroki extensions used in the presentation
2 Select the reveal.js distribution
3 The presentation file to process

The generated presentation can be distributed as a single HTML file. Any browser can display the slides and support navigation and the presenter mode.

The presentation contains the notes you wrote for each slide and has all the functionality of a RevealJS slide deck.

Lessons Learnt

Toolchain

Beware of your toolchain. After updating some ruby modules, I could not generate bibtex citation references anymore [1]. I posted the issue on the asciidoctor GitHub, and some weeks later a new version was released. The gem asciidoctor-bibtex-0.9.0 fixed the issue.

The following statements are helpful for ruby applications. Beware that Asciidoctor is a ruby application.

gem list                                                                       (1)
gem outdated                                                                   (2)
gem update                                                                     (3)
gem cleanup                                                                    (4)

ruby -v                                                                        (5)
1 list all installed gems
2 list all outdated gems
3 update all installed gems
4 remove old versions of gems
5 show the current ruby version

The consequence is that I should set up a CI pipeline to check if the toolchain is still working.

Asciidoc Stylesheet

The support of Docsy for Asciidoc is limited. I had to extend the theme to support styling of Asciidoc texts and to display taxonomies in the sidebar.

Additional tinkering supports the download of referenced documents.

Link Integrity

When your website is growing, you need tools to ensure consistency of links. I use integrity to validate all hyperlinks on my website.

Links

1. The problem was an incompatibility between ruby 2.x and 3.x of one gem called bibtex-ruby used by the asciidoctor bibtex extension. Therefore, all unit tests of the package still run under the older version of ruby. People who updated to the newer ruby discovered the problem. The Asciidoc community solved the issue in a few weeks.