No Bloat

When I started to document my adventures in Oberon programming and FPGA designs and configurations on oberon-rts.org, I simply hacked the theme that I had designed for this very website to get something somewhat useful quickly. It works, but it’s not very good for technical documentation as regards quick overview and navigation.

I use Hugo to create the actual web pages from the contents files, which are written using Markdown markup in a text editor. The contents files are “pulled into” a hierarchical framework of templates, which also add the navigation and other standard page elements, including the invisible ones in the head section, in particular the links to the stylesheets. The templates can execute logic to insert the contents and their formatting via stylesheets, use partial templates, create and link specific stylesheets if the contents of a page requires them (eg. for a picture), and so on. The templates can be the original ones of the theme, or can be supplied for the website, “plugged into” the right places. Very flexible.

Hugo is a good and powerful tool, consisting of just one (!) binary file, without the need to install all sorts of extra stuff.¹ I can simply put the executable into my ~/bin directory, and use it in my bash scripts. Script hugot renders the site into a local directory on my Mac, and a local nginx webserver allows me to use this local instance to check my work. Script hugop generates the files to be uploaded to the public Linux server using rsync.

The set of templates, stylesheets, shortcodes, etc. are called a Hugo theme.

Docsy

When I happened to come across the theme Docsy I thought, OK, let’s give this a try, as it’s made for technical documentation. Porting the contents of the Oberon RTS website into Docsy was easy enough. Things looked promising.

Docsy has lots – lots! – of features. It’s targeted at open source projects with many contributors. A “community”. It can be scaled down and simplified. Which I did. Of course, me being me, I needed to adjust more than what is possible via site parameters. Which means digging into the template code and the stylesheets.

Since everything in Hugo is hierarchical and modular, all is possible, even without touching the original theme itself. But then I all of a sudden realised: what are you doing here?! Using a theme that has way more features that I’ll ever need, and tinkering with template code and CSS that I didn’t write, and hence don’t fully understand?

I have written each and every code line of the theme used for this website, including the stylesheets. It’s a good feeling to know exactly where to go to tweak, or to extend, or to fix. Using an overly complex theme that I don’t really need and use runs completely counter to my credo of lean design and implementation.

Docsy is a good theme, but too much for me.

Step Back

Could I extend my own theme to show a list of all documents in a section in a left-hand sidebar, like Docsy, in order to easier and quicker navigate them? Quick hack prototype, and – yes. To make it look nice and well integrated would take a bit more effort. The theme’s appearance is now pretty much centred on the screen, and a left sidebar will throw things out of balance visually. So I have deferred this extension, but have decided to stay with my own theme also for Oberon RTS. Which is surely less sophisticated, and probably uses far from optimal and “professional” CSS styling. But which I understand. Mostly.

Back to the Basics

Doing the sidebar prototyping I realised how I really had hacked my original theme to make it work for Oberon RTS. Actually, I had to, since my original theme design was not really well thought out for easy adaptation. Well, it was my first Hugo theme. Consequently, I went back to the basics and have rectified this.

Which meant, alas, going back to try to understand all the templating language, and the processing of the different templates when a site gets generated. It’s all well structured, basically, but I hadn’t touched this for years. The templating language is quirky, but powerful. I’ll paste an example below for a taste.

I have considered to throw out the functionality to toggle the theme variation between light and dark, in order to simplify the logic – and future maintenance efforts –, but have left it in for now.

Bottom Line

This site and Oberon RTS are now re-generated using the updated theme. If all is good and well, you should not see any difference. :)

On Oberon RTS, I have updated the home page and the About section, and have added some introductory information for the different platforms. I am hopelessly behind with the documentation compared to the codebases on GitHub.²

As I write on the homepage: Refer to the GitHub repos for the actual details. As the saying goes: “Debug only code, don’t get suckered in by the comments.” Or by websites.

Example

Generate the article contents part of the page you’re reading. Everything inside {{ }} is template logic that is executed upon site generation. The rest is HTML code that will be inserted verbatim.

{{ define "content" }}
  <div class="article">
    <div class="article-header">
      <h1>{{ .Title }}</h1>
      {{ with .Params.description}}
        <p class="article-meta"> {{ . | markdownify | safeHTML }} </p>
      {{ end }}
    </div>
    {{ with .Content }}
      <div class="article-content">
        {{ . }}
      </div>
    {{ end }}
  </div>
{{ end }}

{{ define "debug" }}
  {{ if $.Site.Params.debug }}
    <div class="site-debuginfo">
      template: default/single, kind: {{ .Kind }}
    </div>
  {{ end }}
{{ end }}

The whole page is defined as follows. The “content” block above gets inserted at {{ block "content" . }}, “debug” at {{ block "debug" . }} if enabled via parameter $.Site.Params.debug.

<!DOCTYPE html>
<html lang="{{ .Site.LanguageCode }}">
  <head>
    <meta charset="utf-8" />
    {{- partial "head/stylesheets.html" . }}
    {{- partial "head/title.html" . }}
    {{- partial "head/meta.html" . }}
    {{- partial "head/fonts.html" . }}
    {{- partial "head/styles.html" . }}
    {{- partial "head/favicons.html" . }}
    {{- partial "head/feeds.html" . }}
  </head>
  <body>
    {{- partial "header/site-header.html" . }}
    <div class="site-content">
      {{ block "side-nav" . }}
      {{ end }}
      {{ block "content" . }}
      {{ end }}
      {{ block "bottom-nav" . }}
      {{ end }}
    </div>
    {{- partial "footer/site-footer.html" . }}
    {{- partial "footer/stylesheet-switch.html" . }}
    {{ block "debug" . }}
    {{ end }}
    {{- partial "footer/scripts.html" . }}
    {{ block "bottom-scripts" . }}
    {{ end }}
  </body>
</html>