Docs

Runes

Themes

Extend

Project

Embed

Embed external content from popular platforms. URLs are automatically detected and converted to the appropriate embed format. Supports YouTube, Vimeo, Twitter/X, CodePen, and Spotify.

Basic usage

Pass a URL and optional title to embed content from a supported provider.

{% embed url="https://www.youtube.com/watch?v=dQw4w9WgXcQ" title="Example video" /%}

<figure data-rune="embed" typeof="VideoObject" data-rune-fields="{&quot;provider&quot;:&quot;youtube&quot;}">
  <meta content="https://www.youtube.com/watch?v=dQw4w9WgXcQ" property="contentUrl">
  <meta content="Example video" property="name">
  <meta content="https://www.youtube-nocookie.com/embed/dQw4w9WgXcQ" property="embedUrl">
  <div style="padding-bottom: 56.25%" data-name="wrapper">
    <iframe src="https://www.youtube-nocookie.com/embed/dQw4w9WgXcQ" title="Example video" frameborder="0" allow="accelerometer; autoplay; clipboard-write; encrypted-media; gyroscope; picture-in-picture" allowfullscreen="" loading="lazy"></iframe>
  </div>
  <div data-name="fallback"></div>
</figure>

<figure typeof="VideoObject" class="rf-embed" data-provider="youtube" data-elevation="flat" data-rune="embed" data-density="compact">
  <meta content="https://www.youtube.com/watch?v=dQw4w9WgXcQ" property="contentUrl" />
  <meta content="Example video" property="name" />
  <meta content="https://www.youtube-nocookie.com/embed/dQw4w9WgXcQ" property="embedUrl" />
  <div style="padding-bottom: 56.25%" data-name="wrapper" class="rf-embed__wrapper">
    <iframe src="https://www.youtube-nocookie.com/embed/dQw4w9WgXcQ" title="Example video" frameborder="0" allow="accelerometer; autoplay; clipboard-write; encrypted-media; gyroscope; picture-in-picture" allowfullscreen="" loading="lazy"></iframe>
  </div>
  <div data-name="fallback" class="rf-embed__fallback"></div>
</figure>

With fallback content

Children become fallback content displayed when the embed cannot load.

