Repository navigation
Keep chapters in sync with the WordPress/library repo - #2
Merged
Merged
Conversation
robertbpugh
marked this pull request as ready for review
October 13, 2026 23:59
Adds a chapter importer built on the wporg-markdown importer that developer.wordpress.org uses, following its theme's pattern. The library's manifest.json maps each chapter file to an existing post slug; the importer updates only those posts' content and titles. Differences from the shared importer, so it is safe on a book: - never creates posts, so a manifest typo can't publish a stray post - only imports chapters in the current manifest - renames Jetpack Markdown footnote anchors (fn:1), which KSES strips - applies the manifest title even when the file is unchanged - stores the ETag only after the post saves, so failures retry - strips the volume title and chapter heading the site already shows - points relative image paths at raw.githubusercontent.com - stays off until wporg_book_import_enabled is set; wp book import --dry-run reports what would change first Co-Authored-By: Claude Opus 5.5 (1M context) <noreply@anthropic.com> Claude-Session: https://claude.ai/code/session_01MXBwXzdG2XPckiBuLKiFZ1
- Read and validate the whole manifest before writing anything, and reject entries whose source is outside WordPress/library. Replaces the shared importer's manifest handling, which writes any meta the manifest lists and exits WP-CLI on errors. - Fetch with wp_safe_remote_get(), without following chapter redirects. - Exit non-zero from wp book import when a chapter fails or is skipped. - Show the overwrite warning in the block editor, not just the classic one. - Use the same published-post lookup for dry runs and imports. - Keep query strings when resolving image paths, and resolve root-relative paths against the repo root. - Rename to class-chapter-importer.php and create it in functions.php. Co-Authored-By: Claude Opus 5.5 (1M context) <noreply@anthropic.com> Claude-Session: https://claude.ai/code/session_01MXBwXzdG2XPckiBuLKiFZ1
- A blank slug made WP_Query drop the name filter and match the newest post, so slugs must now be non-empty and already sanitized. - Source URLs are checked after decoding, so %2e%2e can't climb out of WordPress/library. - wp book import --dry-run exits non-zero when a chapter can't be fetched or has no post. Co-Authored-By: Claude Opus 5.5 (1M context) <noreply@anthropic.com> Claude-Session: https://claude.ai/code/session_01MXBwXzdG2XPckiBuLKiFZ1
Links to the book showed up bare in Slack and on social sites, because the theme never turned on Jetpack's Open Graph tags the way the other wordpress.org themes do. - Turn them on with jetpack_enable_open_graph. - Describe both volumes on the home page; the site description only covers Volume 2. - Use a chapter's first image, since Jetpack skips images without a height attribute and no chapter image has one. Chapters without images fall back to the wordpress.org default image. Co-Authored-By: Claude Opus 5.5 (1M context) <noreply@anthropic.com> Claude-Session: https://claude.ai/code/session_012uTEZEmU5AYzhgPvhx3HvJ
site-branding.php strips -256x256 style sizes from og:image, which turned chapter 8's Gutenberg icon into a 404. Images named that way are passed over, falling back to the default image. Also drop the forced large Twitter card, since some first images are too small for one, and skip sources that don't survive esc_url_raw. Co-Authored-By: Claude Opus 5.5 (1M context) <noreply@anthropic.com> Claude-Session: https://claude.ai/code/session_012uTEZEmU5AYzhgPvhx3HvJ
obenland
force-pushed
the
add/chapter-import
branch
from
October 16, 2026 17:05
24eb7d8 to
dbbf3aa
Compare
Member
|
Member
|
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
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.
This makes wordpress.org/book pull chapter edits from WordPress/library on its own, so nobody has to paste them in by hand any more.
Konstantin, this is the follow-up to the GPL chapter you updated by hand. It uses the same wporg-markdown importer as the handbooks, wired up the way wporg-developer's theme does it. The library now has a
manifest.json(WordPress/library#130) mapping each of the 61 chapter files to the slug of its existing post here.What it does
Each hourly run reads the manifest, then updates each listed chapter whose Markdown changed. It only touches post content and title. Dates, slugs, the dated permalinks and the
mb_vol/mb_part/mb_chapternavigation meta stay as they are.It also fixes footnotes on every chapter. The posts still contain
[footnote]shortcodes that nothing renders any more, so readers see the raw brackets. The imported chapters use real footnotes with working links both ways.Where it differs from the shared importer
The handbook defaults would misbehave on a book, so this subclass reads the manifest itself and changes seven things:
wp_safe_remote_get(), and the manifest can't set any other post meta.fn:1, and KSES strips#fn:1links as a bad protocol, so they becomefn-{post ID}-1.Sharing previews
Links to the book show up bare in Slack and on social sites, because this theme never turned on Jetpack's Open Graph tags the way the other wordpress.org themes do. This adds them:
site-branding.php.These go live with the deploy and don't depend on the import being switched on.
Rolling it out
Nothing changes when this deploys. The import stays off until the option below is set.
Jetpack is already active on the book site. From the wordpress.org web root:
The last command turns on the hourly import, which schedules itself on the next page load.
A dry run is optional, since the import has already run against copies of all 61 live chapters (see Testing). If you want one,
wp --url=https://wordpress.org/book/ book import --dry-runlists each chapter, whether it would change, and its word count before and after, without writing anything.library#130 has merged, so the manifest is on trunk.
Testing
I ran it in wp-env with copies of all 67 live posts, importing from the #130 branch:
mb_*meta are unchanged. Volume 2 posts keep their chapter titles rather than the volume title.wp book importexits non-zero when any chapter fails or is skipped.phpcswith the wporg ruleset is clean.The lint check on this PR fails before it reaches the code.
composer installcan't fetch the wporg-mu-plugins commit pinned incomposer.lock, which is no longer on its build branch, so this needs a lockfile refresh on trunk.🤖 Generated with Claude Code
https://claude.ai/code/session_01MXBwXzdG2XPckiBuLKiFZ1