Distinguish between “Link Preview Card” and “Embed WordPress (full post)”

[kimjiwoon]

### Summary

• ​https://github.com/Automattic/wordpress-activitypub/issues/2152
• ​https://github.com/WordPress/gutenberg/issues/71564

When embedding a WordPress link in the Block Editor today, it’s rendered in a URL preview card style. However, on some WordPress sites (e.g., those using the Avada theme), the embed attempts to render the entire site within the block. While that may be a theme–embed compatibility issue, the net result is inconsistent behavior depending on which theme powers the target site. We’ve tolerated this ambiguity because there hasn’t been a clean alternative.

By contrast, on the Fediverse side, Mastodon exposes a clearly defined PreviewCard (OpenGraph-driven) concept:

• ​https://docs.joinmastodon.org/entities/PreviewCard/(​https://docs.joinmastodon.org/entities/PreviewCard/)
• ​https://blog.joinmastodon.org/2024/07/highlighting-journalism-on-mastodon/(​https://blog.joinmastodon.org/2024/07/highlighting-journalism-on-mastodon/)

And when going through a Mastodon proxy to embed a WordPress post, we can successfully retrieve the full post body.

Core point:

• Today, “Embed WordPress” behaves like a URL preview card (title + excerpt + image), cannot embed the full post body, and is sensitive to target theme quirks.
• If we say “Embed WordPress,” it should—strictly speaking—fetch and render the post content, not just show a preview.

---

### Problem

• Conflation of two concepts:

1. Preview (OpenGraph/Twitter Card/Mastodon PreviewCard—lightweight summary), and
2. Embed (oEmbed or compatible transform that renders the actual post content).

• Inconsistent UX depending on the target site’s theme (e.g., Avada), where the block may try to embed the entire site wrapper or behave unpredictably.
• ActivityPub context: The Fediverse already distinguishes previews from content (e.g., PreviewCard vs. Article/Note bodies). WordPress should mirror that separation for predictable embeds.

---

### Proposal

Introduce two explicit embed modes in the Block Editor (and expose the distinction to ActivityPub if/where relevant):

1. Link Preview Card (lightweight)

• Driven by OpenGraph/PreviewCard-like data.
• Always consistent: title, description/excerpt, preview image, source domain.
• Theme-agnostic outcome.

2. Embed WordPress Post (full content)

• Fetches and renders the post body (within a safe, sanitized container).
• Theme-agnostic; does not attempt to embed the entire site shell.
• Clearly labeled as “Full post embed,” with fallbacks if full content retrieval fails.

Behavior:

• Default to Preview Card for any external URL.
• When the target is a WordPress post, allow switching to Full Post Embed (explicit control).
• For ActivityPub contexts, keep Preview vs. Full distinct in the UI and payload.

---

### Why this helps

• Consistency: No more theme-dependent surprises (Avada or otherwise).
• Clarity: Authors choose Preview vs. Full explicitly.
• Parity with Fediverse: Mirrors Mastodon’s PreviewCard vs. actual post content distinction.
• Better journalism/long-form: Aligns with ongoing work to represent long-form content cleanly across platforms.

---

### Edge Cases / Risks

• Full-content embeds require robust sanitization and styling isolation (e.g., shadow root or scoped styles) to avoid CSS/JS bleed.
• Fallback to Preview Card when full content retrieval fails or is disallowed by the target.
• Caching and revalidation policy to avoid stale embeds.

---

### Repro (current behavior)

1. In the Block Editor, paste a WordPress post URL.
2. Observe it renders as a preview card (not full content).
3. Try a site using Avada; you may see inconsistent or site-shell embeds.
4. Compare with a Mastodon proxy path where the full post body can be retrieved.

---

### Suggested UI

• Block: “Link Preview” vs “Embed WordPress Post” toggle (auto-detected for WP targets).
• Clear labels/tooltips explaining the difference.

---

e.g. ​https://designbusan.wpcomstaging.com/2025/09/09/embed-2/

| Case | Screenshot | Notes |

|

| 1. Current “Preview Card” for WordPress links | <img src="​https://github.com/user-attachments/assets/45d50f0d-8193-4429-8890-d7585479bfee" width="500" /> | Title, excerpt, image only. Not the full post body.<br>Behavior can vary depending on the theme. |
| 2. Mastodon proxy → WordPress post (full body) | <img src="​https://github.com/user-attachments/assets/f72a5c68-a23b-4a6d-b2ef-5e5decd52dcf" width="500" /> | Shows that full content retrieval is possible.<br>Demonstrates the case for a distinct “Full Post Embed.” |
| 3. Avada-themed site link → inconsistent embed | <img src="​https://github.com/user-attachments/assets/461060f0-339e-435d-9e14-b9dd42e90d9f" width="500" /><br><img src="​https://github.com/user-attachments/assets/32ab5736-1e61-4f08-bf00-4a12a60d76c2" width="500" /> | Attempts to embed the entire site shell.<br>Highlights why we need to separate Preview vs. Full Content modes. |

