[wp-trac] [WordPress Trac] #63948: Distinguish between “Link Preview Card” and “Embed WordPress (full post)”
WordPress Trac
noreply at wordpress.org
Tue Sep 9 15:11:21 UTC 2025
#63948: Distinguish between “Link Preview Card” and “Embed WordPress (full post)”
-------------------------+-----------------------------
Reporter: kimjiwoon | Owner: (none)
Type: enhancement | Status: new
Priority: normal | Milestone: Awaiting Review
Component: Embeds | Version:
Severity: normal | Keywords:
Focuses: |
-------------------------+-----------------------------
### 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?
--
Ticket URL: <https://core.trac.wordpress.org/ticket/63948>
WordPress Trac <https://core.trac.wordpress.org/>
WordPress publishing platform
More information about the wp-trac
mailing list