From 03b4daab3c28f1fdc361554be704ecf3eab5db70 Mon Sep 17 00:00:00 2001 From: pengzhanbo Date: Mon, 9 Sep 2024 00:18:32 +0800 Subject: [PATCH] docs: update docs --- docs/.vuepress/client.ts | 2 + .../themes/components/Contributors.vue | 44 +++++++ docs/README.md | 12 +- docs/notes/plugins/README.md | 1 - docs/notes/theme/guide/国际化.md | 5 + docs/notes/theme/guide/编写文章.md | 111 ++++++++++++++++-- docs/sponsor.md | 4 +- theme/README.md | 2 +- 8 files changed, 164 insertions(+), 17 deletions(-) create mode 100644 docs/.vuepress/themes/components/Contributors.vue diff --git a/docs/.vuepress/client.ts b/docs/.vuepress/client.ts index 297ee754..4788225a 100644 --- a/docs/.vuepress/client.ts +++ b/docs/.vuepress/client.ts @@ -3,6 +3,7 @@ import HeroTintPlateConfig from './themes/components/HeroTintPlateConfig.vue' import CanIUseConfig from './themes/components/CanIUseConfig.vue' import Demos from './themes/components/Demos.vue' import ThemeColors from './themes/components/ThemeColors.vue' +import Contributors from './themes/components/Contributors.vue' import { setupThemeColors } from './themes/composables/theme-colors.js' export default defineClientConfig({ @@ -11,6 +12,7 @@ export default defineClientConfig({ app.component('CanIUseConfig', CanIUseConfig) app.component('Demos', Demos) app.component('ThemeColors', ThemeColors) + app.component('Contributors', Contributors) }, setup() { setupThemeColors() diff --git a/docs/.vuepress/themes/components/Contributors.vue b/docs/.vuepress/themes/components/Contributors.vue new file mode 100644 index 00000000..9606c873 --- /dev/null +++ b/docs/.vuepress/themes/components/Contributors.vue @@ -0,0 +1,44 @@ + + + + + diff --git a/docs/README.md b/docs/README.md index 18d0c978..9ec23893 100644 --- a/docs/README.md +++ b/docs/README.md @@ -32,11 +32,11 @@ config: - title: 开箱即用 icon: 🚀 - details: 支持零配置即可使用，也支持丰富的自定义配置 + details: 支持零配置开箱即用，也支持丰富的自定义配置 - title: 多语言 icon: ⚖ - details: 内置了 中文/英文支持，还可以自定义添加更多的语言支持 + details: 内置 中文/英文支持，还可以自定义添加更多的语言支持 - title: 双色主题 icon: 👨‍💻 @@ -71,7 +71,7 @@ config: description: 支持 4 种评论系统，你可以自由选择符合你的需求的评论系统。 - title: 搜索 - description: 支持基于 minisearch 的本地搜索， 支持Algolia搜索。 + description: 支持基于 minisearch 的本地搜索， 支持 Algolia 搜索。 - title: 加密 description: 支持全站加密、部分加密（加密目录、加密文章）。 @@ -80,7 +80,7 @@ config: description: 代码复制，CodePen演示，Replit演示，JSFiddle演示，CodeSandbox演示，代码组，行高亮，行聚焦，行警告，差异对比等。 - title: 资源嵌入 - description: 图表，视频，PDF + description: 图表：chart.js/ECharts/Mermaid/flowchart，视频：Bilibili/Youtube，PDF - type: text-image title: 博客 @@ -169,8 +169,6 @@ export default defineUserConfig({ ### 贡献者 -[![Contributor pengzhanbo](https://img.shields.io/badge/Contributor-pengzhanbo-32A9C3?style=for-the-badge&labelColor=1B3C4A)](https://github.com/pengzhanbo/) - -[![Contributor huan_kong](https://img.shields.io/badge/Contributor-huan__kong-32A9C3?style=for-the-badge&labelColor=1B3C4A)](https://github.com/huankong233) + diff --git a/docs/notes/plugins/README.md b/docs/notes/plugins/README.md index db761816..5dc3ee07 100644 --- a/docs/notes/plugins/README.md +++ b/docs/notes/plugins/README.md @@ -11,7 +11,6 @@ permalink: /plugins/ ## 插件 -- [@vuepress-plume/plugin-iconify](/plugins/plugin-iconify/) - [@vuepress-plume/plugin-shikiji](/plugins/plugin-shikiji/) - [@vuepress-plume/plugin-content-update](/plugins/plugin-content-update/) - [vuepress-plugin-netlify-functions](/plugins/plugin-netlify-functions/) diff --git a/docs/notes/theme/guide/国际化.md b/docs/notes/theme/guide/国际化.md index 2c70d03b..be13d352 100644 --- a/docs/notes/theme/guide/国际化.md +++ b/docs/notes/theme/guide/国际化.md @@ -23,6 +23,11 @@ tags: - foo.md ::: +::: important +在不同的语言目录下，请尽量保持文件名和目录名的一致。这有助于在 切换语言时，主题能够正确的导航到 文章 +的不同的语言版本。 +::: + ## vuepress 配置 在 `.vuepress/config.js` 中配置： diff --git a/docs/notes/theme/guide/编写文章.md b/docs/notes/theme/guide/编写文章.md index 0c81521f..910091c6 100644 --- a/docs/notes/theme/guide/编写文章.md +++ b/docs/notes/theme/guide/编写文章.md @@ -12,13 +12,14 @@ tags: ::: info 提示 以下内容中，以 `sourceDir` 表示 项目中用于保存 `Markdown` 文件的目录。 -如 `package.json`的`scripts` 中配置的 `vuepress dev src`，则表示 `sourceDir` 为 `src` 目录 +如 `package.json`的`scripts` 中配置的 `vuepress dev docs`，则表示 `sourceDir` 为 `docs` 目录 ::: ## 约定 -使用本主题编写文章是一件很轻松的事情，你可以在 `sourceDir`目录中按照你的个人命名喜好新建任意名字的`Markdown`文件， -主题将会自动帮你生成一个文章永久链接，并保存在文章的配置中，以便随时修改。 +使用本主题编写文章是一件很轻松的事情，你可以在 `sourceDir`目录中按照你的个人命名喜好新建任意名字的`Markdown`文件。 + +### 文件夹命名约定 对于 `sourceDir` 中的文件夹命名，主题有一套简单的约定。 @@ -26,9 +27,7 @@ tags: - 允许多级目录，子级目录将作为父目录对应的分类的子项。 - 如果目录名称 在 [主题配置 notes](../config/notes配置.md) 中声明用于 notes 文章管理，则默认不作为 分类目录。 -### 文件夹命名约定 - -由于文件夹名称将作为分类名称，且不在主题配置中进行排序配置，对于有排序需要的场景，使用以下规则进行命名 +由于文件夹名称将作为分类名称，且不在主题配置中进行排序配置，对于有排序需要的场景，使用以下规则进行命名： ``` ts :no-line-numbers const dir = /\d+\.[\s\S]+/ @@ -43,7 +42,7 @@ __example:__ ::: file-tree - \{sourceDir\} - - 1.前端/ + - 1.前端 - 1.html/ - 2.css/ - 3.javascript/ @@ -51,7 +50,105 @@ __example:__ - 运维/ ::: +主题将根据 目录结构，生成一个 分类页。 + +### 文件命名约定 + +- __博客文章__ + + 对于 __博客文章__ 的名称，主题没有任何约定，你可以任意命名。博客文章默认排序规则仅根据文件创建时间进行排序。 + 你还可以通过 [frontmatter > sticky](../config/frontmatter/post.md#sticky) 配置文章是否置顶。 + +- __notes__ + + 对于 __notes__ 中的 markdown 文件名称，依然遵循 与 [文件夹命名约定](#文件夹命名约定) 相同的规则。 + 这可以为 notes 的 [自动生成侧边栏](../config/notes配置.md#自动生成侧边栏) 提供排序依据。 + +## 自动生成 Frontmatter + +默认配置下，主题在启动开发服务后，会帮助为源目录中的 markdown 文件，生成一些 `frontmatter` 配置。 +这些配置包括： __标题__, __创建时间__ 以及 __永久链接__。 + +一方面，这可以减少 内容创作者 的一些重复工作；另一方面，这些配置也为主题后续的其他功能提供了前置支持。 + +```md +--- +title: 标题 +createTime: 2024/09/08 22:53:34 +permalink: /article/9eh4d6ao/ +--- +``` + +### 标题 + +主题默认 使用文件名作为文章标题。在解析 文件名 时，[文件命名约定](#文件夹命名约定) 所命名的文件名如 +`1.我的文章.md`，其中 `1.` 和 `.md` 部分将被裁剪，最终文章标题为 `我的文章` 。 + +### 创建时间 + +主题默认使用文件创建时间作为文章创建时间，并将其格式化为 `yyyy/MM/dd HH:mm:ss`。 + +### 永久链接 + +__永久链接__ 指的是，文章发布后的 访问地址，这个地址一旦生成，只要您不手动修改它，即使文件路径、文件名发生改变也不会改变。 + +提前准备好 __永久链接__ 是比较有价值的，一方面，它可以帮助改善 站点的 SEO，避免收录的地址频繁变动； +另一方面，主题使用一套规范 生成 __永久链接__ ，它使得整个站点的 链接 风格一致。 + +- __博客文章__ + + 对于 博客文章，默认使用 `/article/` 作为永久链接的前缀，然后使用 [`nanoid`](https://github.com/ai/nanoid) + 生成长度为 `8` 的随机字符串进行拼接，作为文章的永久链接， 如 `/article/9eh4d6ao/`。 + + 对于链接前缀，还可以通过修改 [主题配置 > article](../config/主题配置.md#article) 替换默认的 `/article/`。 + +- __notes__ + + 对于 notes , 主题使用更为灵活的自定义方案，你可以在 [notes > note.link](../config/notes配置.md#配置) 声明不同的 + note 的链接前缀，然后同样适用 [`nanoid`](https://github.com/ai/nanoid) + 生成长度为 `8` 的随机字符串进行拼接，作为 ntoe 文章的永久链接。 + +### 禁用自动生成 + +你可能不想主题做额外的自动生成，希望由自己完全掌控。这完全没问题，主题支持通过配置来控制 自动生成 frontmatter 的行为。 +通过 [主题配置 > autoFrontmatter](../config/主题配置.md#autofrontmatter) 即可轻松做到。 + +```ts +import { defineUserConfig } from 'vuepress' +import { plumeTheme } from 'vuepress-theme-plume' + +export default defineUserConfig({ + theme: plumeTheme({ + // 完全禁用所有自动生成 + // autoFrontmatter: false, + + // 控制部分自动生成 + autoFrontmatter: { + permalink: true, // 是否生成永久链接 + createTime: true, // 是否生成创建时间 + title: true, // 是否生成标题 + } + }) +}) +``` + ## 文章写作 你可以使用 `markdown` 语法开始在 `sourceDir` 下新建 `Markdown` 文件，编写你自己的文章了， 关于 markdown 扩展的功能支持，请查看 [这个文档](./markdown/扩展.md) + +由于主题默认会为文章 的 `frontmatter` 自动生成一个 `title`，因此，文章内容的主体部分的标题，起始应该从 `h2` 即 +`## 二级标题` 开始。如果您禁用了 `autoFrontmatter.title`，那么应该使用 `h1` 即 `# 一级标题` 开始。 + +### 标签 + +通过 `frontmatter.tags` 可以为文章添加标签。 + +```md +--- +title: 我的文章 +tags: + - 标签 1 + - 标签 2 +--- +``` diff --git a/docs/sponsor.md b/docs/sponsor.md index f16059b8..cfb57d70 100644 --- a/docs/sponsor.md +++ b/docs/sponsor.md @@ -22,7 +22,7 @@ readingTime: false | :[bi:alipay]: AliPay | :[fa:wechat]: WeChat | | -------------------------------------- | ----------------------------------------- | -| ![Alipay](https://static.pengzhanbo.cn/images/sponsor/ali_pay.jpg){width="150px"} | ![WeChat](https://static.pengzhanbo.cn/images/sponsor/wechat_pay.jpg){width="150px"} | +| ![Alipay](https://static.pengzhanbo.cn/images/sponsor/ali_pay.jpg){width="300" height="300" style="width:150px"} | ![WeChat](https://static.pengzhanbo.cn/images/sponsor/wechat_pay.jpg){width="300" height="300" style="width:150px"} | ## 打赏记录 @@ -31,3 +31,5 @@ readingTime: false | **锋 | 2024-04-18 | 6.88 | 支持下作者，加油！ | | *杰 | 2024-05-25 | 6.00 | 请你喝杯茶，加油 | | **党 | 2024-08-22 | 8.80 | 感谢开源，加油 | + +1 diff --git a/theme/README.md b/theme/README.md index 0eebe941..b5927a5d 100644 --- a/theme/README.md +++ b/theme/README.md @@ -62,7 +62,7 @@ export default defineUserConfig({ __options__ : `PlumeThemeOptions` -[查看 options 详细说明](https://theme-plume.vuejs.press//config/basic/) +[查看 options 详细说明](https://theme-plume.vuejs.press/config/basic/) ## 注意