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/
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-tools contains some shell scripts that build and publish the site, keeping the
site-out directories in sync, like this
#!/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'.
<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.