# Device Variants

Wrap any markdown in `mobile:` / `/mobile` or `desktop:` / `/desktop` to show different content depending on the visitor's viewport. Switching is pure CSS — no JavaScript, no flash of wrong content.

```markdown
desktop:
This shows on screens wider than 768px.
/desktop

mobile:
This shows on screens 768px and narrower.
/mobile
```

## When would I use this?

The most common case is embedding a different video for desktop and mobile — a wide landscape cut for desktop and a portrait or square cut for mobile, since the same file rarely flatters both. But device variants work with any markdown, so they're useful any time the desktop and mobile experiences should differ in content (not just layout).

| Use case | Example |
|---|---|
| Different videos per device | Landscape demo on desktop, portrait demo on mobile |
| Different images per device | Wide hero on desktop, square hero on mobile |
| Touch vs. click copy | "Tap to continue" on mobile, "Click to continue" on desktop |
| Mobile-only callouts | A "Best viewed on desktop" notice that only mobile visitors see |
| Desktop-only diagrams | A wide architecture diagram desktop visitors see, hidden on mobile to save bandwidth |
| Different button labels | A short label on mobile, a longer one on desktop |

If you only need to change *layout* (not content), reach for CSS via [Inline HTML](/docs/inline-html) or theme styles instead — device variants are about swapping content, not styling it.

## How does it work?

Each fence wraps its content in a `<div class="device-only device-mobile">` or `device-desktop`. A media query in the theme hides the wrong variant at the 768px breakpoint:

- `device-desktop` is visible above 768px, hidden at or below
- `device-mobile` is visible at or below 768px, hidden above

Both variants are present in the HTML — only one is rendered to the screen. This means:

- **No JavaScript runs.** The browser handles the swap with CSS.
- **No layout flash.** Visitors never see the wrong variant before it's hidden.
- **Both variants are crawlable.** Search engines and AI crawlers see both, which is usually what you want.
- **Both variants download.** Hidden videos still issue a `preload="metadata"` request, and hidden images still load. Keep both files reasonably sized.

## Different videos per device

The canonical use case. Cut a landscape video for desktop and a portrait or square one for mobile, then drop them into separate fences:

```markdown
desktop:
![Product demo](/media/demo-web.mp4 +autoplay +width:1200 +corner:curve)
/desktop

mobile:
![Product demo](/media/demo-mobile.mp4 +autoplay +corner:curve)
/mobile
```

See [Videos](/docs/videos) for the full list of video modifiers.

## Different images per device

Same pattern works for hero images, banners, and any other visual where a single aspect ratio doesn't fit both viewports:

```markdown
desktop:
![Hero](/media/hero-wide.jpg +corner:curve)
/desktop

mobile:
![Hero](/media/hero-square.jpg +corner:curve)
/mobile
```

## Different copy per device

Device fences wrap any markdown — paragraphs, lists, buttons, headings:

```markdown
desktop:
Click the **Download** button below to get started.
button: Download for Mac: /downloads/mac
button: Download for Windows: /downloads/windows
/desktop

mobile:
Tap below to download — we'll detect your platform automatically.
button: Download: /downloads
/mobile
```

## Combining with other fences

Device fences nest inside (or alongside) [alignment fences](/docs/content-alignment), [hidden fences](/docs/hidden-content), and [gated sections](/docs/user-auth#gated-sections):

```markdown
center:
desktop:
![Wide demo](/media/demo-web.mp4 +autoplay +width:1200)
/desktop

mobile:
![Tall demo](/media/demo-mobile.mp4 +autoplay)
/mobile
/center
```

## What about more than two breakpoints?

Device variants are intentionally simple — just `mobile:` and `desktop:` at a single 768px breakpoint. If you need finer control (tablet, large desktop, print), drop down to [Inline HTML](/docs/inline-html) and write your own media queries against the theme's CSS variables.

## Syntax reference

| Fence | Visible when |
|---|---|
| `mobile:` / `/mobile` | Viewport is 768px or narrower |
| `desktop:` / `/desktop` | Viewport is wider than 768px |

Both fences are block-level — each fence tag must be on its own line. Content inside fenced code blocks is not processed.