Here’s part two of my Apex posts for the day: Multiple image formats from a single image syntax.
Modern browsers support a bunch of image formats, like WebP and AVIF, that are smaller and sharper than good old PNG and JPEG. The trick is serving them without breaking older browsers. Apex makes that easy with a few attributes on your image syntax.
Apex isn’t going to generate the additional images themselves, of course, that’s up to you. But if you have a series of images in the same directory, inserting them properly is super simple now. Take a directory with:
Now you can generate a <picture> (and optionally a <figure> with captions) with a single line of Markdown.
Add webp or avif after the URL and Apex wraps the image in a <picture> element with the right <source> tags. Browsers that support the format use it; everyone else falls back to the main image.
You can combine both for maximum compatibility:
Both attributes work with @2x for retina. So  produces a srcset with img.webp at 1x and img@2x.webp at 2x. Same deal for avif. Apex also recognizes @3x, if you need that.
If you’d rather not list every format by hand, use the auto attribute:
When base_directory is set (e.g. from the document path or --base-directory), Apex checks the filesystem for existing variants. For images it looks for 2x, 3x, webp, and avif. It only emits <source> elements for files that actually exist, so you can add formats over time without touching the Markdown.
You can also use * as the extension, which does the same thing:
That scans for jpg, png, gif, webp, and avif (plus 2x and 3x variants) for images, and mp4, webm, ogg, mov, and m4v for videos.  is equivalent to .
Video URLs in image syntax get special treatment. If the URL ends in mp4, mov, webm, ogg, ogv, or m4v, Apex emits a <video> tag instead of <img>:
That becomes <video><source src="media/demo.mp4" type="video/mp4"></video>. No extra syntax needed.
To add alternative formats for broader browser support, tack on the format name:
Apex adds <source> elements for each format you specify. The primary URL (e.g. demo.mp4) stays as the fallback; the attributes add webm, ogg, or whatever before it. So  gives you an ogg source plus the mp4 fallback.
Like I said, using auto or demo.* as a video URL will generate markup for all the existing formats.
It means proper, accessible markup, and optimized web pages. It won’t mean much if your output goal is PDF or DOCX, but it’s great for web production.
The auto and ` *` syntaxes mean you can write the Markdown once, and then every time you add a new format or resolution, the correct markup will be generated the next time you render, without touching the Markdown.
| Syntax | Result |
|---|---|
 |
<picture> with WebP source |
 |
<picture> with AVIF source |
 |
WebP with retina srcset |
 |
Discovers formats from disk (requires base_directory) |
 |
Same as auto—scans jpg/png/gif/webp/avif and video formats |
 |
<video> with mp4 source |
 |
<video> with webm + mp4 fallback |
Same Markdown image syntax, better output. Check out the Apex wiki for more details.
Brett is a writer and developer living in Minnesota, USA. You can follow him as ttscoff on GitHub, Mastodon, and elsewhere.
Sign up for the email newsletter, and keep up with this blog by adding it to your favorite news reader, or following it on Bluesky or Mastodon at @brettterpstra.com@web.brid.gy.