Hugo on Werk Space

Document system

Wed, 08 Apr 2020 09:46:25 -0500

This page describes the system as it runs today: dev container, vendored theme, Render builds. The manual procedures from earlier stages of the system are preserved in the 2023 revision of this page on GitHub.

Overview

The first step in starting a document system is to evaluate and determine which system to use. Based on experience, I decided that my system needed:

Documents written in markdown for simplicity, universality, and versioning.
Documents organized in a tree fashion with options for categories and tagging.
Standardized presentation formatting.
Advanced formatting and presentation options.
Easily searchable.
Available from anywhere.

In other words, I wanted a system that converted markdown documents to an organized and hyperlinked website.

Hosting

Thu, 06 Aug 2026 00:00:00 +0000

The model

werkspc.com is a Render static site. Render watches the GitHub repository, and every push to master triggers a build from source: there is no local production build step, and the generated public/ directory is never committed. Deployment is therefore identical to pushing, which keeps the git workflow the only workflow.

The site’s DNS is managed at Cloudflare, with the domain pointed at Render.

The build

Render’s dashboard build command is intentionally minimal:

Theme Overrides

Thu, 06 Aug 2026 00:00:00 +0000

The principle

The vendored theme in _vendor/ is never edited. Hugo resolves templates by looking in the site’s own layouts/ before the theme’s, so a file at the same relative path shadows its theme counterpart. Customization happens by shadowing; the vendored copy stays pristine, and hugo mod vendor can regenerate it at any time without losing anything.

The cost of a shadow is that it copies theme markup at a point in time. When the theme upgrades, the shadow silently keeps the old markup until it is reconciled by hand, which is why the upgrade steps include a re-diff of every override.

Starting my documentation site

Thu, 16 Apr 2020 16:02:22 -0500

During this crazy time of corona virus quarantine, I figured it is time to get some things done. One of those is updating my documentation efforts. I was last using a system based upon asciidoc, pandoc, and git, with some work done in markdown and hugo. It worked fairly well but was cumbersome in many regards. I last reviewed methods in 2018, which was prior to my restarting school in Mathematics.