Improving a Static Web Site Build With Hugo and Docsy

2021-09-01

Tags:

The static website build tool Hugo is awesome. With the extensive built-in feature set of Hugo and the feature-rich text formatting options that Asciidoc offers, it creates a blogging experience composed of easy content management and fun writing experience.

In most static site generators including Hugo, Markdown is the one and only first-class citizen when it comes to creating posts.

However, in recent Hugo versions, external helpers are an official feature. It calls appropriate external programs to a certain type of files. Fortunately, Asciidoc based files are automatically compiled with Asciidoctor, so we do not need to do anything. Just 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 love to write my documentation and blogs using Asciidoc notation ^[1]. The official site is Asciidoc. A major tool chain can be found under Asciidoctor.].

Hugo supports Asciidoctor through external helpers. External helpers are relatively new and more like an experimental feature. There is a proposal on improving it by adding user configurations, so at least there is hope for this particular feature to expand.

The features of Asciidoc are equivalent to DocBook. The readers with gray hair probably remember SGML, the ancestor of DocBook. The librarians could remember LaTeX created by Leslie Lamport. He created it to describe temporal logic aspects of cluster communication for the Digital Equipment Corporation DEC solution. These highly qualified experts and their solutions paved the way to legible documentation and professional typography.

Source Code Highlight

Asciidoctor supports rouge source code highlighting per default ^[2]. You do need to add any extension to Hugo. Just select the style you prefer, such as:

rouge-style = "github"

Search Function for the Website

The theme has multiple search solutions to index your static website. I chose the Lunr approach for our site. The solution has no strings attached and does not require an external search server.

The website and the search functionality are self-contained as a static website should be.

Comment Function for Blog Article

The comment feature is somewhat at odds with the concept of static website. The theme has multiple comment solutions to allow readers to publish a question or a test to our site. I decided to provide comments only to the blog part of the website. I chose the Utterances approach for our site. The solution has no strings attached and uses the well-known platform GitHub. No tracking, no ads and no locking are great.

The comment author must first log in GitHub before adding her comment therefore spamming or flaming are minimized.

You have to create a partial in docsy to use Utterances.

<div class="page-blank">
    <div id="utterancers_thread"></div>
    <script src="https://utteranc.es/client.js"
            repo= {{ .Site.Params.comments_utterances_repo }}
            issue-term= {{ .Site.Params.comments_utterances_issue_term }}
            theme= {{ .Site.Params.comments_utterances_theme }}
            crossorigin="anonymous"
            async>
    </script>

Tag Function for Blog Article

Docsy has finally merged the change request for taxonomies during the first semester of 2021. Tags for articles are now natively supported without tinkering with the code of the plugin.

Our blog displays the tags on the right side of the window. Give it a try.

Diagrams in articles

Diagrams in blog articles are currently a more complex issue. Hugo seems to be quite restrictive which extensions can be loaded when generating a static site ^[3]. No reasonable reasons exit for the above-mentioned restrictions. Ongoing pull requests try to improve the situation.

I had success with:

plantUML diagrams: See, for example, following blogs GitLab for Students
mermaid diagrams: See for example following blogs Agile Trend 2021 or Agile Trend 2020.

plantUML supports hyperlinks in diagrams. To use relative links in your site declare a PlantUML variable for the root of your and define links relative to this root. The declarations for such a diagram could be:

[plantuml,target=dependencies,format=svg, width="100%",,opts="inline",svg-type="inline"]     (1)

....
@startuml

!$root = "https:/blog.tangly.net"                                              (2)

package net.tangly.bdd [[$root/docs/bdd/]] {                                   (3)
}

@enduml
....

1	Links work only for SVG digrams with the opion inline or interactive. The value is stated once in opts and once in svg-type because plantUML and kroki generators use different options for the same information.
2	Define a plantUML variable for the root URL of your site. I could not use asciidoc variable in plantUML links because the characters {} are interpreted as caption items.
3	Use the variable to define links [[]] relative to your root. plantUML will expand the link to expected value.

The generated HTML code does not respect all AsciiDoc parameters. Text flow configurations are not enforced.

Layout and Appearance

The docsy theme is regularly improving. The provided features are good and very stable.

The Hugo integration of Asciidoc is subpar. The CSS styling files of Asciidoc are not integrated with Hugo and themes. Often the appearance of the generated HTML could be improved. I am currently exploring venues to improve the integration of nice looking asciidoc styling sheets with the docsy universe.

Future Features

I have integrated an extension to provide access to static files through a Hugo/Docsy site. For example the presentation of a speech is made available directly in the static website.

This feature is currently experimental and queued as a pull request in the Docsy GitHub repository ^[4].