docs: update docs

2024-09-09 00:18:32 +08:00 · 2024-09-09 00:18:32 +08:00 · 03b4daab3c
commit 03b4daab3c
parent 3d3b49da57
8 changed files with 164 additions and 17 deletions
--- 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()
--- a/docs/.vuepress/themes/components/Contributors.vue
+++ b/docs/.vuepress/themes/components/Contributors.vue
@ -0,0 +1,44 @@
+<script setup lang="ts">
+defineProps<{
+  contributors: string[]
+}>()
+</script>
+
+<template>
+  <div class="contributors">
+    <div v-for="contributor in contributors" :key="contributor" class="contributor">
+      <img :src="`https://github.com/${contributor}.png`" :alt="contributor">
+      <a :href="`https://github.com/${contributor}`" target="_blank" rel="noopener noreferrer">{{ contributor }}</a>
+    </div>
+  </div>
+</template>
+
+<style scoped>
+.contributors {
+  display: flex;
+  flex-wrap: wrap;
+  gap: 24px;
+  align-items: center;
+  justify-content: flex-start;
+  margin-top: 32px;
+  margin-bottom: 64px;
+}
+
+.contributor {
+  display: flex;
+  gap: 8px;
+  align-items: center;
+}
+
+.contributor img {
+  width: 32px;
+  height: 32px;
+  border-radius: 100%;
+
+  object-fit: contain;
+}
+
+.contributor a {
+  text-decoration: none;
+}
+</style>
--- 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)
+<Contributors :contributors="['pengzhanbo', 'huankong233', 'northword', 'KrLite', 'shylock-wu', 'hrradev']" />

 </div>
--- 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/)
--- a/docs/notes/theme/guide/国际化.md
+++ b/docs/notes/theme/guide/国际化.md
@ -23,6 +23,11 @@ tags:
  - foo.md
 :::

+::: important
+在不同的语言目录下，请尽量保持文件名和目录名的一致。这有助于在 切换语言时，主题能够正确的导航到 文章
+的不同的语言版本。
+:::
+
 ## vuepress 配置

 在 `.vuepress/config.js` 中配置：
--- 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
+---
+```
--- 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
--- 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/)

 ## 注意