blog: how this site works — publishing pipeline post + first index entry

2 files changed, 70 insertions, 3 deletions

diff --git a/blog/how-this-site-works.qmd b/blog/how-this-site-works.qmd
new file mode 100644
index 0000000..00b9656
--- /dev/null
+++ b/blog/how-this-site-works.qmd
@@ -0,0 +1,69 @@
+---
+title: "How This Site Works"
+date: "2026-07-31"
+---
+
+## WHY
+
+I wanted publishing to be easy, and I wanted this site to
+work from a terminal. You should be able to `curl jayrup.me`
+and read the whole thing as plain text — no browser needed.
+
+This is the pipeline that makes that happen.
+
+## HOW
+
+Everything lives in one git repo, hosted on meru, my server
+at home. That repo is the source of truth. My agents on
+archbook (my laptop) and voidlaptop (an old laptop I turned
+into a server) push to it — and a push to main is a deploy.
+
+The repo is public, so the site and the code behind it are
+both out in the open.
+
+## STACK
+
+- every page is a `.qmd` file
+- Quarto renders each one twice: HTML for browsers,
+  plain text for curl
+- a post-receive hook on meru runs that render inside a
+  Docker container, then rsyncs the result to the VPS
+- nginx on the VPS checks the user-agent: curl gets
+  `.txt`, browsers get `.html`
+
+## SOURCE OF TRUTH
+
+The repo is self-contained and public — browse the
+source or clone it:
+
+- Web: [git.jayrup.me](https://git.jayrup.me)
+- Clone: `git clone https://git.jayrup.me/git/homepage.git`
+
+`blog/` holds these posts as flat `.qmd` files;
+`blog/index.qmd` is the listing page, newest first.
+
+## PUBLISHING
+
+1. Write `blog/<slug>.qmd` with a title and date
+2. Add an entry to `blog/index.qmd`
+3. Push to meru — the post-receive hook renders the site
+   in a Docker container and rsyncs it to the VPS
+4. Verify: `curl https://jayrup.me/blog/<slug>` —
+   you'll get plain text, which is the point
+
+## WHY THIS WORKS
+
+The deploy script finds every `.qmd` recursively, so new
+posts need zero script changes. Builds run from a git
+snapshot of the exact commit you pushed, so what goes
+live is always what's in the repo. And each deploy
+stamps `last-deploy.txt` with the commit, so the site
+shows you what's actually live.
+
+That's the whole pipeline: a repo, a render script, and
+nginx. The code is all in the repo if you want to poke
+at it.
+
+--------------------------------------------------
+
+BACK: [BLOG](https://jayrup.me/blog) | [HOME](https://jayrup.me)
diff --git a/blog/index.qmd b/blog/index.qmd
index cdd3563..528afba 100644
--- a/blog/index.qmd
+++ b/blog/index.qmd
@@ -5,9 +5,7 @@ title: "Jayrup Nakawala | Blog"
 RANDOM THOUGHTS, EXPERIMENTS, AND SYSTEMS NOTES
 --------------------------------------------------
 
-_No posts yet — coming soon._
-
-hello
+- [How this site works](https://jayrup.me/blog/how-this-site-works) — 2026-07-31
 
 --------------------------------------------------