3.7 KiB
Cookbook: Add a plugin feature preview
English | 中文
A feature preview is an optional illustration at the top of a bundle's detail document, the long description that its page in Plugins shows first. Follow this guide when drawing one for an official bundle. The detail document itself is declared through meta.detail.
1. Decide whether an image helps
Show one concrete result or recognizable capability. Omit the image when the description is enough: no image is required. Essential instructions stay in the document's text or in configuration outside the illustration.
2. Draw one fixed-size SVG
| Item | Requirement |
|---|---|
| Count | Zero or one feature image per bundle. English and Chinese files are alternatives for that image, not a gallery or carousel. |
| Format | SVG: width="640" height="300" viewBox="0 0 640 300" (32:15). |
| Languages | Supply both an English and a Chinese file. Translate headings, annotations, and example content; preserve official brand assets and names. |
| Composition | One main example, optionally with one close-up. Keep important content about 32 canvas units from the edges. Review text at the page's actual size. |
| Typography | Outline lettering into paths using a suitable font. Match the feature and neighboring UI; do not rely on browser font substitution. |
| Theme | Compare light and dark themes. One illustration serves both; avoid transparent dark text that disappears on dark backgrounds. |
The SVG is self-contained: no fonts, remote resources, scripts, handlers, animation, stylesheets, text, or foreignObject. An image element may embed an unchanged official PNG/JPEG/WebP brand asset as a base64 data URL. Small plugin icons remain geometry-only. The page renders the SVG through <img>. Keep each file small; the Host refuses images above plugin-manager's detailImageMaxBytes, 5 MiB by default.
3. Put it at the top of the detail document
Save the pair as docs/preview.svg and docs/preview.zh.svg in the bundle package, beside docs/DETAIL.md and docs/DETAIL.zh.md, and make the image the first line of each document:
The Chinese document references preview.zh.svg with Chinese alternative text. Use the badge skill and voice input documents as examples. The voice transcript is explanatory sample content, not a recording result.
4. Page behavior
| Item | Current behavior |
|---|---|
| Position | First in the detail document, which is the first section of the bundle page, below the description and status notices. |
| Display | The detail document renders the image at most its own width, inside its height-bounded scroll area. |
| Language | The document for the UI language references its own file. |
| Availability | Visible before activation. Lists and component rows keep their small icons. |
5. Validate and review
scripts/plugin-preview-assets.spec.ts checks every preview pair in a bundle's docs directory: the fixed canvas, absent scripts, stylesheets, text elements, and external references, the 1 MiB pair limit, and English and Chinese files that differ. Then open the real plugin details in English and Chinese before activation and confirm the image loads, its placement, light/dark readability, and no horizontal overflow at 390 px; review owns visual quality and equivalent meaning in both languages. Follow record-browser-gif for PR evidence; record from the final clean commit and label the demonstrated flow accurately.