Detritus

Colophon

Meta notes about Detritus Notes. This is out of date since the migration from Bismuth Garden in 2023. (See also: About.)

Software

This site is built using Jekyll with custom layouts, plugins and scripts.

Bidirectional links are generated by a modified version of a plugin provided by the Digital garden Jekyll template.

I had two goals in mind when deciding how to build this website:

  • Short-term: Bootstrap the site using familiar tools.
  • Long-term: Build custom tools to fit my needs.

Jekyll was the best choice for me to get started: I’ve used it before, and it’s customisable enough to hack together something with unique requirements. In the process of building this site, I made some open-source contributions to Jekyll and the Rouge syntax highlighter.

Deployment process

I use this shellscript (named deploy.sh) to deploy changes to the website:

#!/bin/sh
set -eu

deploy() {
  rsync -achvz --progress --delete-after --exclude '.DS_Store' \
    "${BUILD_DIR}/" "${REMOTE_HOST}:${REMOTE_PATH}/" "$@"
}

printf '\n== DRY RUN ==\n'
deploy --dry-run

printf 'OK to deploy? [yN] '
read -r answer
[ "$answer" = 'y' ] && deploy

This script uses rsync to efficiently upload files from my local machine to the web server. First it performs a trial run (or dry run), showing which changes it would make; then, it prompts to confirm the changes.

The script requires three environment variables:

REMOTE_HOST
The hostname of the server, e.g. example.com. This can be an alias defined in ~/.ssh/config.
REMOTE_PATH
The full path to the website on the server, e.g. /var/www/example.com/public.
BUILD_DIR
The relative path to the files you want to upload, e.g. build.

The script makes two connections to the server because of the initial dry run. However, you can reuse the initial connection using SSH multiplexing.

To simplify the deployment process, I use a Makefile like this:

REMOTE_HOST = example.com
REMOTE_PATH = /var/www/example.com/public
export REMOTE_HOST
export REMOTE_PATH

build:
	JEKYLL_ENV=production bundle exec jekyll build -d build

deploy: build
	BUILD_PATH=build bin/deploy.sh

.PHONY: build deploy

With this, I can run make deploy to build and deploy changes to the website.

Fonts

Fonts used on this website include: