doc: updated documentation for prefer-ideal-image

Azurinine · Azurinine · commit 27a484a8c05c · 2026-02-10T20:59:57.000-08:00
diff --git a/website/docs/api/misc/eslint-plugin/README.mdx b/website/docs/api/misc/eslint-plugin/README.mdx
@@ -54,6 +54,7 @@ For more fine-grained control, you can also enable the plugin manually and confi
 | [`@docusaurus/string-literal-i18n-messages`](./string-literal-i18n-messages.mdx) | Enforce translate APIs to be called on plain text labels | ✅ |
 | [`@docusaurus/no-html-links`](./no-html-links.mdx) | Ensures @docusaurus/Link is used instead of `<a>` tags | ✅ |
 | [`@docusaurus/prefer-docusaurus-heading`](./prefer-docusaurus-heading.mdx) | Ensures @theme/Heading is used instead of `<hn>` tags for headings | ✅ |
+| [`@docusaurus/prefer-ideal-image`](./prefer-ideal-image.mdx) | Ensures @theme/IdealImage is used instead of `<img>` tags for embedding images |  |
 
 ✅ = recommended
 
diff --git a/website/docs/api/misc/eslint-plugin/prefer-ideal-image.mdx b/website/docs/api/misc/eslint-plugin/prefer-ideal-image.mdx
@@ -0,0 +1,50 @@
+---
+slug: /api/misc/@docusaurus/eslint-plugin/prefer-ideal-image
+---
+
+# prefer-ideal-image
+
+Ensure that the `<IdealImage />` component provided by the [`@docusaurus/plugin-ideal-image`](../../plugins/plugin-ideal-image.mdx) plugin is used instead of standard `<img>` tags for local assets.
+
+The `@theme/IdealImage` component automatically generates responsive images, provides lazy-loading, and adds low-quality image placeholders (LQIP) to improve LCP and user experience.
+
+## Rule Details {#details}
+
+This rule flags standard HTML `<img>` tags that point to local files, suggesting the use of `IdealImage` for better optimization.
+
+Examples of **incorrect** code for this rule:
+
+```jsx
+// Error: Definitely a local image via require()
+<img src={require('./thumbnail.png')} />
+
+// Warning: Likely a local image via relative path
+<img src="./img/logo.png" />
+
+// Warning: Root-relative path usually points to the static folder
+<img src="/img/hero.jpg" />
+```
+
+Examples of **correct** code for this rule:
+
+```jsx
+// Optimized using the IdealImage component
+import IdealImage from '@theme/IdealImage';
+
+<IdealImage img={require('./thumbnail.png')} />
+
+// External images are ignored
+<img src="[https://example.com/external.png](https://example.com/external.png)" />
+
+// SVGs are ignored as IdealImage does not support them
+<img src="./icon.svg" />
+```
+
+## When to not use it
+
+If you have not installed or do not plan to use @docusaurus/plugin-ideal-image, you should keep this rule disabled.
+
+## Further Reading {#further-reading}
+
+- https://docusaurus.io/docs/api/plugins/@docusaurus/plugin-ideal-image
+- https://web.dev/articles/browser-level-image-lazy-loading
