The `imageDimensions` feature reads image file headers at build time and injects `width` and `height` attributes onto local `<img>` elements, preventing Cumulative Layout Shift (CLS) by letting the browser reserve space before the image loads.

:::note[Functional since zfb next.38]

Through zfb `0.1.0-next.35` this feature was a no-op for public-directory absolute paths — an image such as `![alt](/img/x.png)` was emitted with no `width`/`height` injected. As of zfb `0.1.0-next.38` it works: dimensions are injected for public-directory images on this corpus, and a missing file produces a `cannot stat` build warning.

:::

## Configuration

It is an object-typed feature, so it must be given an options object (`{}` or fields):

```ts title="zfb.config.ts"
export default defineConfig({
  markdown: {
    features: {
      imageDimensions: {},
    },
  },
});
```

## Behavior

For each image element, the feature:

1. Skips elements that already carry a `width` or `height` attribute.
2. Ignores remote URLs (`http://`, `https://`, `//`) and `data:` URLs.
3. Resolves the `src` to an absolute file path on disk.
4. For raster formats, reads only the image file header and injects the resolved dimensions.
5. For SVG, reads the intrinsic size from the markup instead of a header probe: an explicit `width`/`height` pair when present, otherwise the `viewBox`.
6. Emits a build warning if the file is missing or unrecognized.

Supported formats: PNG, JPEG, GIF, WebP, AVIF (header-probed), and SVG (dimensions read from markup, not a header probe).

## Path resolution

| Path form | Resolves against |
| --- | --- |
| Absolute (`/img/hero.png`) | the `public` directory |
| Relative (`./assets/hero.png`) | the markdown file's directory |
| Remote / `data:` | skipped silently |

## Options

| Option | Default | Description |
| --- | --- | --- |
| `skipRemote` | `true` | When `false`, remote images are probed during the build instead of being skipped. |

## Syntax

A standard markdown image is all that is required — no special syntax:

```md
![Hero image](/img/hero.png)
```

The output for a 400×300 PNG is:

```html
<img src="/img/hero.png" alt="Hero image" width="400" height="300" />
```