{% embed url="https://example.com/video" %}
Video could not be loaded. [Watch on the original site](https://example.com/video).
{% /embed %}

<figure data-rune="embed" typeof="VideoObject" data-rune-fields="{&quot;provider&quot;:&quot;generic&quot;}">
  <meta content="https://example.com/video" property="contentUrl">
  <meta content="https://example.com/video" property="embedUrl">
  <div style="padding-bottom: 56.25%" data-name="wrapper">
    <iframe src="https://example.com/video" title="Embedded content" frameborder="0" allow="accelerometer; autoplay; clipboard-write; encrypted-media; gyroscope; picture-in-picture" allowfullscreen="" loading="lazy"></iframe>
  </div>
  <div data-name="fallback">
    <p>
      Video could not be loaded.
      <a href="https://example.com/video">Watch on the original site</a>
      .
    </p>
  </div>
</figure>

Video could not be loaded. Watch on the original site.

<figure typeof="VideoObject" class="rf-embed" data-provider="generic" data-elevation="flat" data-rune="embed" data-density="compact">
  <meta content="https://example.com/video" property="contentUrl" />
  <meta content="https://example.com/video" property="embedUrl" />
  <div style="padding-bottom: 56.25%" data-name="wrapper" class="rf-embed__wrapper">
    <iframe src="https://example.com/video" title="Embedded content" frameborder="0" allow="accelerometer; autoplay; clipboard-write; encrypted-media; gyroscope; picture-in-picture" allowfullscreen="" loading="lazy"></iframe>
  </div>
  <div data-name="fallback" class="rf-embed__fallback">
    <p>
      Video could not be loaded. 
      <a href="https://example.com/video">Watch on the original site</a>
      .
    </p>
  </div>
</figure>

Supported providers

Provider	Example URL
YouTube	`https://www.youtube.com/watch?v=...` or `https://youtu.be/...`
Vimeo	`https://vimeo.com/...`
Twitter/X	`https://twitter.com/.../status/...`
CodePen	`https://codepen.io/.../pen/...`
Spotify	`https://open.spotify.com/...`
Generic	Any other URL (rendered as iframe)

Attributes

Attribute	Type	Required	Description
`url`	`string`	✓	URL of the content to embed
`type`	`string`	—	Override auto-detected embed type
`aspect`	`"16:9" \| "4:3" \| "1:1" \| "auto"`	—	Aspect ratio of the embed frame
`title`	`string`	—	Accessible title for the embed iframe

Universal attributes

The background layer (SPEC-088): image, video, gradient, flat overlay wash and legibility scrim, in a single injected layer behind the rune's content.

Attribute	Type	Required	Description
`bg`	`string`	—	Background preset applied to this block
`bg-from`	`string`	—	Gradient start colour — a semantic token name (→ var(--rf-color-*))
`bg-gradient`	`"to-t" \| "to-b" \| "to-l" \| "to-r" \| "to-tr" \| "to-br" \| "to-bl" \| "to-tl"`	—	Gradient direction (bounded named set)
`bg-gradient-type`	`"linear" \| "radial" \| "conic"`	—	Gradient type
`bg-to`	`string`	—	Gradient end colour — a semantic token name
`bg-via`	`string`	—	Optional middle gradient stop — a semantic token name
`scrim`	`"top" \| "bottom" \| "left" \| "right" \| "none"`	—	Scrim direction (heaviest edge); presence turns the scrim on, "none" opts out of the default cover scrim
`scrim-blur`	`"none" \| "sm" \| "md" \| "lg"`	—	Frost scrim blur amount
`scrim-strength`	`"sm" \| "md" \| "lg"`	—	Gradient scrim strength
`scrim-tone`	`"dark" \| "light"`	—	Whether the scrim darkens (for light text) or lightens (for dark text)
`scrim-type`	`"gradient" \| "frost"`	—	Scrim treatment: gradient (default) or frost (backdrop blur)

The chrome/depth ladder (SPEC-107). The skin maps each rung to a chrome bundle by attribute, so there is no BEM class.

Attribute	Type	Required	Description
`elevation`	`"sunken" \| "flush" \| "flat" \| "raised" \| "floating" \| "overlay" \| "none" \| "sm" \| "md" \| "lg"`	—	Surface depth on the SPEC-107 ladder (sunken→overlay); none/sm/md/lg are deprecated aliases

Internal padding override.

Attribute	Type	Required	Description
`inset`	`"flush" \| "tight" \| "default" \| "loose" \| "breathe"`	—	Inner padding of this block

Scroll-reveal entrance (SPEC-105). The author declares the character, the theme owns the choreography, a behaviour owns the timing.

Attribute	Type	Required	Description
`reveal`	`"none" \| "fade" \| "slide" \| "scale" \| "blur"`	—	Scroll-reveal entrance character (none\|fade\|slide\|scale\|blur); the theme owns the choreography
`stagger`	`boolean`	—	Cascade this block's items in as it reveals (no-op on single-child runes)

Block-level rhythm override.

Attribute	Type	Required	Description
`spacing`	`"flush" \| "tight" \| "default" \| "loose" \| "breathe"`	—	Vertical spacing above and below this block

Generated pattern fills (SPEC-087). Markers only — the engine sets the attributes and cell/opacity custom properties, CSS draws the pattern.

Attribute	Type	Required	Description
`substrate`	`"dots" \| "grid" \| "lines" \| "cross" \| "checker" \| "none"`	—	Generated surface pattern
`substrate-fill`	`"inherit" \| "inset"`	—	Surface fill the pattern sits on (full colour stays with tint)
`substrate-opacity`	`"sm" \| "md" \| "lg"`	—	Pattern ink strength
`substrate-size`	`"sm" \| "md" \| "lg"`	—	Pattern cell size
`substrate-target`	`"self" \| "media"`	—	Which surface the pattern fills (overrides the rune/theme default)

Per-rune colour override (SPEC-053): a named tint from the theme registry, with inline per-token overrides layered on top.

Attribute	Type	Required	Description
`tint`	`string`	—	Color tint preset applied to this block
`tint-mode`	`"auto" \| "dark" \| "light"`	—	Whether the tint adapts to auto, dark, or light mode

The track a block rune occupies.

Attribute	Type	Required	Description
`width`	`"compact" \| "narrow" \| "content" \| "wide" \| "full"`	—	Maximum width constraint for this block

Not available	Why
dropcap, reading	this rune declares no prose body
frame	this rune declares neither a `frameTarget` nor a media section
prominence	this rune has no page-section header