git » homepage.git » commit 18a2920

diff --git a/AGENTS.md b/AGENTS.md
new file mode 100644
index 0000000..afbacdc
--- /dev/null
+++ b/AGENTS.md
@@ -0,0 +1,38 @@
+# Agent Handbook
+
+Welcome! This document describes how automated helpers should operate when working on the `homepage` repository.
+
+## Required Reading Order
+
+1. Skim this `AGENTS.md` document in full before doing anything else.
+2. Re-read the top-level `README.md` to confirm runtime expectations and external dependencies.
+3. Only then begin planning or modifying files.
+
+## Operating Principles
+
+- Prefer incremental changes over sweeping rewrites. Modify existing files in place and preserve user-written content.
+- The repo targets standard POSIX tooling (`make`, `awk`, `rsync`, `cmark-gfm`); avoid introducing extra build dependencies.
+- Always run `make assets && make` after touching Markdown, templates, or build scripts unless instructed otherwise.
+- `make deploy` is reserved for publishing—never call it unless explicitly asked and the git worktree is clean.
+- Ensure `tools/mdlink2html.awk` and build helpers continue to support wiki-style intra-site links.
+- Keep updates idempotent: don’t delete generated output or vendor directories unless instructed.
+
+## Blog Post Style Guidelines
+
+When drafting or editing Markdown articles under `md_export/`:
+
+- Begin with a level-one heading that matches the filename (e.g., `# HomepageDesign`).
+- Use short, conversational paragraphs aimed at technical readers; prefer present tense and active voice.
+- Link to related wiki pages using relative Markdown links (`./PageName.md`) so the generator can rewrite them.
+- For historical notes, include dates or context in plain prose rather than YAML front matter.
+- Tables should follow GitHub-style pipe syntax; the build pipeline will handle them.
+- Avoid HTML unless necessary for layout—stick to Markdown headings, lists, and links.
+- Signatures are not required; rely on the build footer for publication metadata.
+
+## Communication Notes
+
+- If you encounter unexpected files, stop and ask rather than deleting them.
+- Mention any new helper scripts or tooling in commit notes and `README.md` when appropriate.
+- Keep responses in a friendly teammate tone; summarize actions, call out verification steps, and suggest next moves.
+
+Thanks for keeping the blog tidy and consistent!
diff --git a/Makefile b/Makefile
index 40d7346..385b69b 100644
--- a/Makefile
+++ b/Makefile
@@ -1,6 +1,6 @@
 .PHONY: all assets clean deploy help tree check-git-clean
 
-SRC := md_export
+SRC := md
 OUT := out
 HEAD := tpl/head.html
 FOOT := tpl/foot.html
@@ -16,25 +16,16 @@ HTML := $(patsubst $(SRC)/%.md,$(OUT)/%.html,$(MD_FILES))
 all: $(OUT)/style.css $(HTML)
 
 $(OUT)/style.css: $(CSS)
-	@mkdir -p $(OUT)
-	@cp $(CSS) $@
+	mkdir -p $(OUT)
+	cp $(CSS) $@
 
 $(OUT):
-	@mkdir -p $(OUT)
+	mkdir -p $(OUT)
 
 $(OUT)/%.html: $(SRC)/%.md $(HEAD) $(FOOT) tools/mdlink2html.awk $(BUILDINFO) | $(OUT)
-	@mkdir -p $(@D)
-	@awk -f tools/mdlink2html.awk $< > $@.rewritten.md
-	@if [ ! -x $(MD2HTML) ]; then \
-		echo "Missing $(MD2HTML). Build it with:"; \
-		echo "  git clone https://github.com/github/cmark-gfm vendor/cmark-gfm"; \
-		echo "  cmake -S vendor/cmark-gfm -B vendor/cmark-gfm/build"; \
-		echo "  cmake --build vendor/cmark-gfm/build"; \
-		echo "  cp vendor/cmark-gfm/build/src/cmark-gfm bin/"; \
-		echo "Then rerun make with MD2HTML=bin/cmark-gfm"; \
-		exit 1; \
-	fi
-	@$(MD2HTML) $(CMARK_FLAGS) $@.rewritten.md > $@.body.html
+	mkdir -p $(@D)
+	awk -f tools/mdlink2html.awk $< > $@.rewritten.md
+	$(MD2HTML) $(CMARK_FLAGS) $@.rewritten.md > $@.body.html
 	@css_prefix="$$(dirname "$@" | sed -e 's#^$(OUT)##' -e 's#^/##' -e 's#[^/][^/]*#../#g')"; \
 		page_title=$$(basename "$<" .md); \
 		build_info=$$($(BUILDINFO)); \
