Multi Format Images

Multi-Format Images

Apex extends standard Markdown image syntax with attributes for serving multiple image formats (WebP, AVIF), retina variants (@2x, @3x), and automatic format discovery. It also detects video URLs and emits <video> elements instead of <img> when appropriate.

These features are available in unified, MultiMarkdown, and GFM modes.

Retina / @2x and @3x

Add @2x or @3x after the URL to generate a srcset for high-DPI displays. Apex assumes the variant has the same path with @2x or @3x inserted before the file extension (e.g. icon.png → icon@2x.png).

![Alt](img/icon.png @2x)
![Alt](img/hero.png @2x @3x)

Inline:

![Alt](img/icon.png @2x)
![Alt](img/icon.png "title" @2x)

Reference-style:

![Logo][logo]

[logo]: img/hero.png @2x

With IAL:

![Alt](img/icon.png){: @2x}

Output:

<img src="img/icon.png" srcset="img/icon.png 1x, img/icon@2x.png 2x" alt="Alt">

WebP and AVIF

Add webp or avif after the URL and Apex wraps the image in a <picture> element with the appropriate <source> tags. Browsers that support the format use it; others fall back to the main image.

![Hero](img/hero.png webp)
![Hero](img/hero.png avif)
![Modern formats](img/banner.jpg webp avif)

Both attributes combine with @2x and @3x for retina srcsets:

![Retina WebP](img/hero.png webp @2x)
![Retina AVIF](img/hero.png avif @2x)

Auto discovery

Use the auto attribute to discover formats from the filesystem. When base_directory is set (e.g. from the document path or --base-directory), Apex checks for existing variants and emits <picture> or <video> with only the variants that exist.

For images, Apex looks for:

• 2x and 3x variants (e.g. image@2x.png, image@3x.png)
• WebP and AVIF versions (e.g. image.webp, image.avif)

![Profile menu](img/app-pass-1-profile-menu.jpg auto)

Wildcard extension (*)

Using * as the extension is equivalent to auto. It scans for jpg, png, gif, webp, and avif (plus 2x and 3x variants) for images, and mp4, webm, ogg, mov, and m4v for videos.

![Profile menu](img/app-pass-1-profile-menu.*)

![](image.*) is equivalent to ![](image.png auto). The base filename is derived from the path; Apex discovers which formats exist on disk and generates the appropriate <picture> or <video> element.

Video URLs

When the image URL ends in a video extension (mp4, mov, webm, ogg, ogv, m4v), Apex emits a <video> tag instead of <img>:

![Demo video](media/demo.mp4)

Output:

<video><source src="media/demo.mp4" type="video/mp4"></video>

Video format alternatives

Add format attributes to include alternative sources for broader browser support:

![Demo with WebM](media/demo.mp4 webm)
![Demo with OGG](media/intro.mp4 ogg)

Apex adds <source> elements for each format. The primary URL stays as the fallback; the attributes add webm, ogg, or other formats before it.

Video with auto or *

When using auto or * with a video base filename, Apex discovers which video formats exist (mp4, webm, ogg, mov, m4v) and emits a <video> element with the appropriate <source> tags.

Quick reference

Syntax	Result
	srcset with 1x and 2x
	srcset with 1x, 2x, and 3x
	<picture> with WebP source
	<picture> with AVIF source
	WebP with retina srcset
	Discovers formats from disk (requires base_directory)
	Same as auto—scans image and video formats
	<video> with mp4 source
	<video> with webm + mp4 fallback

Requirements

• base_directory must be set for auto and * to discover files. It is typically set automatically when processing a file, or via --base-directory or metadata.
• Format attributes (webp, avif, @2x, @3x) work without base_directory; they generate URLs based on naming conventions.
• Video format attributes (webm, ogg, etc.) also work without base_directory; they generate additional <source> elements from the primary URL path.

See also

• Syntax — Full syntax reference
• Inline Attribute Lists — IAL syntax for images