Skip to content

How to Add a Journal Entry

Anyone can add an entry. No special tools needed — you can do this straight from GitHub.com.

This site is public. Even though the repo is private, the deployed site (https://sturdy-canary.pages.dev) is visible to anyone with the link — don't assume it's protected. Never put passwords, IP addresses, SSH details, or other sensitive/controlled info in a journal post or docs page. That kind of content belongs in the internal-docs/ folder at the repo root instead (not inside docs-site/), which never gets built into the public site — browse it directly on GitHub or in your local clone.

The short version

  1. Go to the repo, switch to the 2027 branch, and open the folder docs-site/docs/blog/posts/.
  2. Click Add file → Create new file.
  3. Name it YYYY-MM-DD-short-title.md — for example 2026-08-11-migrated-auth-service.md. The date must be the actual date and must match the front matter date below, or the plugin will error.
  4. Paste this template at the top, then write whatever you want underneath it:
---
date: 2026-08-11
authors:
  - your-github-username
categories:
  - Progress
---

# Migrated the auth service

Whatever happened today. What you tried, what broke, what you decided, links to
commits/PRs, anything worth remembering later.

<!-- more -->

The part above the `<!-- more -->` line shows as a preview on the journal index page.
Everything below it only shows when someone opens the full post.
  1. Scroll down and commit directly to 2027 (or open a pull request into 2027 first if you'd rather have someone glance at it).
  2. Done. The site rebuilds itself within about a minute — no other steps.

Categories

Reuse categories so entries group together on the journal page — e.g. Components, Tech Specs, Progress, General. You can invent new ones any time; they show up automatically.

Never use a category (or any public post) for passwords, IPs, or SSH/network details — see the note at the top of this page.

Editing locally instead

If you'd rather work in your own editor:

git clone -b 2027 https://github.com/AF-RFDF/sturdy-canary.git
cd sturdy-canary/docs-site
pip install -r requirements.txt
mkdocs serve       # live preview at http://127.0.0.1:8000

Add your post file under docs-site/docs/blog/posts/, preview it, then git add, git commit, git push.

How the site deploys

You don't deploy by hand. The site is hosted on Cloudflare Pages at https://sturdy-canary.pages.dev. Every push to 2027 triggers a Cloudflare build: it runs mkdocs build in docs-site/ and publishes the result, usually within 2–3 minutes. Nothing is stored as a GitHub artifact, and the site stays up between deploys.

To check a build or redeploy without changing any files: in the Cloudflare dashboard go to Workers & Pages → sturdy-canary → Deployments. Open a deployment for its build log, or use the ⋯ menu on the latest one and choose Retry deployment.