About – Built with Hugo

Built with Hugo

This website is built with Hugo. Thanks to the Hugo team for a nice, fast, and free tool to build static websites! The theme is based on Hyde, but with a fair bit of tweaking.

What is Hugo?

Hugo is a generator for static websites. You run Hugo locally on your development computer, either as a background server or via an explicit command. Hugo processes your description of your web pages, and creates standard HTML pages, which you upload to a web server. It is an alternative to content management systems, which require additional software running on your web server, to dynamically generate the pages which are served to visitors.

With Hugo, you describe your web pages on three levels:

Net content is described in Markdown files – plain text with a minimum of information on document structure, like lists and headlines. Markdown is very easy to read and write. You arrange your Markdown pages in a file folder hierarchy, which defines the logical hierarchy of your webiste.
Page structure is described in templates – what is shown on a content or a list (overview) page; what is shown in menus, headers and footers of the pages? The template syntax provides for expression evaluation, conditional constructs, loops, and more. So templates can have some “intelligence”, and pages can adapt to your content structure.
Cosmetic appearance is defined in standard CSS style sheets.

Hugo processes the Markdown and template files and generates a set of standard HTML pages. The logical structure of navigation menus etc. on these pages is described in the templates, and will be filled in automatically by Hugo to match the current hierarchy of your pages.

You then simply copy the pages to your production web server (be it a server you operate yourself, or web space provided by a hosting service). The uploaded pages are static HTML documents – no content management system or other active services are running on the server.

Why use Hugo?

When I set about re-launching these pages and finding the right toolkit, I was mainly looking for three things:

Easy to add and update content

Content should be easy to read and write; and I don’t want to manually update separate navigation menus or such whenever I add a content page or section to the site.

Hugo does this nicely. The Markdown files are easy (for humans) to read and write; I can update and preview content locally using Hugo’s very fast rebuild and convenient local web server; and the complete site navigation is updated automatically depending on the content hierarchy.

My only reservation: Hugo does not use plain Markdown, but requires the use of shortcodes for some functions embedded in your content files. These have a rather ugly syntax which is unpleasant to read in Markdown text.

Low maintenance

I expect “quiet” periods where I don’t publish much on this website. During those times I don’t want to bother with regularly updating a CMS to avoid security risks.

Hugo certainly meets this requirement. Only static, passive data reside on the web server. As long as you don’t want to update the content, it is “fire and forget”.

Future-proof

I have seen homepage hosting services come and go, and hence do not want to depend on anyone’s proprietary “homepage toolbox”. Even tools I control and run locally should use standardized data formats, so my content will survive the eventual change to a next-gen tool.

Hugo does not rely on any tools provided by my web hoster, and I control my local Hugo toolchain. If I should want to move away from Hugo in the distant future, I trust that Markdown is here to stay, so migrating my content should not be too painful. Again, my only reservation is the use of proprietary shortcodes in the Markup, which will need to be revised if I move away from Hugo.

My Hugo theme

Hugo comes with a nice selection of themes – ready-made combinations of templates and style sheets which define the structure and appearance of a site. However, most of the themes are geared towards blogs: Post dates and keywords are the key navigation concepts.

Organized by topics

For my site, I don’t expect to publish a stream of more-or-less independent posts. I prefer to organize my content as a hierarchy of topics. There are a few Hugo themes out there which support this approach; typically in the “documentation” category. But I found these either a bit limiting or overwhelming, and ended up rolling my own, based on the Hyde theme.

My content is organized in a section hierarchy two levels deep. A second-level subsection can comprise either multiple content pages or a single page.
Each section and subsection has an _index.md file. This file contains a summary, to be displayed in the list view (overview page) on the level above. This approach works better for me than using Hugo’s automated .Summary function, since I sometimes want to word the summary differently than the lead-in paragraph to the main page.
Most section and subsection folders also contain a single picture file. If it is present, the list view template will show this picture on the overview page to illustrate the section. All other images, to be displayed on the content pages, are placed in the static folder.
I do not use Hugo’s menu system, where menus are defined in the front matter of content pages and/or in the site’s config file. Convenient enough, but still a separate definition which one needs to keep consistent with the content hierarchy.
Instead, my list.html and sidebar.html templates generate the menus and links directly from the hierarchy of content folders. The order in which sections and pages appear in the menus is defined by the weight property in each page’s front matter.

So my content folder (the hierarchy of .md files which define the site content) looks like this. To keep this brief, not all folders are expanded:

content
|   _index.md
|
|-- arcade
|   |   _index.md
|   |   somepreview.png
|   |-- asteroids
|   |       _index.md
|   |       asteroids_preview.jpg
|   |       intro.md
|   |       cabinet.md
|   |       electro.md
|   |-- pong
|   |       _index.md
|   |       pong_preview.jpg
|   |       pong.md
|   |-- verticade
|
|-- computing
|   |   _index.md
|   |   computing_preview.jpg
|   |-- lgp30
|   |-- rollkugel
|   |-- rpc4000
|
|-- other
|   |...

Templates and CSS for download

So, after all this ado: The main changes I made to the Hyde theme are in the layout templates. This is where the page structure is defined, and where the navigation menus are generated from the section structure. A zipped copy of my layouts folder is here.

The only CSS file I changed is the top-level hyde.css. That file is, of course, available on the website anyway, since your browser wants to see it to render the site properly. You can view it here.