Add crossposting FAQ and reference snippets in the docs (#3483)

Author: pfefferle

docs/faq/crossposting.md

@@ -0,0 +1,53 @@
+# Can the plugin crosspost to my existing Mastodon account?
+
+Short answer: no, and that is a deliberate design choice rather than a missing feature.
+
+This is one of the most common questions in the [support forum](https://wordpress.org/support/plugin/activitypub/), usually phrased as *"How do I connect the plugin to my Mastodon account?"* or *"Why doesn't my post show up on my Mastodon profile?"* The honest answer is that the plugin is not a crossposter and is not trying to be one. This page explains the difference, why crossposting will not be added, and what to do if mirroring to an existing account is genuinely what you want.
+
+## Crossposter vs. native federation
+
+These are two fundamentally different models, and the plugin sits firmly on the federation side.
+
+| | Crossposter | *ActivityPub for WordPress* |
+|---|---|---|
+| **Where your identity lives** | On a third-party Mastodon server (`@you@mastodon.social`) | On your own site (`@you@example.com`) |
+| **What gets sent** | A *copy* of each post, pushed to that account | The *original* post, fetched and followed directly |
+| **Who your followers follow** | Your Mastodon account | Your website |
+| **Where replies land** | On the remote account, separate from your site | Back on your site, as WordPress comments |
+| **Accounts you need** | A separate Mastodon account, plus your site | Just your site |
+
+A crossposter takes a copy of your WordPress post and publishes it to a *separate* account you already have somewhere else. Your identity, your followers, and every reply stay over there. WordPress is only a feed that pushes copies out.
+
+*ActivityPub for WordPress* works the other way around. It turns your own site into a first-class member of the Fediverse, so `@you@example.com` **is** the account. People on Mastodon, Pixelfed, Threads, and other platforms follow your site directly, your posts are the originals instead of copies, and likes, boosts, and replies come back to your site as comments. You own both the identity and the conversation.
+
+## Why the plugin will not crosspost
+
+Crossposting and native federation pull in opposite directions, and bolting one onto the other reintroduces the very problems federation is meant to solve:
+
+- **Split identity.** Your audience has to choose between following your site and following your Mastodon account, and neither one ever has the full picture.
+- **Lost conversations.** Replies would land on the remote account, disconnected from the original post, so your site's comments section would never see them.
+- **Duplicate content.** The same post would exist in two places, with two follower lists, two comment threads, and two link targets. That is confusing for readers and bad for search engines.
+
+> [!NOTE]
+> This is about keeping the plugin focused, not about a technical limitation. Crossposting to an account you control elsewhere is a real, useful workflow. It is simply a different job, and dedicated tools already do it well.
+
+## "But I already have a big Mastodon account"
+
+This is the most understandable reason people ask, and there are a few legitimate paths depending on what you want your main presence to be.
+
+**Option 1: Make your WordPress site your primary Fediverse identity.**
+If you would rather consolidate around your own domain, you can bring your existing Mastodon followers with you. Mastodon's account-migration tool can move your followers to `@you@example.com`, after which new posts reach them natively, with replies arriving as comments. See the [Account Migration guide](../how-to/account-migration.md).
+
+**Option 2: Keep your big Mastodon account and have it boost your posts.**
+If you want to keep your established account but still surface new articles to its followers, [FediBoost](https://github.com/kraftbj/fediboost) is a good middle ground. Instead of copying your post, it has your connected Mastodon account automatically *boost* (reblog) the original post that this plugin already federated from your site. The post stays the single canonical version, replies still come back to your site as comments, and your Mastodon followers see it through the boost.
+
+**Option 3: Keep your Mastodon account as your main presence and mirror articles to it.**
+If your established Mastodon account is where you want your audience to live, that is a crossposting job. Use a [dedicated crossposter plugin](https://wordpress.org/plugins/search/mastodon/) built for exactly this. They work happily alongside this plugin or entirely on their own.
+
+> [!TIP]
+> These options are not either/or. Keep *ActivityPub for WordPress* running so your site has its own Fediverse presence, then layer FediBoost or a crossposter on top to also reach your existing Mastodon audience. They coexist without conflict.
+
+## Related
+
+- [Account Migration](../how-to/account-migration.md) — move your Mastodon followers to your WordPress site.
+- [What is "ActivityPub for WordPress"?](../../readme.txt) — the bigger picture of how the plugin federates your site.

docs/faq/missing-comments.md

@@ -13,14 +13,18 @@ Work through this checklist in order:
 The most common "missing" comment is sitting in a queue:
 
 - **Comments → Spam**: Akismet and friends regularly misclassify federated comments (see below).
-- **Comments → Pending**: **Settings → Discussion → "Comment must be manually approved"** or **"must have a previously approved comment"** holds federated replies like any other comment. If you want Fediverse interactions to skip moderation, use the official [auto-approve-reactions snippet](https://github.com/Automattic/wordpress-activitypub/tree/trunk/snippets/auto-approve-reactions).
+- **Comments → Pending**: **Settings → Discussion → "Comment must be manually approved"** or **"must have a previously approved comment"** holds federated replies like any other comment. If you want Fediverse interactions to skip moderation, use the official [auto-approve-reactions snippet](../../snippets/auto-approve-reactions).
 - **Comments → Trash**: entries on the Disallowed Comment Keys list land here (see below).
 
-⚠ **Beware of "silently discard" options.** Akismet's "Silently discard the worst and most pervasive spam" and similar auto-delete settings (e.g. Antispam Bee's honeypot delete) remove comments without a trace — it looks exactly like they never arrived. Switch such options to "mark as spam" at least while debugging.
+> [!WARNING]
+> **Beware of "silently discard" options.** Akismet's "Silently discard the worst and most pervasive spam" and similar auto-delete settings (e.g. Antispam Bee's honeypot delete) remove comments without a trace — it looks exactly like they never arrived. Switch such options to "mark as spam" at least while debugging.
 
 ### 2. Captcha and honeypot plugins
 
-**The headline cause.** Captcha plugins usually do not distinguish between a comment submitted via the form and one created via an API — and a federated reply can never pass a captcha. Confirmed examples from support threads and issues:
+> [!IMPORTANT]
+> Captcha plugins are the single most common cause. They usually do not distinguish between a comment submitted via the form and one created via an API, and a federated reply can never pass a captcha.
+
+Confirmed examples from support threads and issues:
 
 - **hCaptcha**: the comment-form integration blocks all federated replies. Disable hCaptcha for the comment form (keep it for login etc.).
 - **Advanced Google reCAPTCHA**: blocked all incoming replies; a telltale sign was that comment **notification emails still arrived** while the comments themselves never materialized.
@@ -62,6 +66,7 @@ If a caching layer serves cached HTML where the remote server expects JSON ([con
 Some "missing comments" are protocol semantics, not bugs:
 
 - **Only actual replies become comments.** A post that merely @-mentions you — written from scratch instead of using the Reply button — has no `inReplyTo` and cannot be matched to a post.
+- **Quotes are not replies.** A post that *quotes* yours is shown as a reaction (in the facepile), not as a comment. If you would rather see quotes in the comments, use the [Quotes as Comments snippet](../../snippets/quotes-as-comments).
 - **Visibility matters.** Replies with "mentioned people only" visibility are treated as private messages, not public comments.
 - **Deep threads:** replies to *other people's* replies arrive via the thread; in some setups replies addressed to a local WordPress comment rather than the post are still not imported — a known limitation under investigation.
 - **Companion plugins:** if you run the [Friends plugin](https://wordpress.org/plugins/friends/), mention-only posts appear there as feed items rather than as comments — that is intentional routing.
@@ -70,4 +75,6 @@ Some "missing comments" are protocol semantics, not bugs:
 
 Update the plugin first to rule out long-fixed bugs. Then test with all antispam/captcha/security plugins temporarily disabled — if the reply arrives, re-enable them one at a time to find the culprit.
 
+To see whether the reply even reached your site, the [Inspect Internal Storage snippet](../../snippets/inspect-internal-storage) exposes the plugin's Inbox and Outbox in the WordPress admin: if the activity is there, the problem is local filtering (steps 1-4); if it is not, it was blocked before processing (steps 5-6).
+
 If none of this helps, open a thread in the [support forum](https://wordpress.org/support/plugin/activitypub/) and include: which antispam/captcha/caching/security plugins you run, whether comment notification emails arrive, and the status code your server log shows for the inbox POST.

docs/faq/pending-follow-requests.md

@@ -10,6 +10,7 @@ The plugin **always accepts follow requests automatically** — there is no manu
 
 If step 1 is blocked, your site never learns about the follow. If step 2 or 3 fails, your site knows about the follower but the remote server never hears back. The first thing to check tells you which half is broken:
 
+> [!TIP]
 > **Does the follower appear in WordPress?** Check **Users → Followers** (or **Settings → ActivityPub → Followers** for the blog profile).
 >
 > - **No** → the follow request never reached your site. Work through [Inbound checks](#inbound-checks).
@@ -31,7 +32,8 @@ These block the follow request before your site ever sees it. Your server's acce
 
 ### 1. Host firewall (mod_security)
 
-**The most common cause on shared hosting.** Many hosts (HostGator, Bluehost, OVH, Strato, and other cPanel-based hosts are recurring examples) run mod_security rules that block `POST` requests with the `application/activity+json` content type.
+> [!IMPORTANT]
+> **The most common cause on shared hosting.** Many hosts (HostGator, Bluehost, OVH, Strato, and other cPanel-based hosts are recurring examples) run mod_security rules that block `POST` requests with the `application/activity+json` content type.
 
 There is nothing the plugin can do about this — only your host can fix it. Contact their support with something like:
 
@@ -115,4 +117,6 @@ If outbound requests fail, contact your host.
 
 Update the plugin first — several historic causes (subdirectory signatures, the 4.0.0 inbox regression, Pixelfed follows without addressing) were plugin bugs that are long fixed.
 
+To pinpoint which half of the round-trip broke, the [Inspect Internal Storage snippet](../../snippets/inspect-internal-storage) exposes the plugin's Inbox and Outbox in the WordPress admin: a missing `Follow` in the Inbox points to the [Inbound checks](#inbound-checks), while a stuck `Accept` in the Outbox points to the [Outbound checks](#outbound-checks).
+
 If none of this helps, open a thread in the [support forum](https://wordpress.org/support/plugin/activitypub/) and include: your hosting provider, active security/caching/antispam plugins, whether the follower appears in WordPress, and the status code your server log shows for inbox POSTs.

docs/faq/readme.md

@@ -1,10 +1,13 @@
 # Frequently Asked Questions
 
-Answers to questions and problems that come up regularly in the [support forum](https://wordpress.org/support/plugin/activitypub/) and on [GitHub](https://github.com/Automattic/wordpress-activitypub/issues). Each answer is a checklist, ordered by how often the cause turns out to be the culprit.
+Answers to questions and problems that come up regularly in the [support forum](https://wordpress.org/support/plugin/activitypub/) and on [GitHub](https://github.com/Automattic/wordpress-activitypub/issues). Most answers are troubleshooting checklists, ordered by how often the cause turns out to be the culprit; a few explain how the plugin is meant to work.
 
 If your question is missing, please [open an issue](https://github.com/Automattic/wordpress-activitypub/issues/new/choose) or [submit a pull request](https://github.com/Automattic/wordpress-activitypub/pulls). For guides on configuring specific setups, see the [How-To section](../how-to/readme.md).
 
+Several answers point to community [snippets](../../snippets/README.md): small, optional plugins that adjust or extend the plugin's behavior, for example to auto-approve reactions, show quotes as comments, or inspect the internal Inbox and Outbox while debugging.
+
 ## Table of Contents
 
 - [Why is a follow request stuck on "pending"?](pending-follow-requests.md) — The remote side shows "Follow requested" / "Cancel request" forever.
 - [Why don't comments from the Fediverse show up?](missing-comments.md) — Replies on Mastodon & Co. never appear as WordPress comments, often caused by captcha and antispam plugins.
+- [Can the plugin crosspost to my existing Mastodon account?](crossposting.md) — Why this is native federation rather than a crossposter, and what to do if you want to mirror posts instead.

docs/how-to/account-migration.md

@@ -89,5 +89,7 @@ Only if both checks pass will the server transfer followers from the old account
 
 - **Migration moves followers, not content.** Your posts, media, and other content stay on the original platform. Only the follower relationships are transferred.
 - **Not all servers support Move.** Most Mastodon-compatible servers do, but some smaller Fediverse platforms may not process `Move` activities.
-- **Migration is essentially one-way.** While you can technically migrate back, followers who already transferred may not automatically follow back to the original account.
 - **Add aliases before initiating the move.** The target account must have the origin listed in its aliases, or the move will be rejected.
+
+> [!CAUTION]
+> **Migration is essentially one-way.** While you can technically migrate back, followers who already transferred may not automatically follow back to the original account.

docs/how-to/reverse-proxy.md

@@ -2,7 +2,10 @@
 
 If you are using a reverse proxy with Apache to serve your site, you may find that followers are unable to follow your blog. This happens because the proxy rewrites the `Host` header to your server’s internal DNS name, which the plugin then uses to sign replies. However, remote servers expect replies to be signed with your public DNS name. To resolve this, you need to use the `ProxyPreserveHost On` directive to ensure that the external host name is passed through to the backend server.
 
-If you are using SSL between the reverse proxy and the internal host, you may also need to set `SSLProxyCheckPeerName off` if the internal host does not present the correct SSL certificate. Be aware that this can introduce a security risk in some environments.
+If you are using SSL between the reverse proxy and the internal host, you may also need to set `SSLProxyCheckPeerName off` if the internal host does not present the correct SSL certificate.
+
+> [!WARNING]
+> Disabling `SSLProxyCheckPeerName` stops the proxy from verifying the internal host's certificate, which can introduce a security risk in some environments. Only use it when you trust the network between the proxy and the backend.
 
 ## Example
 

readme.txt

@@ -61,6 +61,12 @@ This plugin connects your WordPress blog to popular social platforms like Mastod
 
 *ActivityPub for WordPress* adds Fediverse features to WordPress, but it is not a replacement for platforms like Friendica or Mastodon. If you're looking to host a decentralized social network, consider using [Mastodon](https://joinmastodon.org/) or [Friendica](https://friendi.ca/).
 
+= Is this a Mastodon crossposter? Can it post to my existing Mastodon account? =
+
+No. A crossposter pushes copies of your posts to a *separate* account you already have on someone else's server. *ActivityPub for WordPress* does the opposite: it makes your own site a first-class Fediverse account (`@you@example.com`), so people follow your site directly and replies come back as WordPress comments, with no second account required.
+
+The plugin will not add crossposting to an existing account; that is a deliberate choice, not a missing feature. If you would rather mirror articles to an established Mastodon account, that is a job for a dedicated crossposter plugin.
+
 = Why "ActivityPub"? =
 
 The name ActivityPub comes from the two core ideas behind the protocol: