Colophon

The site doesn’t use any JavaScript or resources from other domains and there are no referral links or cookies.

Internals

This site is generated with a Rust program, from a directory structure that looks like this:

/pages/index.md
/pages/colophon.md
/pages/...
/stream/<year>/<month>/<short-link>.md
/notes/<subtopic>/<note>.md
/static/style.css

This structure makes it easy to update the site with a common text editor, as opposed to a web interface normally found in blog engines. There’s support for articles and updates, but it’s difficult to maintain a steady stream of substantial, write-once content, so those sources are disabled.

Pages and notes are written in Markdown, to make adding emphasis, code, headings, and links easy. The Rust program uses pulldown-cmark to convert the Markdown to HTML and Askama to incorporate that HTML into templates that provide a consistent look and feel for each page. Tokio provides a multi-threading runtime for regenerating notes, allowing I/Os to be scheduled asynchronously and multiple CPUs to help convert notes.

These notes are stored in a directory called site-content, which is supported by other directories, in a structure like this:

site-content/
site-out/
site-rs/
site-tools/

The site-out directory holds the HTML and CSS results of generating the website and is pushed to GitHub, which Netlify makes available across the internet. The HTML and CSS are small enough to leave un-minified, so it’s easier to inspect for curious visitors.

The Rust code and build tool are in site-rs and site-tools contains some shell scripts that build and publish the site, keeping the site-content and site-out directories in sync, like this publish.sh script:

#!/bin/sh

set -o pipefail
set -o errexit
set -o nounset

msg="$*"
len=`echo "$msg" | wc -c | sed -E 's/^ +//'`
if [ $len -gt 50 ]; then
	> /dev/stderr echo "error: message is $len characters"
	exit 1
fi

if [ -z "$(git -C site-content status --porcelain)" ]; then
	> /dev/stderr echo error: site-content is clean
	exit 1
fi

if [ -z "$(git -C site-out status --porcelain)" ]; then
	> /dev/stderr echo error: site-out is clean
	echo consider implementing automatic rebuild
	exit 1
fi

git -C site-content add .
git -C site-content commit -m "$msg"

git -C site-out add .
git -C site-out commit -m "$msg"
git -C site-out push

To make those scripts accessible, I made a short Makefile in the site’s parent directory:

default: all

all:
	site-tools/build.sh
	site-tools/publish.sh $(m)

build:
	site-tools/build.sh
b: build

amend:
	site-tools/amend.sh
a: amend

publish:
	site-tools/publish.sh $(m)
p: publish

.PHONY: default all build b amend a publish p

So building and publishing the site is as simple as make m='The commit message'.

The 404 page includes this HTML for a JavaScript-free site-specific search:

<form class="search" action="https://www.duckduckgo.com/" method="GET">
	<input name="sites" type="hidden" value="mattwidmann.net">
	<input name="q" type="text">
	<input type="submit" value="Search">
</form>

Updated on 31 July 2022.