From 7c2e3d9f3943b9e6763b7c4b076f80b70bb75ad7 Mon Sep 17 00:00:00 2001 From: pengzhanbo Date: Tue, 10 Sep 2024 16:47:32 +0800 Subject: [PATCH] docs: update docs --- docs/.vuepress/navbar.ts | 14 +- docs/.vuepress/notes/zh/theme-config.ts | 1 - docs/.vuepress/notes/zh/theme-guide.ts | 1 + docs/.vuepress/theme.ts | 1 + docs/README.md | 12 +- docs/notes/theme/config/frontmatter/basic.md | 2 +- docs/notes/theme/config/plugins/README.md | 6 +- .../theme/config/plugins/markdownPower.md | 212 +++++++++++++++++- docs/notes/theme/config/plugins/代码高亮.md | 35 +-- docs/notes/theme/guide/构建优化.md | 75 +++++++ docs/sponsor.md | 2 - 11 files changed, 331 insertions(+), 30 deletions(-) create mode 100644 docs/notes/theme/guide/构建优化.md 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