mirror of
https://github.com/pengzhanbo/vuepress-theme-plume.git
synced 2026-04-23 10:58:13 +08:00
a4ac3a30e0
* docs: translate README to English in homepage * feat(docs): update hero-text in README * docs: add readme_en * feat(docs): add language jump in readme * docs: update readme layout * feat(docs): add CONTRIBUTION_EN and jump link * docs: translate theme introduction * docs: upgrade version to 135 , create 2 file * docs: add icon, fix translation errors in intro, translate quick-start * docs: translate quick start - write * docs: fix jump link in write * docs: translate document in quick start * docs: translate international in quick start * docs: translate deployment in quick start * docs: translate optimize-build in quick start --------- Co-authored-by: pengzhanbo <volodymyr@foxmail.com>
68 lines
3.6 KiB
Markdown
68 lines
3.6 KiB
Markdown
---
|
||
title: Build Optimization
|
||
icon: clarity:bundle-solid
|
||
outline: 2
|
||
createTime: 2025/03/05 16:06:03
|
||
permalink: /en/guide/optimize-build/
|
||
---
|
||
|
||
## Image Optimization <Badge type="warning" text="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](https://developer.mozilla.org/zh-CN/docs/Web/HTML/Element/img#height):
|
||
|
||
::: 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`:
|
||
|
||
```ts
|
||
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](https://icon-sets.iconify.design/), 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.
|
||
:::
|