Sections & blocks›MediaText

core

MediaText

Side-by-side image and text layouts with configurable ratios

Source

import Markdoc from '@markdoc/markdoc';
const { Tag } = Markdoc;
import {
	createContentModelSchema,
	bodyOnly,
	createComponentRenderable,
	renderNodes,
} from '../lib/index.js';

const alignValues = ['left', 'right'] as const;
const ratioValues = ['1:2', '1:1', '2:1'] as const;

export const mediaTextSections = { body: 'body', media: 'media' } as const;
export const mediaTextMediaSlots = { media: 'cover' } as const;

export const mediatext = createContentModelSchema({
	sections: mediaTextSections,
	provides: ['prose'],
	mediaSlots: mediaTextMediaSlots,
	attributes: {
		align: {
			type: String,
			required: false,
			matches: alignValues.slice(),
			description: 'Side the media appears on',
		},
		ratio: {
			type: String,
			required: false,
			matches: ratioValues.slice(),
			description: 'Width ratio between media and text',
		},
		wrap: { type: Boolean, required: false, description: 'Wrap text around the media' },
	},
	contentModel: bodyOnly(),
	transform(resolved, attrs, config) {
		const children = renderNodes(resolved.body, config);

		const align = attrs.align ?? 'left';
		const ratio = attrs.ratio ?? '1:1';
		const wrap = attrs.wrap ?? false;

		const alignMeta = new Tag('meta', { content: align });
		const ratioMeta = new Tag('meta', { content: ratio });
		const wrapMeta = wrap ? new Tag('meta', { content: 'true' }) : undefined;

		const mediaChildren: any[] = [];
		const bodyChildren: any[] = [];

		for (const node of children.toArray()) {
			if (
				Markdoc.Tag.isTag(node) &&
				node.name === 'p' &&
				node.children.length === 1 &&
				Markdoc.Tag.isTag(node.children[0]) &&
				node.children[0].name === 'img'
			) {
				mediaChildren.push(node.children[0]);
			} else if (Markdoc.Tag.isTag(node) && node.name === 'img') {
				mediaChildren.push(node);
			} else {
				bodyChildren.push(node);
			}
		}

		const mediaTag = new Tag('div', {}, mediaChildren);
		const bodyTag = new Tag('div', {}, bodyChildren);

		return createComponentRenderable({
			rune: 'media-text',
			tag: 'div',
			properties: {
				align: alignMeta,
				ratio: ratioMeta,
				wrap: wrapMeta,
			},
			refs: {
				media: mediaTag,
				body: bodyTag,
			},
			children: [mediaTag, bodyTag],
		});
	},
});

View packages/runes/src/tags/mediatext.ts on GitHub

Side-by-side media and text layouts. Images within the rune are extracted into a media column, and the remaining text forms the body column. Control image placement, size ratio, and text wrapping. To caption a single image (or code, or a table) on its own, use figure; to present a screenshot or product shot in a framed viewport, use showcase.

Basic usage

Place an image alongside text — the image is automatically extracted and placed according to the align attribute.

