feat(docs): enable image fallback hints and upgrade plugin to 0.2.0

Author: jsmith3rd

docs/.vitepress/theme/index.ts

@@ -5,6 +5,7 @@ import '@binarynoir/vitepress-markdown-tags/style.css';
 import { enableGlossaryTooltips } from 'markdown-it-glossary/client';
 import { enableHtmlEscapeHints } from '@binarynoir/vitepress-html-escape/client';
 import { enableBrokenLinkHints } from '@binarynoir/vitepress-broken-links/client';
+import { enableImageFallbackHints } from '@binarynoir/vite-plugin-image-fallback/client';
 import './custom.css';
 
 export default {
@@ -18,5 +19,7 @@ export default {
     enableHtmlEscapeHints();
     // Wavy underlines and popovers on links to pages that don't exist.
     enableBrokenLinkHints();
+    // Dashed outlines and popovers on placeholders for images that are missing.
+    enableImageFallbackHints();
   },
 } satisfies Theme;

docs/guide/how-this-site-works.md

@@ -46,15 +46,15 @@ docs/
 | Pages left out by `.exclude`    | [Exclude](/plugins/exclude/)                  | `srcExclude` and `vite.plugins`       |
 | `README.md` as a folder's index | [README Index](/plugins/readme-index/)        | `rewrites` and `markdown.config`      |
 | Smaller images                  | [Optimize Images](/plugins/optimize-images)   | `vite.plugins`                        |
-| Placeholder for a missing image | [Image Fallback](/plugins/image-fallback)     | `vite.plugins`                        |
+| Placeholder for a missing image | [Image Fallback](/plugins/image-fallback)     | `vite.plugins`, plus the theme        |
 
 ## The config
 
 <<< @/.vitepress/config.mts{ts}
 
 ## The theme
 
-The theme registers the badge component and loads its stylesheet, and turns on the three popovers: glossary definitions, the HTML Escape hints that explain broken markup, and the Broken Links hints that explain dead links:
+The theme registers the badge component and loads its stylesheet, and turns on the four popovers: glossary definitions, the HTML Escape hints that explain broken markup, the Broken Links hints that explain dead links, and the Image Fallback hints that explain missing images:
 
 <<< @/.vitepress/theme/index.ts{ts}
 

docs/plugins/image-fallback.md

@@ -18,7 +18,13 @@ The image below points at a file that does not exist on purpose: `./missing-imag
 
 ![This image is intentionally missing to demonstrate the fallback](./missing-image-demo.png)
 
-When you run the build or look at the deploy log, you will see the warning for it. That warning is the plugin working as designed.
+Hover the placeholder, or click or tap it, to see what is missing and where it was imported from. When you run the build or look at the deploy log, you will see the same file and line in the warning:
+
+```txt
+[vite-plugin-image-fallback] Could not find …/docs/plugins/missing-image-demo.png (imported by plugins/image-fallback.md:19). Using fallback image.
+```
+
+That warning is the plugin working as designed.
 
 ## Install
 
@@ -46,6 +52,7 @@ Only relative (`./foo.png`) and root-relative (`/foo.png`) imports are intercept
 | `extensions` | `jpg, jpeg, png, gif, svg, webp, avif` | Extensions treated as image imports.          |
 | `fallback`   | gray "Missing Image Asset" SVG         | A data URI, or any URL string Vite can serve. |
 | `silent`     | `false`                                | Suppress the console warning.                 |
+| `hints`      | `true`                                 | Record what is missing, for the hints below.  |
 
 ```ts
 imageFallbackPlugin({
@@ -54,4 +61,25 @@ imageFallbackPlugin({
 });
 ```
 
+## Hints
+
+Turn on the popovers in your theme. They work the same way as [Broken Links](/plugins/broken-links) and [HTML Escape's hints](/plugins/html-escape/#hints), and all three run side by side on this site.
+
+```ts
+// .vitepress/theme/index.ts
+import DefaultTheme from 'vitepress/theme';
+import { enableImageFallbackHints } from '@binarynoir/vite-plugin-image-fallback/client';
+
+export default {
+  extends: DefaultTheme,
+  enhanceApp() {
+    enableImageFallbackHints();
+  },
+};
+```
+
+Each placeholder gets a dashed outline and a popover that names the missing import, and the file and line that imported it. The plugin records them in a `#image-fallback=…` fragment on the placeholder's URL, which the browser ignores when it loads the image.
+
+`enableImageFallbackHints(options)` takes `hover` (default `true`), `hoverDelay` (default `300` milliseconds) and `injectStyles` (default `true`), the same options as Broken Links. The colors follow the VitePress theme and can be changed with the `--image-fallback-hint-error` CSS variable.
+
 [Source and full README on GitHub](https://github.com/binarynoir/vite-plugin-image-fallback)

package-lock.json

@@ -22,7 +22,7 @@
     "format:check": "prettier --check ."
   },
   "devDependencies": {
-    "@binarynoir/vite-plugin-image-fallback": "^0.1.9",
+    "@binarynoir/vite-plugin-image-fallback": "^0.2.0",
     "@binarynoir/vite-plugin-optimize-images": "^0.1.9",
     "@binarynoir/vitepress-auto-navbar": "^0.3.0",
     "@binarynoir/vitepress-auto-sidebar": "^0.5.0",