@@ -44,11 +35,11 @@ $(OUT)/%.html: $(SRC)/%.md $(HEAD) $(FOOT) tools/mdlink2html.awk $(BUILDINFO) |
 		sed -e "s|@CSS@|$${css_prefix}|g" -e "s|@BUILDINFO@|$${build_info_esc}|g" -e "s|@TITLE@|$${page_title_esc}|g" $(FOOT) > $@.foot.html; \
 		cat $@.head.html $@.body.html $@.foot.html > $@; \
 		rm -f $@.head.html $@.foot.html
-	@rm -f $@.rewritten.md $@.body.html
+	rm -f $@.rewritten.md $@.body.html
 
 assets:
-	@mkdir -p $(OUT)
-	@rsync -a --include='*/' --exclude='*.md' --exclude='*.MD' --prune-empty-dirs $(SRC)/ $(OUT)/
+	mkdir -p $(OUT)
+	rsync -a --include='*/' --exclude='*.md' --exclude='*.MD' --prune-empty-dirs $(SRC)/ $(OUT)/
 
 deploy: check-git-clean assets all
 	@if [ -z "$(DEPLOY_HOST)" ]; then \
@@ -58,8 +49,8 @@ deploy: check-git-clean assets all
 	rsync -a $(OUT)/ $(DEPLOY_HOST)
 
 tree:
-	@printf 'Markdown sources: ' && find $(SRC) -type f -name '*.md' | wc -l
-	@printf 'HTML outputs:   ' && if [ -d $(OUT) ]; then find $(OUT) -type f -name '*.html' | wc -l; else echo 0; fi
+	printf 'Markdown sources: ' && find $(SRC) -type f -name '*.md' | wc -l
+	printf 'HTML outputs:   ' && if [ -d $(OUT) ]; then find $(OUT) -type f -name '*.html' | wc -l; else echo 0; fi
 
 clean:
 	rm -rf $(OUT)
@@ -74,7 +65,7 @@ help:
 	@echo '  (deploy refuses to run with a dirty git worktree)'
 
 check-git-clean:
-	@if [ -n "$$(git status --porcelain)" ]; then \
+	if [ -n "$$(git status --porcelain)" ]; then \
 		echo 'Refusing to build: git worktree has uncommitted changes.'; \
 		git status --short; \
 		exit 1; \
diff --git a/README.md b/README.md
index 516ab1d..7eebf65 100644
--- a/README.md
+++ b/README.md
@@ -2,6 +2,8 @@
 
 This converts Markdown from `md_export/` to HTML in `out/` and can deploy the result to your shared host.
 
+> AI helpers: read `AGENTS.md` before making changes.
+
 ## Usage
 make assets && make
 xdg-open out/index.html  # or open on macOS
diff --git a/md_export/AsyncAwaitGotchas.md b/md/AsyncAwaitGotchas.md
similarity index 100%
rename from md_export/AsyncAwaitGotchas.md
rename to md/AsyncAwaitGotchas.md
diff --git a/md_export/CoffeeTime.md b/md/CoffeeTime.md
similarity index 100%
rename from md_export/CoffeeTime.md
rename to md/CoffeeTime.md
diff --git a/md_export/CoffeeTime/coffee_float_right_200px.jpg b/md/CoffeeTime/coffee_float_right_200px.jpg
similarity index 100%
rename from md_export/CoffeeTime/coffee_float_right_200px.jpg
rename to md/CoffeeTime/coffee_float_right_200px.jpg
diff --git a/md_export/ConsultingPractice.md b/md/ConsultingPractice.md
similarity index 100%
rename from md_export/ConsultingPractice.md
rename to md/ConsultingPractice.md
diff --git a/md_export/FairDivision.md b/md/FairDivision.md
similarity index 100%
rename from md_export/FairDivision.md
rename to md/FairDivision.md
diff --git a/md_export/GitOnSharedHost.md b/md/GitOnSharedHost.md
similarity index 100%
rename from md_export/GitOnSharedHost.md
rename to md/GitOnSharedHost.md
diff --git a/md_export/Home.md b/md/Home.md
similarity index 95%
rename from md_export/Home.md
rename to md/Home.md
index a2992e7..3de48c9 100644
--- a/md_export/Home.md
+++ b/md/Home.md
@@ -22,6 +22,7 @@ Updates
 -------
 | Date       | Note                                                                                                                                       |
 |:-----------|:-------------------------------------------------------------------------------------------------------------------------------------------|
