Build Optimization
Image Optimization Experimental
When we embed images in markdown using [alt](url) or <img src="url">, the page displays the images as expected.
However, due to different image sizes, when images are small or network conditions are good, we may not notice significant layout shifts. When images are large or network conditions are poor, the layout can change noticeably as images load, causing other content to shift.
This experience is not user-friendly, especially with many images on a page. Frequent layout changes can cause noticeable jitter.
To stabilize the layout, images must be optimized. According to MDN > img:
Info
<img> with both height and width allows the browser to calculate the image's aspect ratio before loading. This reserves space for the image, reducing or preventing layout shifts during download and rendering. Reducing layout shifts is crucial for good user experience and web performance.
Our theme provides a solution: automatically adding width and height attributes to [alt](url) or <img src="url"> in markdown files.
Enable it by configuring markdownPower:
export default defineUserConfig({
theme: plumeTheme({
plugins: {
markdownPower: {
imageSize: true, // 'local' | 'all'
},
}
})
})When enabled, the theme retrieves the original dimensions of images from their source URLs and adds width and height attributes.
'local': Only adds attributes to local images.'all': Adds attributes to both local and remote images.true: Equivalent to'local'.
Important
For performance reasons, this feature only takes effect during production build.
Important
Use 'all' cautiously. It requests all remote images during production build, which can increase build time for sites with many images. The theme optimizes this by only requesting a few KB of data to analyze dimensions and processing images concurrently.
Icon Optimization
Thanks to the open-source project iconify, you can use approximately 200,000 icons in our theme.
However, this doesn't mean the theme needs to load all icons. You may have noticed the theme recommends installing the @iconify/json package locally, which requires downloading a 70Mb resource pack. Loading all icons into the documentation site would be excessively large.
But rest assured, the theme only loads the icon resources you actually use. This includes Iconify icons in navigation, sidebar, homepage Features, and icons used via the :[collect:name]: syntax or <Icon name="icon_name" /> component.
When loading icons from local @iconify/json, iconify names icons by [collect]:[name], with each collection containing 100 to 1000+ icons in a json file. Using many different collect icons can slow down initial loading and parsing. For example, our theme uses 54 collect collections with over 160 icons, taking about 500ms to load and parse initially.
To optimize, the theme caches used icons on first launch. On subsequent launches, it优先从缓存加载图标， which is much faster than parsing different collect collections. This reduces loading time from 500ms to 20ms or less, also improving development server startup time!
Info
Using 54 collect collections is extreme. While 500ms for 54 I/O reads and JSON parses seems normal, it's unexpected for only 160+ icons. Caching these icons is a good solution.
