📦 plugin-ideal-image

Docusaurus Plugin to generate an almost ideal image (responsive, lazy-loading, and low quality placeholder).

info

By default, the plugin is inactive in development so you could always view full-scale images. If you want to debug the ideal image behavior, you could set the disableInDev option to false.

Installation

npm

npm install --save @docusaurus/plugin-ideal-image

Yarn

yarn add @docusaurus/plugin-ideal-image

pnpm

pnpm add @docusaurus/plugin-ideal-image

Bun

bun add @docusaurus/plugin-ideal-image

Usage

This plugin supports the PNG and JPG formats only.

import Image from '@theme/IdealImage';
import thumbnail from './path/to/img.png';

// your React code
<Image img={thumbnail} />

// or
<Image img={require('./path/to/img.png')} />

attention

This plugin registers a Webpack loader that changes the type of imported/require images:

• Before: string
• After: {preSrc: string, src: import("@theme/IdealImage").SrcImage}

For pnpm users

Starting with pnpm 10, running pnpm install won't run dependency install scripts by default. You'll need additional pnpm configuration (issue) for our sharp image resizing dependency to install correctly, such as:

package.json

{
  "pnpm": {
    "onlyBuiltDependencies": ["fsevents"]
  }
}

Configuration

Accepted fields:

Option	Type	Default	Description
name	string	ideal-img/[name].[hash:hex:7].[width].[ext]	Filename template for output files.
sizes	number[]	original size	Specify all widths you want to use. If a specified size exceeds the original image's width, the latter will be used (i.e. images won't be scaled up).
size	number	original size	Specify one width you want to use; if the specified size exceeds the original image's width, the latter will be used (i.e. images won't be scaled up)
min	number		As an alternative to manually specifying sizes, you can specify min, max and steps, and the sizes will be generated for you.
max	number		See min above
steps	number	4	Configure the number of images generated between min and max (inclusive)
quality	number	85	JPEG compression quality
disableInDev	boolean	true	You can test ideal image behavior in dev mode by setting this to false. Tip: use network throttling in your browser to simulate slow networks.

Example configuration

Here's an example configuration:

docusaurus.config.js

export default {
  plugins: [
    [
      '@docusaurus/plugin-ideal-image',
      {
        quality: 70,
        max: 1030, // max resized image's size.
        min: 640, // min resized image's size. if original is lower, use that size.
        steps: 2, // the max number of images generated between min and max (inclusive)
        disableInDev: false,
      },
    ],
  ],
};