mirror of
https://github.com/facebook/docusaurus.git
synced 2025-04-29 10:17:55 +02:00
45f1a669b5
Co-authored-by: Joshua Chen <sidachen2003@gmail.com> Co-authored-by: sebastienlorber <lorber.sebastien@gmail.com>
92 lines
2.9 KiB
Text
92 lines
2.9 KiB
Text
---
|
|
sidebar_position: 8
|
|
slug: /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`](#disableInDev) option to `false`.
|
|
|
|
:::
|
|
|
|
## Installation {#installation}
|
|
|
|
```bash npm2yarn
|
|
npm install --save @docusaurus/plugin-ideal-image
|
|
```
|
|
|
|
## Usage {#usage}
|
|
|
|
This plugin supports the PNG and JPG formats only.
|
|
|
|
```jsx
|
|
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](https://webpack.js.org/loaders/) that changes the type of imported/require images:
|
|
|
|
- Before: `string`
|
|
- After: `{preSrc: string, src: import("@theme/IdealImage").SrcImage}`
|
|
|
|
:::
|
|
|
|
## Configuration {#configuration}
|
|
|
|
Accepted fields:
|
|
|
|
```mdx-code-block
|
|
<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](https://www.browserstack.com/guide/how-to-perform-network-throttling-in-chrome) in your browser to simulate slow networks. |
|
|
|
|
```mdx-code-block
|
|
</APITable>
|
|
```
|
|
|
|
### Example configuration {#ex-config}
|
|
|
|
Here's an example configuration:
|
|
|
|
```js title="docusaurus.config.js"
|
|
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
|
|
],
|
|
],
|
|
};
|
|
```
|