@geekity/plugin-wordpress 0.1.1 → 0.3.0

package/README.md

@@ -3,8 +3,10 @@
 A [Geekity CMS](../cms/README.md) plugin for a site that moved from the
 WordPress ActivityPub plugin. It answers the old plugin's inbox and collection
 paths until every follower's server has refetched the actor, records when each
-path was last asked for, and adds `geekity import wordpress-actor`, which
-brings each person's key pair, actor id and followers across.
+path was last asked for, and adds two imports: `geekity import wordpress`,
+which brings the content of a WordPress export across, and
+`geekity import wordpress-actor`, which brings each person's key pair, actor id
+and followers across.
 
 A site born on the CMS never needs it. Stored actor ids, post object ids,
 WebFinger aliases and the feed and archive layout are the site's own and are in
@@ -37,16 +39,18 @@ under `/admin/plugins`:
 docker compose exec geekity geekity plugin add @geekity/plugin-wordpress
 ```
 
-`geekity import wordpress-actor` works as soon as the plugin is installed. The
-old paths are served only while the plugin is enabled under `/admin/plugins`,
-and disabling it takes them away on the next request, with nothing restarted.
+Both imports work as soon as the plugin is installed. The
+old paths, and the redirects from WordPress media URLs, are served only while
+the plugin is enabled under `/admin/plugins`, and disabling it takes them away
+on the next request, with nothing restarted.
 
 The plugin keeps two files in `data/plugins/@geekity/plugin-wordpress/`:
 
-| File            | What it holds                                                                                                               |
-| --------------- | --------------------------------------------------------------------------------------------------------------------------- |
-| `actors.json`   | Each username and the number WordPress gave that person's actor, which the old paths are built from. Written by the import. |
-| `requests.json` | When each old path was last asked for, per user, and when the shared inbox was. Losing it resets what the screen says.      |
+| File            | What it holds                                                                                                                                                                            |
+| --------------- | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
+| `actors.json`   | Each username and the number WordPress gave that person's actor, which the old paths are built from. Written by the import.                                                              |
+| `requests.json` | When each old path was last asked for, per user, and when the shared inbox was. Losing it resets what the screen says.                                                                   |
+| `import.json`   | A hash of every file `geekity import wordpress` wrote, by path, and each `site.json`, `media.json` and redirect key it set. Losing it makes every imported file a clash on the next run. |
 
 ## The old paths
 
@@ -71,6 +75,225 @@ plugin's screen under Plugins, `/admin/plugins/@geekity/plugin-wordpress`,
 lists each path with that instant, or _Never_. Once every follower's server has
 refetched the actor, nothing asks any more, and the plugin can be disabled.
 
+## Bringing the content across
+
+`geekity import wordpress` reads the WXR file WordPress writes under Tools >
+Export (or `wp export`) and writes what it holds into the content directory:
+
+```sh
+geekity import wordpress example.WordPress.2026-10-08.xml \
+  --uploads ./wp-content/uploads \
+  --origins https://staging.example.com
+```
+
+`--uploads` is a copy of the site's `wp-content/uploads` (an export carries
+no files), and `--origins` names any other host the posts wrote media URLs
+on, such as the staging host the site was built on, comma-separated. Both are
+optional; see [Media](#media).
+
+A file that is not a WordPress export is refused before anything is written,
+with each problem named, and the command exits 1.
+
+The command prints the totals, then one tab-separated row per item: its
+outcome, post type, WordPress id, title, the file it went to, and why.
+
+| Outcome     | What it means                                                                                            |
+| ----------- | -------------------------------------------------------------------------------------------------------- |
+| `written`   | The file is new, was changed on WordPress since the last run, or was removed here and is written again.  |
+| `unchanged` | The file already holds what WordPress has.                                                               |
+| `kept`      | The file was edited on this site and WordPress has not changed it since. The edit stays.                 |
+| `conflict`  | The file was edited on this site and changed on WordPress too. The edit stays; the row gives both dates. |
+| `clash`     | A file the import never wrote is at the path. It is left alone.                                          |
+| `skipped`   | The item has no Geekity counterpart, such as a revision, a menu or the ActivityPub plugin's records.     |
+| `warned`    | The item was imported, with something the operator should check.                                         |
+
+**Run it as often as you like.** Two runs over one export leave the content
+directory byte for byte as one run did, and a run over a newer export picks up
+what was added or edited on WordPress since. The import never writes over a file
+it did not write, and never deletes one, so a site can layer its own fixes on
+top of an import. To take WordPress's side of a conflict, remove the file and
+run the import again.
+
+### Posts and pages
+
+Each post becomes `posts/YYYY-MM-DD-slug.md`, dated by its local publish date,
+and each page becomes `pages/slug.md`. The front matter keeps what readers,
+feed readers and followers already know of it:
+
+| Key             | Where it comes from                                                                                                                                                                              |
+| --------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ |
+| `permalink`     | The URL WordPress served, from the export's link. A draft has none yet, so it gets the one the published posts' structure gives it; a page gets its parents' slugs.                              |
+| `redirect_from` | The URLs the post had before WordPress renamed or redated it: its permalink with each `_wp_old_slug` in place of its slug, and each `_wp_old_date` in place of its date.                         |
+| `date`          | `post_date_gmt`. A draft WordPress never dated has none.                                                                                                                                         |
+| `updated`       | `post_modified_gmt`, when it differs from the date.                                                                                                                                              |
+| `tags`          | The post's tags, by name.                                                                                                                                                                        |
+| `categories`    | The post's categories, by name.                                                                                                                                                                  |
+| `draft`         | `true` for a draft, a pending post, and a private or password-protected one, which the report names. A scheduled post keeps its date and publishes then.                                         |
+| `author`        | The WordPress login, when the site has a user by that name. A post by any other login has no author, and the report names it.                                                                    |
+| `in-reply-to`   | The URL an ActivityPub plugin reply block answers.                                                                                                                                               |
+| `activitypub`   | On a published post, `id` is `https://example.com/?p=ID`, the object id the ActivityPub plugin served. A post the plugin federated (`activitypub_status` is `federated`) also has `published`.   |
+| `guid`          | The WordPress guid, when it is not the post's `?p=` address, so feed readers see no old post as new.                                                                                             |
+| `migrated`      | `true` on everything but a scheduled post, so its arrival here, or a draft's publication later, sends nothing to anyone. A scheduled post publishes here as news, as it would have on WordPress. |
+
+**Expect one difference in a feed diff.** WordPress prints the escapes in a
+non-ASCII slug in lower case, as in `/2026/07/i-%e2%99%a5-rss/`. The site
+prints them in upper case, as in `/2026/07/i-%E2%99%A5-rss/`, in the RSS,
+Atom and JSON feeds, the comments feeds, `rel="canonical"`, `og:url`, the
+sitemap and the ActivityStreams `url`. RFC 3986 makes the two spellings the
+same URL, and both answer `200` with the post. A feed reader keys an item on
+its `guid`, which the import keeps, so the post does not show as new.
+
+A post in the status format has no title, so it reads as a note. The page
+WordPress served at the home URL becomes `homepage` in `_data/site.json`. The
+import sets that key only while the site has not set it, or still holds what
+the import last set.
+
+The body becomes Markdown. Block comments go, a classic post's line breaks
+become paragraphs as WordPress showed them, and a YouTube or Vimeo iframe or
+embed becomes the video's URL on a line of its own, which the site plays.
+What Markdown cannot say stays HTML: other iframes, a figure with a caption, a
+table with spans, and an element carrying a `style` or microformats class.
+`<!--more-->` stays where it was. Media URLs point at the files under
+`/uploads/`, as [Media](#media) describes.
+
+### Media
+
+Each attachment's original is copied from `--uploads` into `content/uploads/`
+at the path WordPress kept it under, such as `uploads/2024/03/photo.png`.
+WordPress's size variants (`photo-1024x575.png`, `photo-scaled.png`) are not
+copied: the site makes its own. A file a post or page shows that is no
+attachment is copied too, for that post.
+
+Every media URL in a body, in Markdown and in the HTML it keeps, on the
+export's own origin, on an `--origins` host, or root-relative, becomes a
+root-relative `/uploads/` URL of the original. One pointing at a size variant
+points at its original. An upload URL on any other host is left alone.
+
+Each file is held to the rules an upload through the editor is: the site's
+allowed types and size limits, and location and camera details removed. A
+file the site would refuse is not copied. The report names it, and names
+each file missing from `--uploads`. Without `--uploads` nothing is copied and
+the report names each attachment.
+
+An attachment's alt text (`_wp_attachment_image_alt`) goes to
+`_data/media.json` under its upload path, which is where the editor offers it
+from. The import owns each key it set there, never the file.
+
+While the plugin is enabled, a request for `/wp-content/uploads/<path>`
+answers 301 at `/uploads/<path>`, so links from elsewhere still land on the
+file. A size variant the import did not copy lands on its original, as
+`import.json` records it, and the query string is kept. No `redirects.json`
+entry is written per file. Keep the plugin enabled for as long as links to the
+old media URLs matter.
+
+### Comments and reactions
+
+Every comment WordPress kept on a post or page the import writes goes into the
+post's comment file, `_data/comments/<slug>.json`, the file the site's own
+comments go to. That covers form comments, and the likes, reposts, replies,
+mentions, bookmarks and pingbacks the ActivityPub and Webmention plugins stored
+as comments. Each lands under the post as one the site received itself would:
+
+| WordPress                                                 | Here                                                           |
+| --------------------------------------------------------- | -------------------------------------------------------------- |
+| `comment`, `like`, `repost` with `protocol` `activitypub` | A fediverse reply, like or boost, linked to the remote post.   |
+| `comment`, `like`, `repost` with `protocol` `webmention`  | A webmention reply, like or repost, linked to its source page. |
+| `mention`, `bookmark`, `webmention`                       | A mention, linked to the page that linked here.                |
+| `pingback`, `trackback`                                   | A mention, linked to the page that pinged.                     |
+| `comment` with no protocol                                | A comment left on the page.                                    |
+
+A reply keeps the comment it answers. An approved comment is approved here,
+and one WordPress held for moderation waits here too. Spam and trash are left
+out and named in the report. A commenter's email goes only to
+`data/comments/`. Nothing is announced: no moderator is emailed and nothing is
+delivered.
+
+Every imported comment is `migrated: true`. It shows on its post and in its
+thread like any other comment, and replies to it thread under it. It is in no
+feed: not `/comments/feed/`, not a post's `{permalink}feed/`, not a
+`/replies/{key}/` feed, and not in the reply counts the feeds give. A reader
+of WordPress's comments feed sees nothing new when the site moves.
+
+Each comment keeps its `origin`, the name it was first published under, and
+its id is the key the site gives the same comment when it arrives here itself.
+A key is the first 16 hex digits of a SHA-256.
+
+| Comment                             | `origin`                                                                       | Id, the key of                        |
+| ----------------------------------- | ------------------------------------------------------------------------------ | ------------------------------------- |
+| A fediverse reply                   | The note, `source_id`                                                          | The origin                            |
+| A fediverse like or boost           | The activity, `source_id`                                                      | The origin                            |
+| A webmention, pingback or trackback | The page that linked here: `webmention_source_url`, or a pingback's author URL | The origin and the post's permalink   |
+| A like or repost with no protocol   | `source_id`, such as a Bluesky `at://` URI                                     | The origin and the post's permalink   |
+| A comment left on the page          | None                                                                           | `https://example.com/?p=ID#comment-N` |
+
+So a webmention sent again is the comment the site already holds, and so is
+a fediverse reply or reaction delivered again or read by the site's reply
+backfill: it shows once, as the imported comment, and answers to the note
+thread under it. A fediverse reply's `url` stays the note's web page. A comment left on the page
+has a page of its own, `/comment/{key}/`.
+
+A fediverse comment names its actor in `_activitypub_remote_actor_id`: one of
+the export's `ap_actor` items, the ActivityPub plugin's cached copy of that
+actor's profile. The import reads that profile and gives the comment its
+`actor`, the actor's id, and its `author.avatar`, the actor's icon. The page
+shows the icon through the site's avatar cache, so a like or a boost shows a
+face, and a like delivered here since from the same actor is counted with the
+imported one. A comment whose actor is not in the export imports without
+either.
+
+A comment written signed in to WordPress names its writer in
+`comment_user_id`. When that WordPress user's login is a user on this site, the
+rule a post's author follows, the comment keeps that user as its `user`. The
+thread then shows it as theirs, as it shows their reply posts: their display
+name and avatar, and a link to their author archive with no `rel="nofollow
+ugc"`. It stays an imported comment.
+
+The import merges by comment id. A rerun adds the comments WordPress received
+since and picks up one edited there. It leaves alone a comment this site
+received itself, and the words and status of an imported one a moderator
+approved, filed as spam, edited or deleted. It still marks such a comment
+migrated and gives it its origin, its user and its actor.
+
+**Upgrading from 0.2.0.** Version 0.2.0 used each comment's WordPress URL as
+its id. The site gives every such id the key of that URL when it next boots,
+or when it next runs a plugin command. A rerun of the import then moves each
+fediverse comment and webmention to the key of its origin, in its place, and
+any reply here that names it follows. Each comment stays one record. The
+import's record of what it wrote, `import.json`, moves to the new keys, so the
+rerun reports no clash.
+
+### Redirects
+
+Links from elsewhere use URL forms WordPress answered and the site has no
+document at. The import declares a redirect for each in
+`_data/redirects/wordpress.json`, a file of its own, which the site reads beside
+`_data/redirects.json` with no plugin enabled:
+
+| URL                                         | Answers 301 at              |
+| ------------------------------------------- | --------------------------- |
+| `/?p=ID`, for every published post and page | Its permalink.              |
+| `/?page_id=ID`, for every published page    | Its permalink.              |
+| An attachment's page, such as `/photo-jpg/` | Its file under `/uploads/`. |
+| `/?attachment_id=ID` and `/?p=ID`, likewise | Its file under `/uploads/`. |
+
+The page WordPress used as its static front page is the exception: its
+`?p=` and `?page_id=` answer at `/`, where the site serves its homepage, since
+the page's own permalink redirects there too.
+
+A draft, a pending, private, password-protected or scheduled post or page gets
+no redirect, so its `?p=` answers as an id WordPress never had. An attachment
+whose file was not copied gets none either, until a run copies it. A post's
+old slugs and dates go into its own `redirect_from`, as
+[Posts and pages](#posts-and-pages) says. A published post's `?p=` is also its
+`activitypub.id`, which the site answers first, at the same permalink.
+
+The import owns each key it set in `wordpress.json`, never the file, and never
+touches `_data/redirects.json`. A key the site added there, or changed, is left
+alone on every rerun. Where both files declare one URL, `redirects.json` wins.
+A link to a comment, `#comment-N`, reaches the post: the fragment never
+reaches the server. The post's anchors are `#comment-{key}`, so the browser
+opens the post at the top.
+
 ## Bringing a person across
 
 `geekity import wordpress-actor` brings one person across. It writes the three