+| 2025-10-07 | Added [HomepageDesign](./HomepageDesign.md) to document the move from Zim exports to the current make + cmark workflow.                   |
 | 2022-12-02 | Added [GitOnSharedHost](./GitOnSharedHost.md) to describe setting up a read-only Git repo on Dreamhost.                                    |
 | 2021-07-01 | Added [HomePhotos](./HomePhotos.md) to document family media archival strategy.                                                            |
 | 2021-06-24 | Added [AsyncAwaitGotchas](./AsyncAwaitGotchas.md), about obscure async/await JavaScript errors in Google Chrome.                           |
@@ -36,4 +37,3 @@ Updates
 | 2020-11-09 | Added [FairDivision](./FairDivision.md).                                                                                                   |
 | 2020-11-02 | Deployed new [Zim](https://zim-wiki.org/)-based site and established redirects from previous URLs.                                         |
 
-
diff --git a/md_export/Home/headshot_2018_float_right_200px.jpg b/md/Home/headshot_2018_float_right_200px.jpg
similarity index 100%
rename from md_export/Home/headshot_2018_float_right_200px.jpg
rename to md/Home/headshot_2018_float_right_200px.jpg
diff --git a/md_export/HomePhotos.md b/md/HomePhotos.md
similarity index 100%
rename from md_export/HomePhotos.md
rename to md/HomePhotos.md
diff --git a/md_export/HomePhotos/Dockerfile b/md/HomePhotos/Dockerfile
similarity index 100%
rename from md_export/HomePhotos/Dockerfile
rename to md/HomePhotos/Dockerfile
diff --git a/md_export/HomePhotos/photoprism.png b/md/HomePhotos/photoprism.png
similarity index 100%
rename from md_export/HomePhotos/photoprism.png
rename to md/HomePhotos/photoprism.png
diff --git a/md/HomepageDesign.md b/md/HomepageDesign.md
new file mode 100644
index 0000000..0ab7939
--- /dev/null
+++ b/md/HomepageDesign.md
@@ -0,0 +1,15 @@
+# HomepageDesign
+
+This page explains how my homepage moved from a Zim-based wiki to the minimal static generator that now publishes these pages.
+
+## Zim beginnings
+
+For years I maintained this site directly out of [Zim](https://zim-wiki.org/). Zim made it easy to sketch ideas, follow wiki links, and export the whole notebook as HTML whenever I wanted to share an update. The design and layout you see in older posts originated in that exported theme, including the ornate background and the habit of organizing pages like a personal wiki.
+
+## Static site generator today
+
+Today the site is rebuilt with a tiny static site generator that lives right alongside the content. Everything under `md_export/` is authored in Markdown, and a `make` pipeline rewrites wiki links, runs [`cmark-gfm`](https://github.com/github/cmark-gfm) to render HTML, wraps the result in a shared template, and copies any non-Markdown assets into the `out/` directory. Deploys are a simple `make deploy`, which rsyncs the generated files to my DreamHost account. The build footer shows who published the site, when, and from which git revision.
+
+## Why change?
+
+Moving to this generator means the whole site is version-controlled and scriptable. I can check diffs, branch drafts, and automate deployment from any machine (or even Cosmopolitan builds someday). It keeps Zim's information architecture while making the publishing workflow reproducible. If you're curious about the raw files or the build logic, the [homepage repo](https://tailrecursion.com/git-arr/r/homepage.git/) is public.
diff --git a/md_export/Lisp.md b/md/Lisp.md
similarity index 100%
rename from md_export/Lisp.md
rename to md/Lisp.md
diff --git a/md_export/Lisp/CommonLisp.md b/md/Lisp/CommonLisp.md
similarity index 100%
rename from md_export/Lisp/CommonLisp.md
rename to md/Lisp/CommonLisp.md
diff --git a/md_export/Lisp/CommonLispIteration.md b/md/Lisp/CommonLispIteration.md
similarity index 100%
rename from md_export/Lisp/CommonLispIteration.md
rename to md/Lisp/CommonLispIteration.md
diff --git a/md_export/Lisp/GherkinHistory.md b/md/Lisp/GherkinHistory.md
similarity index 100%
rename from md_export/Lisp/GherkinHistory.md
rename to md/Lisp/GherkinHistory.md
diff --git a/md_export/Lisp/GherkinHistory/IMG_2485.JPG b/md/Lisp/GherkinHistory/IMG_2485.JPG
similarity index 100%
rename from md_export/Lisp/GherkinHistory/IMG_2485.JPG
rename to md/Lisp/GherkinHistory/IMG_2485.JPG
diff --git a/md_export/Lisp/GherkinHistory/alan_wearing_gherkin_shirt.jpg b/md/Lisp/GherkinHistory/alan_wearing_gherkin_shirt.jpg
similarity index 100%
rename from md_export/Lisp/GherkinHistory/alan_wearing_gherkin_shirt.jpg
rename to md/Lisp/GherkinHistory/alan_wearing_gherkin_shirt.jpg
diff --git a/md_export/PersonalBackground.md b/md/PersonalBackground.md
similarity index 100%
rename from md_export/PersonalBackground.md
rename to md/PersonalBackground.md
diff --git a/md_export/RandallRDipert.md b/md/RandallRDipert.md
similarity index 100%
rename from md_export/RandallRDipert.md
rename to md/RandallRDipert.md
diff --git a/md_export/TechSolutions.md b/md/TechSolutions.md
similarity index 100%
rename from md_export/TechSolutions.md
rename to md/TechSolutions.md
diff --git a/md_export/TechWorks.md b/md/TechWorks.md
similarity index 100%
rename from md_export/TechWorks.md
rename to md/TechWorks.md
diff --git a/md_export/TechWorks/2015-04-20_ClojureWestBoot.pdf b/md/TechWorks/2015-04-20_ClojureWestBoot.pdf
similarity index 100%
rename from md_export/TechWorks/2015-04-20_ClojureWestBoot.pdf
rename to md/TechWorks/2015-04-20_ClojureWestBoot.pdf
diff --git a/md_export/TechWorks/2020-01-28-RStudio-Conf-Integration-Testing-ePoster.pdf b/md/TechWorks/2020-01-28-RStudio-Conf-Integration-Testing-ePoster.pdf
similarity index 100%
rename from md_export/TechWorks/2020-01-28-RStudio-Conf-Integration-Testing-ePoster.pdf
rename to md/TechWorks/2020-01-28-RStudio-Conf-Integration-Testing-ePoster.pdf
diff --git a/md_export/TechWorks/Dipert-FRP_in_ClojureScript_with_Javelin.pdf b/md/TechWorks/Dipert-FRP_in_ClojureScript_with_Javelin.pdf
similarity index 100%
rename from md_export/TechWorks/Dipert-FRP_in_ClojureScript_with_Javelin.pdf
rename to md/TechWorks/Dipert-FRP_in_ClojureScript_with_Javelin.pdf
diff --git a/md_export/TechWorks/Dipert-ProgrammingWithValues.pdf b/md/TechWorks/Dipert-ProgrammingWithValues.pdf
similarity index 100%
rename from md_export/TechWorks/Dipert-ProgrammingWithValues.pdf
rename to md/TechWorks/Dipert-ProgrammingWithValues.pdf
diff --git a/md_export/TechWorks/jacl-demo-els-2020.pdf b/md/TechWorks/jacl-demo-els-2020.pdf
similarity index 100%
rename from md_export/TechWorks/jacl-demo-els-2020.pdf
rename to md/TechWorks/jacl-demo-els-2020.pdf
diff --git a/md_export/WellReadUndergrad.md b/md/WellReadUndergrad.md
similarity index 100%
rename from md_export/WellReadUndergrad.md
rename to md/WellReadUndergrad.md
diff --git a/md_export/WellReadUndergrad/phil-lt5.doc b/md/WellReadUndergrad/phil-lt5.doc
similarity index 100%
rename from md_export/WellReadUndergrad/phil-lt5.doc
rename to md/WellReadUndergrad/phil-lt5.doc
diff --git a/md_export/WellReadUndergrad/phil-lt5.docx b/md/WellReadUndergrad/phil-lt5.docx
similarity index 100%
rename from md_export/WellReadUndergrad/phil-lt5.docx
rename to md/WellReadUndergrad/phil-lt5.docx