Image Dimensions

Injects width/height attributes on images from disk metadata at build time.

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.

Configuration

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

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

Options

Syntax

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

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

The output for a 400×300 PNG is:

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