Skip to content

Latest commit

 

History

History
92 lines (67 loc) · 2.9 KB

plugin-ideal-image.mdx

File metadata and controls

92 lines (67 loc) · 2.9 KB
sidebar_position slug
8
/api/plugins/@docusaurus/plugin-ideal-image

📦 plugin-ideal-image

import APITable from '@site/src/components/APITable';

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 {#installation}

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

Usage {#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')} />

:::warning

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

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

:::

Configuration {#configuration}

Accepted fields:

<APITable>
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. 
</APITable>

Example configuration {#ex-config}

Here's an example configuration:

export default {
  plugins: [
    [
      '@docusaurus/plugin-ideal-image',
      // highlight-start
      {
        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,
      },
      // highlight-end
    ],
  ],
};