NatesNotes

Summary

A static notes site whose content lives in a separate repo — a plain folder of markdown I commit by hand. Frontmatter is optional, a bare file publishes, and ordered “courses” are assembled from the notes at build time.

Story

Every CMS I looked at inverted what I wanted: the notes live in the tool and you get them back as an export. Here the notes repo is symlinked in as content/ locally and checked out with a token in CI, and only notes/ and courses/ are read — private/, drafts and scratch are tracked in git and never published. Sequence comes from YAML manifests that list note slugs in order, and the direction of that reference is the whole design: notes never mention courses, courses point at notes, so reordering means editing one manifest. A slug matching no note fails the build on purpose. Decoupling the content also decoupled the deploy — a push to the notes repo fires a repository_dispatch that the site workflow builds on. Then DNS ate the most time: the apex records all have to be DNS only, because proxying hides the origin from GitHub, which then can’t issue a certificate, and the failure looks like a working site with a certificate error nobody warned you about.

Lessons

• Ceremony kills the habit. The moment publishing a note requires frontmatter, I stop writing notes and start maintaining a website.
• A dead link inside a numbered outline is worse than a missing page — the reader can’t tell whether they lost their place. Fail the build.
• Two expiring access tokens are load-bearing infrastructure with a silent failure mode: the site just stops updating and I’d notice weeks later.