Build Optimization
Image Dimension Optimization Experimental
When embedding images in Markdown documents via  or <img src="url">, the content displays correctly, but potential layout stability issues are often overlooked.
Layout Shift Analysis
Layout shifts are not obvious when images are small or network conditions are good. However, with large images or poor network conditions, layout reflow during image loading becomes prominent:
- Before Loading: Image placeholder space is not reserved, subsequent content is pushed up
- After Loading: Image suddenly occupies space, forcing subsequent content to reflow
- User Experience: Frequent layout changes cause visual jumps and operation lag
Solution: Pre-calculate Image Dimensions
According to MDN documentation, specifying both height and width attributes allows browsers to calculate the image aspect ratio in advance and reserve display space, eliminating layout shifts at the source.
Automated solution provided by the theme:
export default defineUserConfig({
theme: plumeTheme({
plugins: {
markdownPower: {
imageSize: true, // Optional 'local' | 'all'
},
}
})
})Configuration Options:
'local'ortrue: Only add dimension attributes for local images'all': Process both local and remote image resources
Implementation Mechanism:
- Automatically analyze original image dimensions during build
- Inject precise
widthandheightattributes into<img>tags - Reserve display space based on image aspect ratio
Performance Considerations
- This feature only takes effect in production builds to avoid performance overhead during development
- Using the
'all'option requests all remote image resources, which may significantly increase build time - Optimization strategy: Concurrent requests + header information analysis, terminating connections immediately after obtaining dimension data
Icon Loading Optimization
Iconify Integration Benefits
The theme deeply integrates with the Iconify project, providing access to over 200,000 icons with flexible selection. Although locally installing the @iconify/json package requires approximately 70MB of storage, only the actually used icon resources are included in the build, achieving on-demand loading.
Performance Bottlenecks and Solutions
Root Cause: Icons are organized by collections, with each collection containing JSON files of 100-1000+ icons. When using icons from multiple different collections, frequent I/O reads and JSON parsing create significant performance overhead.
Real-world Case:
- Using 160+ icons from 54 icon collections
- Initial build: ~500ms icon parsing time
- User experience: Slow development server startup
Cache Optimization Mechanism:
Optimization Results:
- Build time reduced from 500ms to 20ms
- Development server startup speed significantly improved
- Maximum resource utilization
Best Practice Recommendations
Icon Usage Planning:
- Prioritize icons from the same collection
- Avoid overly dispersed usage across different collections
Development Experience Optimization:
- Cache automatically takes effect after first startup
- Intelligent cache updates when adding new icons
- No manual cache management required
Production Build Assurance:
- Cache mechanism doesn't affect final output
- Maintains on-demand loading characteristics of icon resources
- Ensures optimal build artifact size
Through these two optimization measures, the theme maintains rich functionality while ensuring excellent build performance and runtime experience.
Large Site Optimization
For large sites with over 100 pages:
- Consider splitting multi-language configuration by directory to reduce the number of pages per build
- Set
NODE_OPTIONS=--max-old-space-size=4096when runningpnpm docs:buildto increase memory - Regularly clean
.vuepress/.cacheandnode_modules/.vitedirectories to prevent cache bloat