{% mediatext align="left" ratio="1:1" %}
![Mountain landscape](https://assets.refrakt.md/media-text-valley.jpg)

The valley stretches out below, carved by millennia of glacial movement. In spring, wildflowers carpet the meadows in brilliant color, attracting hikers and photographers from around the world.

The trails here range from gentle walks suitable for families to challenging ridge climbs that reward with panoramic views.
{% /mediatext %}
<div data-rune="media-text" data-rune-fields="{&quot;align&quot;:&quot;left&quot;,&quot;ratio&quot;:&quot;1:1&quot;}">
  <div data-name="media">
    <img src="https://assets.refrakt.md/media-text-valley.jpg" alt="Mountain landscape">
  </div>
  <div data-name="body">
    <p>The valley stretches out below, carved by millennia of glacial movement. In spring, wildflowers carpet the meadows in brilliant color, attracting hikers and photographers from around the world.</p>
    <p>The trails here range from gentle walks suitable for families to challenging ridge climbs that reward with panoramic views.</p>
  </div>
</div>
Mountain landscape

The valley stretches out below, carved by millennia of glacial movement. In spring, wildflowers carpet the meadows in brilliant color, attracting hikers and photographers from around the world.

The trails here range from gentle walks suitable for families to challenging ridge climbs that reward with panoramic views.

<div class="rf-mediatext rf-mediatext--left rf-mediatext--1:1" data-align="left" data-ratio="1:1" data-rune="media-text" data-density="full">
  <div data-name="media" class="rf-mediatext__media" data-section="media" data-media="cover" data-guest-fit="clip">
    <img src="https://assets.refrakt.md/media-text-valley.jpg" alt="Mountain landscape" />
  </div>
  <div data-name="body" class="rf-mediatext__body" data-section="body">
    <p>The valley stretches out below, carved by millennia of glacial movement. In spring, wildflowers carpet the meadows in brilliant color, attracting hikers and photographers from around the world.</p>
    <p>The trails here range from gentle walks suitable for families to challenging ridge climbs that reward with panoramic views.</p>
  </div>
</div>

How Markdown is read

You writeIt becomes
An image on a line of its own, anywhere in the bodyThe media column; several such images all go there
Everything else: paragraphs, headings, lists, an image inside a sentenceThe text column, in the order written

Image on the right

Flip the layout by setting align="right".

{% mediatext align="right" ratio="1:2" %}
![Ancient forest](https://assets.refrakt.md/media-text-old-growth.jpg)

Old-growth forests like this one in the Pacific Northwest contain trees over 500 years old, forming dense canopies that filter sunlight into soft, dappled patterns on the forest floor. The thick understory of ferns and moss supports an ecosystem found nowhere else on earth.

Walking through these forests feels like stepping back in time. The silence is broken only by birdsong and the occasional crack of a falling branch, while the air carries the rich scent of cedar and damp earth.
{% /mediatext %}
<div data-rune="media-text" data-rune-fields="{&quot;align&quot;:&quot;right&quot;,&quot;ratio&quot;:&quot;1:2&quot;}">
  <div data-name="media">
    <img src="https://assets.refrakt.md/media-text-old-growth.jpg" alt="Ancient forest">
  </div>
  <div data-name="body">
    <p>Old-growth forests like this one in the Pacific Northwest contain trees over 500 years old, forming dense canopies that filter sunlight into soft, dappled patterns on the forest floor. The thick understory of ferns and moss supports an ecosystem found nowhere else on earth.</p>
    <p>Walking through these forests feels like stepping back in time. The silence is broken only by birdsong and the occasional crack of a falling branch, while the air carries the rich scent of cedar and damp earth.</p>
  </div>
</div>
Ancient forest

Old-growth forests like this one in the Pacific Northwest contain trees over 500 years old, forming dense canopies that filter sunlight into soft, dappled patterns on the forest floor. The thick understory of ferns and moss supports an ecosystem found nowhere else on earth.

Walking through these forests feels like stepping back in time. The silence is broken only by birdsong and the occasional crack of a falling branch, while the air carries the rich scent of cedar and damp earth.

<div class="rf-mediatext rf-mediatext--right rf-mediatext--1:2" data-align="right" data-ratio="1:2" data-rune="media-text" data-density="full">
  <div data-name="media" class="rf-mediatext__media" data-section="media" data-media="cover" data-guest-fit="clip">
    <img src="https://assets.refrakt.md/media-text-old-growth.jpg" alt="Ancient forest" />
  </div>
  <div data-name="body" class="rf-mediatext__body" data-section="body">
    <p>Old-growth forests like this one in the Pacific Northwest contain trees over 500 years old, forming dense canopies that filter sunlight into soft, dappled patterns on the forest floor. The thick understory of ferns and moss supports an ecosystem found nowhere else on earth.</p>
    <p>Walking through these forests feels like stepping back in time. The silence is broken only by birdsong and the occasional crack of a falling branch, while the air carries the rich scent of cedar and damp earth.</p>
  </div>
</div>

Text wrapping

Enable wrap for text that flows around the image rather than staying in a strict column.

{% mediatext align="left" ratio="2:1" wrap=true %}
![Japanese zen garden](https://assets.refrakt.md/media-text-zen-garden.jpg)

The Japanese zen garden, or *karesansui*, is an art form centuries in the making. Raked gravel represents flowing water, while carefully placed stones suggest mountains rising from the sea. Bonsai trees — shaped over decades of patient pruning — anchor the composition with gnarled trunks and delicate canopies that echo their full-sized counterparts in miniature.

In spring, cherry blossoms drift across the garden like pink snow, settling on the raked patterns and dissolving the boundary between the designed and the natural. The transience of the blossoms is central to the experience — a reminder that beauty is most vivid in its passing. Visitors often sit in silence on the wooden engawa, watching petals fall, letting the stillness of the garden quiet the mind.
{% /mediatext %}
<div data-rune="media-text" data-rune-fields="{&quot;align&quot;:&quot;left&quot;,&quot;ratio&quot;:&quot;2:1&quot;,&quot;wrap&quot;:&quot;true&quot;}">
  <div data-name="media">
    <img src="https://assets.refrakt.md/media-text-zen-garden.jpg" alt="Japanese zen garden">
  </div>
  <div data-name="body">
    <p>
      The Japanese zen garden, or
      <em marker="*">karesansui</em>
      , is an art form centuries in the making. Raked gravel represents flowing water, while carefully placed stones suggest mountains rising from the sea. Bonsai trees — shaped over decades of patient pruning — anchor the composition with gnarled trunks and delicate canopies that echo their full-sized counterparts in miniature.
    </p>
    <p>In spring, cherry blossoms drift across the garden like pink snow, settling on the raked patterns and dissolving the boundary between the designed and the natural. The transience of the blossoms is central to the experience — a reminder that beauty is most vivid in its passing. Visitors often sit in silence on the wooden engawa, watching petals fall, letting the stillness of the garden quiet the mind.</p>
  </div>
</div>
Japanese zen garden

The Japanese zen garden, or karesansui, is an art form centuries in the making. Raked gravel represents flowing water, while carefully placed stones suggest mountains rising from the sea. Bonsai trees — shaped over decades of patient pruning — anchor the composition with gnarled trunks and delicate canopies that echo their full-sized counterparts in miniature.

In spring, cherry blossoms drift across the garden like pink snow, settling on the raked patterns and dissolving the boundary between the designed and the natural. The transience of the blossoms is central to the experience — a reminder that beauty is most vivid in its passing. Visitors often sit in silence on the wooden engawa, watching petals fall, letting the stillness of the garden quiet the mind.

<div class="rf-mediatext rf-mediatext--left rf-mediatext--2:1 rf-mediatext--true" data-align="left" data-ratio="2:1" data-wrap="true" data-rune="media-text" data-density="full">
  <div data-name="media" class="rf-mediatext__media" data-section="media" data-media="cover" data-guest-fit="clip">
    <img src="https://assets.refrakt.md/media-text-zen-garden.jpg" alt="Japanese zen garden" />
  </div>
  <div data-name="body" class="rf-mediatext__body" data-section="body">
    <p>
      The Japanese zen garden, or 
      <em marker="*">karesansui</em>
      , is an art form centuries in the making. Raked gravel represents flowing water, while carefully placed stones suggest mountains rising from the sea. Bonsai trees — shaped over decades of patient pruning — anchor the composition with gnarled trunks and delicate canopies that echo their full-sized counterparts in miniature.
    </p>
    <p>In spring, cherry blossoms drift across the garden like pink snow, settling on the raked patterns and dissolving the boundary between the designed and the natural. The transience of the blossoms is central to the experience — a reminder that beauty is most vivid in its passing. Visitors often sit in silence on the wooden engawa, watching petals fall, letting the stillness of the garden quiet the mind.</p>
  </div>
</div>

Attributes

AttributeTypeRequiredDescription
align"left" | "right"—Side the media appears on
ratio"1:2" | "1:1" | "2:1"—Width ratio between media and text
wrapboolean—Wrap text around the media

Universal attributes

bg

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

AttributeTypeRequiredDescription
bgstring—Background preset applied to this block
bg-fromstring—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-tostring—Gradient end colour — a semantic token name
bg-viastring—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)
dropcap

Per-instance drop-cap opt-in.

AttributeTypeRequiredDescription
dropcapboolean—Style the opening letter of a prose body as a drop cap. Honoured only when the body reads as prose; ignored otherwise.
elevation

How far the rune sits off the page, from sunken to overlay. The theme decides what each step looks like.

AttributeTypeRequiredDescription
elevation"sunken" | "flush" | "flat" | "raised" | "floating" | "overlay" | "none" | "sm" | "md" | "lg"—Surface depth, from sunken to overlay. Deprecated: none, sm, md and lg (read as flat, raised, raised and floating)
frame

Surface chrome: a named preset from the theme registry with inline `frame-*` overrides layered on top.

AttributeTypeRequiredDescription
framestring—Named frame preset presenting this block's media surface
frame-anchorstring—Crop focal point when the guest is cut (object-position)
frame-aspectstring—Aspect ratio of the framed media, e.g. "16/9"
frame-displace"top" | "bottom" | "end" | "bottom-end" | "top-end" | "both"—Edge/corner the framed guest moves toward
frame-displace-mode"peek" | "bleed"—How displacement renders: `peek` (default) translates the guest visually inside its frame target; `bleed` uses negative margin on the media zone so following layout pulls up — extends past a section like a hero without leaving a gap above
frame-offset"none" | "sm" | "md" | "lg" | "xl" | "2xl" | "3xl" | "4xl"—Displacement distance (non-linear named scale: sm…xl ride the block-spacing tokens, 2xl/3xl/4xl step up to section-spacing for bleed-mode displacements that clear a section edge)
frame-overflow"clip" | "bleed"—How the frame handles a guest whose content is wider than it: `clip` (default) keeps it inside the rounded frame; `bleed` runs an overflowing guest out to the layout edge on a narrow viewport so it reads as cropped by the screen (a bleed host only — hero/feature)
frame-oversizestring—How far the guest exceeds its slot (scale factor)
frame-placestring—Guest-box alignment in the slot (e.g. "left top")
frame-shadow"none" | "sm" | "md" | "lg"—Silhouette drop-shadow strength for the framed media
inset

Internal padding override.

AttributeTypeRequiredDescription
inset"flush" | "tight" | "default" | "loose" | "breathe"—Inner padding of this block
motion

Scroll-reveal entrance. You choose its character; the theme decides how it moves.

AttributeTypeRequiredDescription
reveal"none" | "fade" | "slide" | "scale" | "blur"—Scroll-reveal entrance character (none|fade|slide|scale|blur); the theme owns the choreography
staggerboolean—Cascade this block's items in as it reveals (no-op on single-child runes)
reading

Editorial register for body text. You pick the register; the theme decides how it looks.

AttributeTypeRequiredDescription
reading"fine" | "ui" | "prose"—Reading register for this block’s body: fine | ui | prose. The theme sets how each one looks.
spacing

Block-level rhythm override.

AttributeTypeRequiredDescription
spacing"flush" | "tight" | "default" | "loose" | "breathe"—Vertical spacing above and below this block
substrate

Generated pattern fills behind the content, drawn by the theme.

AttributeTypeRequiredDescription
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)
tint

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

AttributeTypeRequiredDescription
tintstring—Color tint preset applied to this block
tint-mode"auto" | "dark" | "light"—Whether the tint adapts to auto, dark, or light mode
width

The track a block rune occupies.

AttributeTypeRequiredDescription
width"compact" | "narrow" | "content" | "wide" | "full"—Maximum width constraint for this block
Not availableWhy
prominencethis rune has no page-section header or featured quotation