# Image Variants

Marked can automatically build responsive `<picture>` elements for local images when companion dark mode and Retina files sit next to the image you reference. This uses the same naming conventions as Apple’s DocC documentation catalogs, but works for any Markdown or HTML document with normal image paths that include a file extension.

See also DocC Support for extensionless catalog references inside `.docc` bundles.

Contents

- Enabling image variants
- Naming convention
- What gets rewritten
- What is skipped
- Live preview and file watching
- Tips
- Related topics

## Enabling image variants

In Marked Settings, Apps pane, enable Resolve dark and @2x image variants (on by default) under DocC settings.

This preference is separate from Resolve DocC image references, which only applies inside `.docc` catalogs. You can use one, both, or neither depending on your project.

## Naming convention

Place variant files in the same folder as the primary image. Marked looks for four combinations based on the base name:

Role | Example filename
--- | ---
Light (1x) | `icon.png`
Dark (1x) | `icon~dark.png`
Light (2x) | `icon@2x.png`
Dark (2x) | `icon~dark@2x.png`

Suffix order is flexible — `icon@2x~dark.png` and `icon~dark@2x.png` are treated the same way.

Supported extensions: `png`, `jpg`, `jpeg`, `gif`, `svg`, `webp`, and `pdf`.

## What gets rewritten

Marked scans your document before final preview rendering:

- Markdown: `![Alt text](images/icon.png)`
- HTML: `<img src="images/icon.png?46" alt="Alt text">`

If at least two matching variant files exist on disk, the reference is replaced with a `<picture>` block. A single extra file is enough — you do not need all four variants.

Example output when light, dark, and @2x files are present:

    <picture>
      <source media="(prefers-color-scheme: dark)" srcset="images/icon~dark.png 1x, images/icon~dark@2x.png 2x">
      <source srcset="images/icon.png 1x, images/icon@2x.png 2x">
      <img src="images/icon.png?46" alt="Alt text">
    </picture>

The preview (and HTML export) then follows the user’s system appearance for dark variants and device pixel density for @2x assets.

## What is skipped

Marked does not rewrite:

- Remote URLs (`http://`, `https://`, `data:`)
- References that already point at a `~dark` file
- `<img>` tags already inside an existing `<picture>` element
- Extensionless names like `![Diagram](diagram)` — use DocC Support for catalog-style references

## Live preview and file watching

When variants are detected, Marked adds every existing variant file to its watch list alongside the main document. Saving `icon~dark.png` in an external editor triggers the same live image reload as editing `icon.png`.

## Tips

- Reference the light 1x image in your source when possible (`icon.png`, not `icon~dark.png`). Marked discovers siblings from that path.
- If you only have `@2x` assets, include at least one other variant (typically `~dark`) or Marked will leave the reference unchanged.
- Variant resolution uses paths relative to the document (or the included file’s folder for nested includes), the same base path rules as Multi-file Documents.

## Related topics

- DocC Support — extensionless image names inside `.docc` catalogs
- Settings: Apps — preference toggles for DocC and image variants
- Previewing — live preview and file updates

#### Next up: Link Validation ▶

Support Site | Legal | Privacy