---

### Open Questions

• Should the Full Post Embed rely on oEmbed, a dedicated REST endpoint, or a sanitized server-side transform?
• What is the cache invalidation strategy for embedded content updates?
• For ActivityPub contexts, should “Full Post Embed” be exposed as a distinct block/type or remain a WordPress-only authoring affordance?

[swissspidy]

Link previews powered by Open Graph were previously suggested in #32955. Ultimately, we didn't implement it because there was already the oEmbed functionality and it wouldn't make sense two have to similar competing implementations for embeds.

Personally I still don't see a need for such functionality and there haven't been any additional feature requests for this since the above ticket. And plugins like ​https://wordpress.org/plugins/visual-link-preview/ and ​https://wordpress.org/plugins/link-preview-cards/ have very few installations.

With your suggestion, we would have 3 different types of embeds in WordPress:

1. oEmbed
2. Link preview
3. Full embedded content

I doubt that site owners would be happy about (3) without any kind of opt-in, and for (2) there are already plugins like the ones mentioned above.

[kimjiwoon]

@swissspidy I am currently deeply immersed in the connection between the Fediverse and WordPress. Regardless of personal preferences, this is also in line with Automattic’s direction.

​https://github.com/Automattic/wordpress-activitypub/issues/2157
Reader: Add support for link previews

Personally I still don't see a need for such functionality and there haven't been any additional feature requests for this since the above ticket. And plugins like ​https://wordpress.org/plugins/visual-link-preview/(​https://wordpress.org/plugins/visual-link-preview/) and ​https://wordpress.org/plugins/link-preview-cards/(​https://wordpress.org/plugins/link-preview-cards/) have very few installations.

My preference is not to inflate functionality through additional plugins, but rather to have link previews supported natively at the core level, ensuring clean and consistent behavior across the entire WordPress ecosystem.

The current level of demand might not be high enough to justify standalone plugins, but that does not diminish the value of having this as a baseline feature in core.

Full-text embedding is already possible via WordPress’s Mastodon proxy. This is exactly why I believe improving the embed structure in WordPress core itself is necessary to provide seamless support by default.
​https://designbusan.wpcomstaging.com/2025/09/09/embed-2/

---

Thank you for pointing me to #32955 and for highlighting the plugin landscape. I agree that historically, “oEmbed vs. Open Graph preview” may have felt like duplication, which is probably why the feature never gained traction in Core.

However, the situation today is slightly different:

1. We already have conflation in practice. What we call “Embed WordPress” currently behaves like a link preview (title + excerpt + image), but does not actually deliver the post body. This creates ambiguity both for authors and for users consuming embeds.

2. Other ecosystems draw a clear line. Mastodon (and more broadly, ActivityPub contexts) explicitly separate PreviewCard (Open Graph) from the Note/Article body. WordPress today does not make that distinction, which causes confusion when bridging across platforms.

3. The demand is not just stylistic, it’s semantic. A “preview” and a “full embed” serve two different purposes. Conflating them into a single oEmbed-like behavior leaves us with inconsistent UX (e.g., Avada case, where the entire theme shell tries to render).

4. Opt-in solves the risk. I agree that site owners would not want their content fully embedded without consent. But the solution is to treat “Full Post Embed” as an explicit, opt-in mode for WordPress targets only. By default, all external URLs would continue to resolve to a Link Preview Card.

So rather than proposing “three competing implementations,” the proposal is:

• Preview Card = lightweight, Open Graph–driven (consistent, theme-agnostic).
• Full Post Embed = opt-in for WordPress posts only (fetch post content, not site shell).
• oEmbed continues to power both under the hood, but with explicit UI labels that separate the semantics.

This reframing means we are not introducing “another” embed type, but clarifying existing ambiguities and giving authors predictable control.

[kimjiwoon]

​https://github.com/iamcal/oembed/tree/master/providers

Currently, the oEmbed provider list only includes WordPress.com and its subdomains (*.wordpress.com, wp.me). Self-hosted WordPress.org sites are not registered as providers by default.

### ⚠️ Issues

1. Reliance on discovery

• Each site must expose a <link rel="alternate" …> meta tag correctly, but certain themes or plugins can break this.
• Without a fixed endpoint in the provider list, client applications need to perform discovery for every request, which introduces instability.

2. Caching and proxy concerns

• Clients like Mastodon, Slack, and Discord typically consult the oembed.com provider list first. Since self-hosted WordPress sites aren’t listed, these clients must fall back to discovery.
• If discovery fails, the result is often that no link preview card is generated.

3. Compatibility over scalability

• Scalability itself is not the bottleneck here, but compatibility becomes inconsistent.
• Example: embedding a WordPress.org blog URL may show a preview in some clients but fail entirely in others.

---

👉 This highlights that the real challenge for self-hosted WordPress oEmbed is not scaling, but ensuring consistent compatibility across clients.