markdown-it-image-size

Automatically adds width and height attributes to img tags rendered by markdown-it. Supports both local and remote images.

If you'd rather set image sizes manually, check out @mdit/plugin-img-size.

[!NOTE] markdown-it-image-size does not support browsers. If you have a use case for using it in the browser, please open an issue.

Why

Browsers use the width and height attributes to determine aspect ratios of images. If the attributes are set, the browser can reserve space for the image even though it's not finished loading yet, thus preventing cumulative layout shifts after images load.

How to use

Basic usage

import MarkdownIt from "markdown-it";
import { markdownItImageSize } from "markdown-it-image-size";

const mdRenderer = MarkdownIt();
mdRenderer.use(markdownItImageSize);

Option: publicDir

Type: string Default: .

The publicDir option lets you specify a base URL for local images. This is useful when you're using a static site generator like Eleventy.

import MarkdownIt from "markdown-it";
import { markdownItImageSize } from "markdown-it-image-size";

const mdRenderer = MarkdownIt();
mdRenderer.use(markdownItImageSize, {
  publicDir: "/path/to/images",
});

Option: cache

Type: boolean Default: true

The cache option lets you disable caching of image dimensions. The cache is located in node_modules/markdown-it-image-size/.cache. Remove this directory to clear the cache.

import MarkdownIt from "markdown-it";
import { markdownItImageSize } from "markdown-it-image-size";

const mdRenderer = MarkdownIt();
mdRenderer.use(markdownItImageSize, {
  cache: false,
});

Option cacheFile

Type: string Default: dimensions.json

The cacheFile option lets you specify a custom cache file name.

import MarkdownIt from "markdown-it";
import { markdownItImageSize } from "markdown-it-image-size";
import path from "node:path";

const cacheFile = path.resolve(import.meta.dirname, "image-dimensions.json");
const mdRenderer = MarkdownIt();
mdRenderer.use(markdownItImageSize, {
  cacheFile,
});

Option: cacheDir

Type: string Default: node_modules/markdown-it-image-size/.cache

The cacheDir option lets you specify a custom cache directory. This is useful when you want to version control the cache.

import MarkdownIt from "markdown-it";
import { markdownItImageSize } from "markdown-it-image-size";
import path from "node:path";

const cacheDir = path.resolve(import.meta.dirname, "my-cache-dir");
const mdRenderer = MarkdownIt();
mdRenderer.use(markdownItImageSize, {
  cacheDir,
});

Option: overwriteAttrs

Type: boolean Default: false

The overwriteAttrs option lets you overwrite existing width and height attributes on img tags. This is useful when using another plugin which sets the attributes, such as @mdit/plugin-img-size.

import MarkdownIt from "markdown-it";
import { markdownItImageSize } from "markdown-it-image-size";
import { imgSize } from "@mdit/plugin-img-size";

const mdRenderer = MarkdownIt();
mdRenderer.use(imgSize).use(markdownItImageSize, {
  overwriteAttrs: true,
});

const html = mdRenderer.render(`![alt text](/path/to/image.jpg =100x200)`);
console.log(html);

// The attributes are overwritten with the correct dimensions (350x700).
// <p><img src="/path/to/image.jpg" alt="alt text" width="350" height="700"></p>

Examples

See the demo directory for usage with Eleventy and VitePress.

Development

This project uses tsup for bundling and Vitest for testing. It currently supports Node.js 20 and up. To get started, fork the repository and run the following commands:

# Install dependencies
npm install

# Build the project
npm run build

# Run tests
npm test

# Lint and format
npm run lint:fix

[!NOTE] The unit tests run on the build output, so make sure to run npm run build before running the tests if you have made changes to the source code.