[@layout]: ../docs.layout.md

# Embed web content

Turn a titled Markdown link into an X post, YouTube player, or rich card for
another public web page:

```md
[@embed A post from X](https://x.com/Interior/status/463440424141459456)

[@embed YouTube API demonstration](https://www.youtube.com/watch?v=M7lc1UVf-VE)

[@embed An article](https://example.com/article)
```

Ordinary links remain ordinary links. `@embed` is an explicit choice to present
the destination in the document.

---

## Setup

```sh
bun run pmx plugins add embed
```

Start from an initialized [Quickstart project](../start/first-site.guide), add
one of the links above to a Source, then run `bun run pmx lint` and
`bun run pmx dev`.

---

## Supported destinations

Individual X posts use X's official web widget. Individual YouTube watch, short,
Shorts, live, and embed URLs use a responsive privacy-enhanced YouTube player.
Profiles, feeds, channels, playlists, and search pages are not supported as rich
embeds. Every rich embed retains a link to its original post, video, or page;
Play mode exposes that link as an external Beat action.

Every other public HTTP or HTTPS page becomes a PathMX link card. The Plugin reads
the page's Open Graph or standard metadata for its title, description, publisher,
and preview image. This works with public articles from sources such as Substack
and news sites when they expose readable page metadata. The card links to the
original page; it does not copy or reframe the article.

Use the [Video plugin](./video.reference) instead when a YouTube video needs PathMX
playback controls, captions, thumbnails, or Player integration.

---

## Fallbacks and privacy

The authored title and destination remain available if a provider is blocked,
unavailable, private, or removes its content. Missing metadata produces a simpler
card rather than failing the page. A malformed supported-provider URL is an
authoring error reported by `pmx lint`.

YouTube and X receive browser requests when their embedded content loads. Generic
web-page metadata is fetched while PathMX compiles the page; readers receive the
resulting card and do not fetch the article themselves. Remote metadata is
best-effort and cached during the running PathMX process.

Try the [embed example](../../examples/embed.demo).