diff --git a/docs/.vuepress/navbar.ts b/docs/.vuepress/navbar.ts
index e71e78db..24c9a5bd 100644
--- a/docs/.vuepress/navbar.ts
+++ b/docs/.vuepress/navbar.ts
@@ -16,13 +16,13 @@ export const zhNavbar = [
link: '/notes/theme/config/配置说明.md',
activeMatch: '^/config/',
},
- {
- text: '插件',
- icon: 'clarity:plugin-line',
- // link: '/plugins/',
- link: '/notes/plugins/README.md',
- activeMatch: '^/plugins/',
- },
+ // {
+ // text: '插件',
+ // icon: 'clarity:plugin-line',
+ // // link: '/plugins/',
+ // link: '/notes/plugins/README.md',
+ // activeMatch: '^/plugins/',
+ // },
{
text: '博客',
link: '/blog/',
diff --git a/docs/.vuepress/notes/zh/theme-config.ts b/docs/.vuepress/notes/zh/theme-config.ts
index 5eb18f45..9cc27679 100644
--- a/docs/.vuepress/notes/zh/theme-config.ts
+++ b/docs/.vuepress/notes/zh/theme-config.ts
@@ -38,7 +38,6 @@ export const themeConfig = defineNoteConfig({
'阅读统计',
'markdown增强',
'markdownPower',
- '百度统计',
'水印',
],
},
diff --git a/docs/.vuepress/notes/zh/theme-guide.ts b/docs/.vuepress/notes/zh/theme-guide.ts
index beab6f91..dca3a185 100644
--- a/docs/.vuepress/notes/zh/theme-guide.ts
+++ b/docs/.vuepress/notes/zh/theme-guide.ts
@@ -16,6 +16,7 @@ export const themeGuide = defineNoteConfig({
'编写文章',
'国际化',
'部署',
+ '构建优化',
],
},
{
diff --git a/docs/.vuepress/theme.ts b/docs/.vuepress/theme.ts
index ad061289..94c7025b 100644
--- a/docs/.vuepress/theme.ts
+++ b/docs/.vuepress/theme.ts
@@ -17,6 +17,7 @@ export const theme: Theme = plumeTheme({
flowchart: true,
},
markdownPower: {
+ imageSize: 'all',
pdf: true,
caniuse: true,
plot: true,
diff --git a/docs/README.md b/docs/README.md
index 9ec23893..3006c461 100644
--- a/docs/README.md
+++ b/docs/README.md
@@ -169,6 +169,16 @@ export default defineUserConfig({
### 贡献者
-
+
diff --git a/docs/notes/theme/config/frontmatter/basic.md b/docs/notes/theme/config/frontmatter/basic.md
index 24a5ec83..c2eab3e9 100644
--- a/docs/notes/theme/config/frontmatter/basic.md
+++ b/docs/notes/theme/config/frontmatter/basic.md
@@ -76,7 +76,7 @@ permalink: /config/frontmatter/basic/
主题会在文件创建时:
- - 博客类型的文章，自动填充 `/article/` + `nanoid 生成的 6 位随机字符串` 作为 文章永久链接
+ - 博客类型的文章，自动填充 `/article/` + `nanoid 生成的 8 位随机字符串` 作为 文章永久链接
- notes 目录下的文章，会根据 notes 的配置，自动填充 文章永久链接
### externalLinkIcon
diff --git a/docs/notes/theme/config/plugins/README.md b/docs/notes/theme/config/plugins/README.md
index 8bdc8cde..9e980cda 100644
--- a/docs/notes/theme/config/plugins/README.md
+++ b/docs/notes/theme/config/plugins/README.md
@@ -5,7 +5,7 @@ createTime: 2024/03/06 8:26:44
permalink: /config/plugins/
---
-主题内置的使用的插件，扩展了主题的众多功能，你可以在这个 字段中， 实现对内部使用的各个插件的自定义配置。
+主题内置的使用的插件，扩展了主题的众多功能，你可以在 `plugins` 配置中， 实现对内部使用的各个插件的自定义配置。
## 配置
@@ -23,3 +23,7 @@ export default defineUserConfig({
}),
})
```
+
+:::tip
+您无需重复安装这些内置插件，也无需在 [vuepress配置 > plugins](https://v2.vuepress.vuejs.org/zh/reference/config.html#plugins) 中添加它们。主题已在内部完成了这些工作。
+:::
diff --git a/docs/notes/theme/config/plugins/markdownPower.md b/docs/notes/theme/config/plugins/markdownPower.md
index 940f372c..295f9638 100644
--- a/docs/notes/theme/config/plugins/markdownPower.md
+++ b/docs/notes/theme/config/plugins/markdownPower.md
@@ -9,7 +9,9 @@ permalink: /config/plugin/markdown-power/
提供 Markdown 增强功能。
-关联插件: [@vuepress-plume/plugin-md-power](/)
+关联插件: [@vuepress-plume/plugin-md-power](https://github.com/pengzhanbo/vuepress-theme-plume/tree/main/plugins/plugin-md-power)
+
+## 配置
默认配置：
@@ -32,12 +34,216 @@ export default defineUserConfig({
// jsfiddle: true, // @[jsfiddle](id) 嵌入 jsfiddle
// caniuse: true, // @[caniuse](feature) 嵌入 caniuse
// repl: true, // :::go-repl :::kotlin-repl :::rust-repl
+ // plot: true, // !!plot!! 隐秘文本
+ // fileTree: true, // :::file-tree 文件树容器
+
+ // imageSize: true, // 在构建阶段为 图片添加 width/height 属性
}
}
}),
})
```
-## 配置
+## 功能
-查看 [文档](../../../plugins/md-power.md)
+### 嵌入 PDF
+
+插件默认不启用该功能，你需要手动设置 `pdf` 为 `true`
+
+__语法:__
+
+```md
+@[pdf](url)
+```
+
+请查看 [完整使用文档](../../guide/嵌入/pdf.md)
+
+### iconify 图标
+
+插件默认不启用该功能，你需要手动设置 `icons` 为 `true`
+
+得益于 [iconify](https://iconify.design/), 你可以在 Markdown 中使用 iconify __200k+__ 的图标
+
+__语法:__
+
+```md
+:[collect:name]:
+```
+
+请查看 [完整使用文档](../../guide/markdown/进阶.md#iconify-图标)
+
+### bilibili 视频
+
+插件默认不启用该功能，你需要手动设置 `bilibili` 为 `true`
+
+__语法:__
+
+```md
+@[bilibili](bvid)
+```
+
+请查看 [完整使用文档](../../guide/嵌入/bilibili.md)
+
+### youtube 视频
+
+插件默认不启用该功能，你需要手动设置 `youtube` 为 `true`
+
+__语法:__
+
+```md
+@[youtube](id)
+```
+
+请查看 [完整使用文档](../../guide/嵌入/youtube.md)
+
+### codePen 代码演示
+
+插件默认不启用该功能，你需要手动设置 `codepen` 为 `true`
+
+__语法:__
+
+```md
+@[codepen](user/slash)
+```
+
+请查看 [完整使用文档](../../guide/代码演示/codepen.md)
+
+### codeSandbox 代码演示
+
+插件默认不启用该功能，你需要手动设置 `codeSandbox` 为 `true`
+
+__语法:__
+
+```md
+@[codesandbox](id)
+```
+
+请查看 [完整使用文档](../../guide/代码演示/codeSandbox.md)
+
+### jsfiddle 代码演示
+
+插件默认不启用该功能，你需要手动设置 `jsfiddle` 为 `true`
+
+__语法:__
+
+```md
+@[jsfiddle](id)
+```
+
+请查看 [完整使用文档](../../guide/代码演示/jsFiddle.md)
+
+### caniuse 浏览器支持
+
+插件默认不启用该功能，你需要手动设置 `caniuse` 为 `true`
+
+__语法:__
+
+```md
+@[caniuse](feature)
+```
+
+请查看 [完整使用文档](../../guide/markdown/进阶.md#can-i-use)
+
+### Repl 代码演示容器
+
+插件默认不启用该功能，你需要手动设置 `repl` 为 `true`
+
+支持在线运行 Rust、Golang、Kotlin 代码，还支持在线编辑。
+
+或者开启部分功能，如下所示
+
+``` ts
+export default defineUserConfig({
+ theme: plumeTheme({
+ plugins: {
+ markdownPower: {
+ repl: {
+ rust: true,
+ go: true,
+ kotlin: true,
+ },
+ },
+ }
+ })
+})
+```
+
+__语法:__
+
+````md
+::: rust-repl
+```rust
+// rust code
+```
+:::
+
+::: go-repl
+```go
+// go code
+```
+:::
+
+::: kotlin-repl
+```kotlin
+// kotlin code
+```
+:::
+````
+
+请查看完整使用文档:
+
+- [代码演示 > Rust](../../guide/代码演示/rust.md)
+- [代码演示 > Golang](../../guide/代码演示/golang.md)
+- [代码演示 > Kotlin](../../guide/代码演示/kotlin.md)
+
+### Plot 隐秘文本
+
+插件默认不启用该功能，你需要手动设置 `plot` 为 `true`
+
+__语法:__
+
+```md
+!!content!!
+```
+
+请查看 [完整使用文档](../../guide/markdown/进阶.md#隐秘文本)
+
+### 文件树
+
+插件默认不启用该功能，你需要手动设置 `fileTree` 为 `true`
+
+__语法:__
+
+```md
+::: file-tree
+
+- folder1
+ - file1.md
+ - file2.ts
+ - folder2
+ - file3.md
+- folder3
+
+:::
+```
+
+请查看 [完整使用文档](../../guide/markdown/进阶.md#文件树)
+
+### 图片尺寸
+
+该功能会为 markdown 文件中的 图片引用 添加当前图片的 `width` 和 `height` 属性。
+通过读取 图片的原始尺寸大小，为 图片设置默认的 图片尺寸 和 比例。
+从而解决页面在图片加载未完成到完成时，布局闪烁的问题。
+
+插件默认不启用该功能，你需要手动设置 `imageSize`：
+
+- 如果 `imageSize` 为 `true`，则插件仅处理本地图片，等同于 `local` 选项；
+- 如果 `imageSize` 为 `'local'`，则插件仅处理本地图片；
+- 如果 `imageSize` 为 `'all'`，则插件同时处理本地图片和远程图片。
+
+::: important
+__此功能仅在构建生产包时生效。__
+
+请谨慎 使用 `'all'` 选项，由于该选项会在 构建生产包时，请求远程图片资源，这会使得构建时间变长。
+虽然主题做了优化仅会加载图片 __几 KB__ 的数据包 用于分析尺寸，但还是会实际影响构建时间。
+:::
diff --git a/docs/notes/theme/config/plugins/代码高亮.md b/docs/notes/theme/config/plugins/代码高亮.md
index f46e0241..6a4aa90d 100644
--- a/docs/notes/theme/config/plugins/代码高亮.md
+++ b/docs/notes/theme/config/plugins/代码高亮.md
@@ -16,9 +16,16 @@ Shiki 支持多种编程语言。
关联插件： [@vuepress-plume/plugin-shikiji](https://github.com/pengzhanbo/vuepress-theme-plume/tree/main/plugins/plugin-shikiji)
-相比于 官方的 [@vuepress/plugin-prismjs](https://ecosystem.vuejs.press/zh/plugins/prismjs.html) 和
-[@vuepress/plugin-shiki](https://ecosystem.vuejs.press/zh/plugins/shiki.html) 两个代码高亮插件，
-提供了更为丰富的功能支持，包括：
+::: details 为什么不用 官方的 @vuepress/plugin-shiki ？
+
+你可以认为本插件是 官方 [@vuepress/plugin-shiki](https://ecosystem.vuejs.press/zh/plugins/shiki.html) 的
+一个分支版本，但本插件更为激进，支持更多新的特性。
+
+同时，我也是 [@vuepress/plugin-shiki](https://ecosystem.vuejs.press/zh/plugins/shiki.html) 的主要维护者之一
+，在 `@vuepress-plume/plugin-shikiji` 插件中新增的试验性的新特性，会在未来合适的时候合并到 官方插件中。
+:::
+
+## 特性
- [代码行高亮](../../guide/代码/特性支持.md#在代码块中实现行高亮)
- [代码聚焦](../../guide/代码/特性支持.md#代码块中聚焦)
@@ -26,7 +33,9 @@ Shiki 支持多种编程语言。
- [代码高亮“错误”和“警告”](../../guide/代码/特性支持.md#高亮-错误-和-警告)
- [代码词高亮](../../guide/代码/特性支持.md#代码块中-词高亮)
- [代码块折叠](../../guide/代码/特性支持.md#折叠代码块)
-- [twoslash](../../guide/代码/twoslash.md#twoslash) ，在代码块内提供内联类型提示。
+- [twoslash](../../guide/代码/twoslash.md#twoslash) ：在代码块内提供内联类型提示。
+
+## 配置
默认配置：
@@ -45,8 +54,6 @@ export default defineUserConfig({
})
```
-## 配置
-
### theme
- 类型: `string | { light: string, dark: string }`
@@ -123,14 +130,7 @@ interface CopyCodeOptions {
}
```
-### codeTransformers
-
-- 类型: `ShikiTransformer[]`
-- 默认值: `[]`
-
-代码转换器， 查看 [shiki transformers](https://shiki.style/guide/transformers) 了解更多信息。
-
-### twoslash
+### twoslash
- 类型: `boolean`
- 默认值: `false`
@@ -156,3 +156,10 @@ interface CopyCodeOptions {
- 默认值： `false`
将代码块折叠到指定行数。
+
+### codeTransformers
+
+- 类型: `ShikiTransformer[]`
+- 默认值: `[]`
+
+代码转换器， 查看 [shiki transformers](https://shiki.style/guide/transformers) 了解更多信息。
diff --git a/docs/notes/theme/guide/构建优化.md b/docs/notes/theme/guide/构建优化.md
new file mode 100644
index 00000000..e5185cd0
--- /dev/null
+++ b/docs/notes/theme/guide/构建优化.md
@@ -0,0 +1,75 @@
+---
+title: 构建优化
+icon: clarity:bundle-solid
+createTime: 2024/09/10 01:50:20
+permalink: /guide/optimize-build/
+---
+
+## 图片优化
+
+当我们在 markdown 中使用 `[alt](url)` 或者 `
` 嵌入图片后，虽然页面按照预期的显示了
+图片。
+
+由于图片的体积不同，当图片体积较小，网络情况良好的时候，我们不会感受到页面的布局有产生明显的抖动。
+然而，当图片体积较大，或者网络情况较差时，由于图片为完成加载，原本页面上应该显示图片的位置被后面的
+内容挤压，等到图片加载完成后，页面布局会发生变化，图片重新占据应该显示的位置，其它的内容被排开。
+
+事实上这个体验相当不友好。特别是对于页面内的图片数量较多时，页面会频繁发生布局变化，这一过程还可能
+感知到卡顿，较为明显的是布局的抖动。
+
+因此，让页面布局稳定下来，图片是一个必须解决的问题。
+
+从 [MDN > img](https://developer.mozilla.org/zh-CN/docs/Web/HTML/Element/img#height) 我们可以知道：
+
+::: info
+`![]()
` 同时包括 `height` 和 `width` 使浏览器在加载图像之前计算图像的长宽比。
+此长宽比用于保留显示图像所需的空间，减少甚至防止在下载图像并将其绘制到屏幕上时布局的偏移。
+减少布局偏移是良好用户体验和 Web 性能的主要组成部分。
+:::
+
+因此，主题围绕这个问题，提供了 一个解决方案：
+
+为 markdown 文件中的 `[alt](url)` 或者 `` 自动添加 `width` 和 `height` 属性。
+
+你可以通过配置 `markdownPower` 来启用它：
+
+```ts
+export default defineUserConfig({
+ theme: plumeTheme({
+ plugins: {
+ markdownPower: {
+ imageSize: true, // 'local' | 'all'
+ },
+ }
+ })
+})
+```
+
+启用此功能后，主题会通过图片资源地址，获取图片的原始尺寸，然后为图片添加 `width` 和 `height` 属性。
+
+- 如果设置为 `'local'`， 则仅为 本地图片添加 `width` 和 `height` 属性。
+- 如果设置为 `'all'`， 则包括 __本地图片__ 和 __网络图片__ 都 添加 `width` 和 `height` 属性。
+- 如果设置为 `true`， 则等同于 `'local'`
+
+::: important
+请注意，出于性能考虑，即使您启用了此功能，该功能也仅在 构建生产包时生效。
+:::
+
+::: important
+请谨慎使用 `'all'` 选项，该选项会在构建生产包时，请求所有 markdown 中包含的 远程图片资源，
+这对于包含较多图片资源的站点而言，会使得构建时间变长。
+
+主题也针对此类情况做了优化，请求远程图片仅在获取 __几 KB__ 的数据包足够分析尺寸后不再等待请求完成，
+同时并发请求其他图片资源。这在一定程度上能够改善构建时间。
+:::
+
+::: details 还有其他方案吗？
+事实上有的，当前的方案其实是一个折中的方案。
+
+我考虑过使用 [thumbhash](https://github.com/evanw/thumbhash) 为图片生成缩略图，通过 占位图 和 懒加载
+等技术方案实现更为平滑优雅的图片加载体验。
+
+然而这是有代价的，这需要使用的 [sharp](https://github.com/lovell/sharp) 或 [canvaskit](https://github.com/google/skia/tree/main/modules/canvaskit) 等图片处理库，对图片进行处理分析，
+再通过 [thumbhash](https://github.com/evanw/thumbhash) 生成大概 `20byte` 大小的缩略图。这需要花费更多的时间，
+这可能对于用户而言是不可接受的。
+:::
diff --git a/docs/sponsor.md b/docs/sponsor.md
index cfb57d70..9cd4b0a9 100644
--- a/docs/sponsor.md
+++ b/docs/sponsor.md
@@ -31,5 +31,3 @@ readingTime: false
| **锋 | 2024-04-18 | 6.88 | 支持下作者，加油！ |
| *杰 | 2024-05-25 | 6.00 | 请你喝杯茶，加油 |
| **党 | 2024-08-22 | 8.80 | 感谢开源，加油 |
-
-1