Static Website Improvements
The static website build tool Hugo is awesome.
The extensive built-in feature set of Hugo and the feature-rich text-formatting options that Asciidoc offers creates a blogging experience composed of easy content management and fun writing experience.
The Hugo theme Docsy is ideal to create a good-looking software documentation site. The templates for blogging are good enough for our needs.
This theme is currently the best match I found to combine product documentation with blogging.
I love to write my documentation and blogs using Asciidoc notation. The expression power covers all our needs. A major tool chain is the Asciidoctor ecosystem.
Lately, I needed new features to ameliorate the usability of our open-source documentation and blogging site.
I had to deepen my understanding of how Hugo is working with themes.
Tabs
I wanted to display plantUML diagrams and the associated code side by side in my article. The tab approach is perfect and lets the reader switch between both views in her browser.
provides an extension to support tabular display [1].
-
The stylesheet for Asciidoc was extended to handle the tabular notation. The crew provides a styling example. Find my scss stylesheet under Asciidoc Docsy Stylesheet.
-
Add the Javascript code to react to user selections. Find my javascript code under Asciidoc Tabs Javascript.
-
The script code shall be included in the Hugo partials. Find the HTML code under Hugo Docsy Partials in the file footer.html.
An article using this functionality is C4 and UML with plantUML.
I hope that the tabular display extension will soon graduate to an official Asciidoc extension.
Attachments
I am a lecturer at Lucerne School of Information Technology. All my course materials are under Creative Commons CC BY-SA..
I wanted to provide recommended reading materials as a list of downloadable documents on the website.
The Docsy theme as a merge request for exactly this function. The request was created in June 2021. It is still open end of November 2023, more than two years later [2].
I decided to add the necessary code as a local extension to the docsy theme.
-
Add the Hugo shortcodes to the theme under Hugo Docsy Shortcodes in the file attachments.html
-
Add my scss stylesheet under Asciidoc Docsy Stylesheet in the file shortcodes.scss.
A document using this functionality is Lectures. The page displays multiple lists of documents. The reader can download the material she is interested in.
Mundane Work
I invested quite some time to improve the layout of the blog articles in the context of the Docsy theme. Hugo supports Asciidoc out of the box. It does not mean that the layout is perfect.
Another tedious activity is to remove broken links from the website.
The Asciidoc stylesheet had to be extended to support the additional features I am using.
The work is low tech. But I am convinced that users will appreciate the improvements.
Links
-
[1] Static Website Improvements Marcel Baumann. 2023.
-
[2] Improving a Static Website Build With Hugo and Docsy Marcel Baumann. 2021.
-
[3] Support Comments for Static Hugo Website Marcel Baumann. 2020.
-
[4] Creating a technical Website with Hugo and Asciidoc Marcel Baumann. 2020.
1. The extension is still beta level end of 2023.