Repository navigation
Fix footnotes and bring site-only edits back so wordpress.org/book can sync from here - #130
Draft
robertbpugh wants to merge 7 commits into
Draft
robertbpugh wants to merge 7 commits into
robertbpugh wants to merge 7 commits into
Conversation
Footnotes were written four different ways ([^Fn-1], [^fn-1], [fn^1], [Fn^1]) with no colon on the note itself, so GitHub, pandoc and Jetpack Markdown all showed them as plain text. They are now [^1] in the text and [^1]: at the note, which every Markdown renderer understands. Every reference has a matching note, and the count per chapter matches the live site. Co-Authored-By: Claude Opus 5.5 (1M context) <noreply@anthropic.com> Claude-Session: https://claude.ai/code/session_01MXBwXzdG2XPckiBuLKiFZ1
The Introduction was edited directly on wordpress.org/book and the edits never came back to this repo: tighter wording throughout, section headings, a dated 25% figure with its W3Techs source, and the Ecuador photo removed. This takes the site's text and keeps the repo's image files. Co-Authored-By: Claude Opus 5.5 (1M context) <noreply@anthropic.com> Claude-Session: https://claude.ai/code/session_01MXBwXzdG2XPckiBuLKiFZ1
These were edited on the live site but never in this repo, so syncing from the repo would have undone them: photo captions in A New Logo, Themes, Riding the Crazyhorse and Building Blocks chapter 4, section headings in Building Blocks chapters 1, 5 and 9, an https link, and a name initial. Co-Authored-By: Claude Opus 5.5 (1M context) <noreply@anthropic.com> Claude-Session: https://claude.ai/code/session_01MXBwXzdG2XPckiBuLKiFZ1
manifest.json follows the format of the wporg-markdown importer that wordpress.org already uses to keep its handbooks in sync with GitHub, so the book site can import chapters straight from trunk. Titles match the live posts exactly. bin/check-manifest.py checks every entry points at a real file and every footnote has a note, and runs on each PR. Co-Authored-By: Claude Opus 5.5 (1M context) <noreply@anthropic.com> Claude-Session: https://claude.ai/code/session_01MXBwXzdG2XPckiBuLKiFZ1
The importer resolves relative paths against the manifest's own URL, so the same manifest works from any branch. That lets the import be tested against a branch before it merges. Co-Authored-By: Claude Opus 5.5 (1M context) <noreply@anthropic.com> Claude-Session: https://claude.ai/code/session_01MXBwXzdG2XPckiBuLKiFZ1
The Maria Scarpello photo in the Introduction carried its caption twice after the conversion from the site; this keeps the one with the photographer link. bin/check-manifest.py now also fails when a chapter defines the same footnote note twice. Co-Authored-By: Claude Opus 5.5 (1M context) <noreply@anthropic.com> Claude-Session: https://claude.ai/code/session_01MXBwXzdG2XPckiBuLKiFZ1
This was referenced Oct 7, 2026
This file contains hidden or bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
Sign up for free
to join this conversation on GitHub.
Already have an account?
Sign in to comment
1 participant
Add this suggestion to a batch that can be applied as a single commit.This suggestion is invalid because no changes were made to the code.Suggestions cannot be applied while the pull request is closed.Suggestions cannot be applied while viewing a subset of changes.Only one suggestion per line can be applied in a batch.Add this suggestion to a batch that can be applied as a single commit.Applying suggestions on deleted lines is not supported.You must change the existing code in this line in order to create a valid suggestion.Outdated suggestions cannot be applied.This suggestion has been applied or marked resolved.Suggestions cannot be applied from pending reviews.Suggestions cannot be applied on multi-line comments.Suggestions cannot be applied while the pull request is queued to merge.Suggestion cannot be applied right now. Please check back later.
Footnotes in both volumes now render as real footnotes, and this repo now holds every edit that was only made on wordpress.org/book. That makes it safe for the site to import chapters straight from here.
Right now wordpress.org/book only changes when someone pastes an edit in by hand. A companion pull request to WordPress/wporg-book adds an importer, the same one wordpress.org uses to keep its handbooks in sync with GitHub. This PR gets the repo ready for it.
Footnotes. They were written four ways (
[^Fn-1],[^fn-1],[fn^1],[Fn^1]) with no colon on the note, so GitHub showed them as plain text. They're now[^1]and[^1]:, which GitHub, pandoc and the site's Markdown parser all understand. The live site has its own footnote bug: every chapter shows raw[footnote]text, because the plugin behind that shortcode is gone. Importing from here fixes that too.Edits that only existed on the site. I rendered all 61 chapters the way the importer will and compared them with the live posts. For each difference I checked whether the site's wording had ever been in this repo's history. If it had, the site is just behind. If it never had, someone edited the site directly, and I brought that edit here:
The other differences are the site missing this repo's later fixes, such as #108's tense change in Thesis and #127's copyedit, which the import will bring to the site.
manifest.json maps each chapter file to its post on the site, in the importer's format. Titles match the live posts exactly. The six Part pages (haiku and illustration) aren't in this repo, so they stay as they are.
bin/check-manifest.py checks that each manifest entry points at a real file and every footnote has a note. A new workflow runs it on each pull request.
This is stacked on #129, so it includes that change until #129 merges.
Testing
python3 bin/check-manifest.pypasses: 61 chapters, footnotes OK.🤖 Generated with Claude Code
https://claude.ai/code/session_01MXBwXzdG2XPckiBuLKiFZ1