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.

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.

Docsy on Werk Space

Document system

Overview

Theme Overrides

The principle