docs: update docs
This commit is contained in:
pengzhanbo
parent
ab7d368485
commit
7c2e3d9f39
@ -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/',
|
||||
|
||||
@ -38,7 +38,6 @@ export const themeConfig = defineNoteConfig({
|
||||
'阅读统计',
|
||||
'markdown增强',
|
||||
'markdownPower',
|
||||
'百度统计',
|
||||
'水印',
|
||||
],
|
||||
},
|
||||
|
||||
@ -16,6 +16,7 @@ export const themeGuide = defineNoteConfig({
|
||||
'编写文章',
|
||||
'国际化',
|
||||
'部署',
|
||||
'构建优化',
|
||||
],
|
||||
},
|
||||
{
|
||||
|
||||
@ -17,6 +17,7 @@ export const theme: Theme = plumeTheme({
|
||||
flowchart: true,
|
||||
},
|
||||
markdownPower: {
|
||||
imageSize: 'all',
|
||||
pdf: true,
|
||||
caniuse: true,
|
||||
plot: true,
|
||||
|
||||
@ -169,6 +169,16 @@ export default defineUserConfig({
|
||||
|
||||
### 贡献者
|
||||
|
||||
<Contributors :contributors="['pengzhanbo', 'huankong233', 'northword', 'KrLite', 'shylock-wu', 'hrradev']" />
|
||||
<Contributors
|
||||
:contributors="[
|
||||
'pengzhanbo',
|
||||
'huankong233',
|
||||
'northword',
|
||||
'KrLite',
|
||||
'shylock-wu',
|
||||
'hrradev',
|
||||
'TheCoderAlex'
|
||||
]"
|
||||
/>
|
||||
|
||||
</div>
|
||||
|
||||
@ -76,7 +76,7 @@ permalink: /config/frontmatter/basic/
|
||||
|
||||
主题会在文件创建时:
|
||||
|
||||
- 博客类型的文章，自动填充 `/article/` + `nanoid 生成的 6 位随机字符串` 作为 文章永久链接
|
||||
- 博客类型的文章，自动填充 `/article/` + `nanoid 生成的 8 位随机字符串` 作为 文章永久链接
|
||||
- notes 目录下的文章，会根据 notes 的配置，自动填充 文章永久链接
|
||||
|
||||
### externalLinkIcon
|
||||
|
||||
@ -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) 中添加它们。主题已在内部完成了这些工作。
|
||||
:::
|
||||
|
||||
@ -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__ 的数据包 用于分析尺寸，但还是会实际影响构建时间。
|
||||
:::
|
||||
|
||||
@ -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 <Badge type="tip" text="实验性" />
|
||||
### twoslash
|
||||
|
||||
- 类型: `boolean`
|
||||
- 默认值: `false`
|
||||
@ -156,3 +156,10 @@ interface CopyCodeOptions {
|
||||
- 默认值： `false`
|
||||
|
||||
将代码块折叠到指定行数。
|
||||
|
||||
### codeTransformers
|
||||
|
||||
- 类型: `ShikiTransformer[]`
|
||||
- 默认值: `[]`
|
||||
|
||||
代码转换器， 查看 [shiki transformers](https://shiki.style/guide/transformers) 了解更多信息。
|
||||
|
||||
75
docs/notes/theme/guide/构建优化.md
Normal file
75
docs/notes/theme/guide/构建优化.md
Normal file
@ -0,0 +1,75 @@
|
||||
---
|
||||
title: 构建优化
|
||||
icon: clarity:bundle-solid
|
||||
createTime: 2024/09/10 01:50:20
|
||||
permalink: /guide/optimize-build/
|
||||
---
|
||||
|
||||
## 图片优化 <Badge type="warning" text="试验性" />
|
||||
|
||||
当我们在 markdown 中使用 `[alt](url)` 或者 `<img src="url">` 嵌入图片后，虽然页面按照预期的显示了
|
||||
图片。
|
||||
|
||||
由于图片的体积不同，当图片体积较小，网络情况良好的时候，我们不会感受到页面的布局有产生明显的抖动。
|
||||
然而，当图片体积较大，或者网络情况较差时，由于图片为完成加载，原本页面上应该显示图片的位置被后面的
|
||||
内容挤压，等到图片加载完成后，页面布局会发生变化，图片重新占据应该显示的位置，其它的内容被排开。
|
||||
|
||||
事实上这个体验相当不友好。特别是对于页面内的图片数量较多时，页面会频繁发生布局变化，这一过程还可能
|
||||
感知到卡顿，较为明显的是布局的抖动。
|
||||
|
||||
因此，让页面布局稳定下来，图片是一个必须解决的问题。
|
||||
|
||||
从 [MDN > img](https://developer.mozilla.org/zh-CN/docs/Web/HTML/Element/img#height) 我们可以知道：
|
||||
|
||||
::: info
|
||||
`<img>` 同时包括 `height` 和 `width` 使浏览器在加载图像之前计算图像的长宽比。
|
||||
此长宽比用于保留显示图像所需的空间，减少甚至防止在下载图像并将其绘制到屏幕上时布局的偏移。
|
||||
减少布局偏移是良好用户体验和 Web 性能的主要组成部分。
|
||||
:::
|
||||
|
||||
因此，主题围绕这个问题，提供了 一个解决方案：
|
||||
|
||||
为 markdown 文件中的 `[alt](url)` 或者 `<img src="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` 大小的缩略图。这需要花费更多的时间，
|
||||
这可能对于用户而言是不可接受的。
|
||||
:::
|
||||
@ -31,5 +31,3 @@ readingTime: false
|
||||
| **锋 | 2024-04-18 | 6.88 | 支持下作者，加油！ |
|
||||
| *杰 | 2024-05-25 | 6.00 | 请你喝杯茶，加油 |
|
||||
| **党 | 2024-08-22 | 8.80 | 感谢开源，加油 |
|
||||
|
||||
1
|
||||
|
||||
Loading…
x
Reference in New Issue
Block a user