{
  "$type": "site.standard.document",
  "bskyPostRef": {
    "cid": "bafyreidiykzcgdcarwzf6t3j37udlksbna6hwxvn5feos23m3q7tbk7udm",
    "uri": "at://did:plc:t4aigbwuwix7x3q42qzjc6mn/app.bsky.feed.post/3mf6tqo5arw32"
  },
  "coverImage": {
    "$type": "blob",
    "ref": {
      "$link": "bafkreiarvja3nxyesd2ra34odtnibzd4b4qbhg4btcjt2gtkl3pgke3mla"
    },
    "mimeType": "image/jpeg",
    "size": 22024
  },
  "path": "/link/535/17278639/apex-and-multiple-image-formats",
  "publishedAt": "2026-02-18T16:05:00.000Z",
  "site": "https://brett.trpstra.net",
  "tags": [
    "Apex wiki",
    "on Mastodon",
    "Bluesky",
    "Twitter",
    "Click here if you'd like to help out.",
    "Mastodon",
    "GitHub",
    "everywhere else",
    "@2x",
    "@3x"
  ],
  "textContent": "Here’s part two of my Apex posts for the day: Multiple image formats from a single image syntax.\n\nModern 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.\n\nApex 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:\n\n  * image.png\n  * image@2x.png\n  * image.webp\n  * image@2x.webp\n  * image.avif\n  * image@2x.avif\n\n\n\nNow you can generate a `<picture>` (and optionally a `<figure>` with captions) with a single line of Markdown.\n\n### WebP and AVIF\n\nAdd `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.\n\n\n    ![Hero image](img/hero.png webp) ![Hero AVIF](img/hero.png avif)\n\nYou can combine both for maximum compatibility:\n\n\n    ![Modern formats](img/banner.jpg webp avif)\n\nBoth attributes work with `@2x` for retina. So `![Retina](img/hero.png webp @2x)` 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.\n\n### Auto discovery\n\nIf you’d rather not list every format by hand, use the `auto` attribute:\n\n\n    ![Profile menu](img/app-pass-1-profile-menu.jpg auto)\n\nWhen `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.\n\nYou can also use `*` as the extension, which does the same thing:\n\n\n    !Profile menu\n\nThat 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 `![](image.png auto)`.\n\n### Video: same syntax, different element\n\nVideo 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>`:\n\n\n    !Demo video\n\nThat becomes `<video><source src=\"https://brettterpstra.commedia/demo.mp4\" type=\"video/mp4\"></video>`. No extra syntax needed.\n\nTo add alternative formats for broader browser support, tack on the format name:\n\n\n    ![Demo with WebM](media/demo.mp4 webm) ![Demo with OGG](media/intro.mp4 ogg)\n\nApex 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 `![](video.mp4 ogg)` gives you an ogg source plus the mp4 fallback.\n\nLike I said, using `auto` or `demo.*` as a video URL will generate markup for all the existing formats.\n\n### What This Means\n\nIt 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.\n\nThe `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.\n\n### Quick reference\n\nSyntax | Result\n---|---\n`![alt](url webp)` | `<picture>` with WebP source\n`![alt](url avif)` | `<picture>` with AVIF source\n`![alt](url webp @2x)` | WebP with retina srcset\n`![alt](url auto)` | Discovers formats from disk (requires base_directory)\n`!alt` | Same as auto—scans jpg/png/gif/webp/avif and video formats\n`!alt` | `<video>` with mp4 source\n`![alt](video.mp4 webm)` | `<video>` with webm + mp4 fallback\n\nSame Markdown image syntax, better output. Check out the Apex wiki for more details.\n\nLike or share this post on Mastodon, Bluesky, or Twitter.\n\n* * *\n\nBrettTerpstra.com is supported by readers like you. Click here if you'd like to help out.\n\nFind Brett on Mastodon, Bluesky, GitHub, and everywhere else.",
  "title": "Apex and Multiple Image Formats",
  "updatedAt": "2026-02-18T16:05:00.000Z"
}