docs: improve docs (#226)

pengzhanbo · Sep 27, 2024 · 2f73602 · 2f73602
1 parent da64267
commit 2f73602
Show file tree

Hide file tree

Showing 6 changed files with 126 additions and 10 deletions.
diff --git a/docs/.vuepress/navbar.ts b/docs/.vuepress/navbar.ts
@@ -38,6 +38,7 @@ export const zhNavbar = [
     text: '更多',
     icon: 'icon-park-outline:more-three',
     items: [
+      { text: '常见问题', link: '/faq/', icon: 'wpf:faq' },
       { text: '喝杯奶茶', link: '/sponsor/', icon: 'line-md:coffee-loop' },
       { text: '主题工具', link: '/tools/', icon: 'jam:tools' },
       { text: '友情链接', link: '/friends/', icon: 'carbon:friendship' },

diff --git a/docs/notes/theme/guide/博客.md b/docs/notes/theme/guide/博客.md
@@ -121,14 +121,15 @@ tags:
 
 以下是在 博客文章中可用的 `frontmatter` 属性。
 
-| 属性       | 类型                | 默认值                      | 说明                                         |
-| ---------- | ------------------- | --------------------------- | -------------------------------------------- |
-| title      | `string`            | 默认自动填入文件名          | 文章标题                                     |
-| createTime | `string`            | 当前时间                    | 文章创建时间                                 |
-| tags       | `string[]`          | `[]`                        | 文章标签                                     |
-| sticky     | `boolean \| number` | false                       | 是否置顶, 如果为数字，则数字越大，置顶越靠前 |
-| draft      | `boolean`           | false                       | 是否为草稿，草稿文章不会被展示               |
-| cover      | `string` \| `BlogPostCover` | `''` | 文章封面                                     |
+| 属性       | 类型                        | 默认值             | 说明                                         |
+| ---------- | --------------------------- | ------------------ | -------------------------------------------- |
+| title      | `string`                    | 默认自动填入文件名 | 文章标题                                     |
+| createTime | `string`                    | 当前时间           | 文章创建时间                                 |
+| tags       | `string[]`                  | `[]`               | 文章标签                                     |
+| sticky     | `boolean \| number`         | false              | 是否置顶, 如果为数字，则数字越大，置顶越靠前 |
+| draft      | `boolean`                   | false              | 是否为草稿，草稿文章不会被展示               |
+| cover      | `string \| BlogPostCover` | `''`               | 文章封面                                     |
+| excerpt    | `boolean \| string`         | ''                 | 文章摘要，默认通过 `<!-- more -->` 注释生成, 传入字符串表示自定义内容，不再从正文提取 |
 
 除了以上的字段，你还可以使用 [通用 frontmatter 配置](../config/frontmatter/basic.md) 中的字段，
 灵活的控制当前页面的行为。
@@ -151,6 +152,25 @@ title: 标题
 这里的内容不会被作为摘要
 ```
 
+还可以使用 `frontmatter.excerpt` 来控制文章是否显示摘要，以及 自定义摘要内容。
+
+- `frontmatter.excerpt` 默认为 `false`，表示不显示摘要，此时 `<!-- more -->` 注释会被忽略。
+- `frontmatter.excerpt` 为 `string` 类型时，表示自定义摘要内容，此时 `<!-- more -->` 注释会被忽略。
+
+**示例：**
+
+```md
+---
+title: 标题
+excerpt: 自定义摘要内容
+---
+```
+
+您可以根据需要使用不同的方式来控制文章的摘要。
+
+::: tip 主题更建议使用 <code>&lt;!-- more --&gt;</code> 注释来添加摘要
+:::
+
 ## 文章封面图
 
 在博客文章列表页，主题支持为 文章添加封面图，并支持不同的 排版 和 灵活的尺寸配置。

diff --git a/docs/notes/theme/guide/自定义首页.md b/docs/notes/theme/guide/自定义首页.md
@@ -157,6 +157,8 @@ interface PlumeThemeHomeHero extends PlumeHomeConfigBase {
       theme?: 'brand' | 'alt'
       text: string
       link?: string
+      target?: '_blank' | '_self' | string
+      rel?: string
     }
   }
   /**

diff --git a/docs/notes/tools/README.md b/docs/notes/tools/README.md
@@ -11,5 +11,6 @@ permalink: /tools/
 
 ## 工具列表
 
-- [caniuse 特性搜索](./caniuse.md)
+- [主题配置工具](./config.md)
 - [首页背景色板配置](./home-hero-tint-plate.md)
+- [caniuse 特性搜索](./caniuse.md)
diff --git a/docs/questions.md b/docs/questions.md
@@ -0,0 +1,93 @@
+---
+title: 常见问题
+createTime: 2024/09/27 08:47:36
+permalink: /faq/
+draft: true
+---
+
+本文主要包含了使用主题的过程中可能会遇到的常见问题与解决方法。
+
+如果您遇到任何问题，您可以先在以下内容中寻找是否有相关的问题和解决方法。
+
+如果没有找到，您可以先通过  Github [Discussions](https://github.com/pengzhanbo/vuepress-theme-plume/discussions/new?category=q-a) 与我们讨论。
+
+如果您确定某处确实存在问题，请在 Github [Open an issue](https://github.com/pengzhanbo/vuepress-theme-plume/issues/new?assignees=pengzhanbo&labels=bug&projects=&template=bug-report.zh-CN.yml&title=%5BBug%5D),
+在 Issue 中说明该问题的具体细节，如有必要，请尽量提供一个 最小重现包，我们会尽快解决。
+
+::: details 发起讨论或提出问题需要注意什么？
+我们欢迎你发起讨论或提出任何问题，无论它是否简单，积极提问是好事。但请确保以下三点：
+
+1. 你已经尝试搜索过相关文档；
+2. 你在讨论中提供了详细的描述；
+3. 你不是在问与 VuePress 无关的问题，也不是在寻求技术支持。
+
+   我们不会回答 “我如何在我自己的项目中单独使用主题的某个功能” 、“我怎么在我的自己项目中实现主题的某个功能” 这种
+   问题。
+:::
+
+## 怎么更新主题？
+
+你可以通过 `vp-update` 命令来更新主题。
+
+`vp-update` 是 VuePress 官方维护的 CLI 工具，它可以帮助你检查项目内与 VuePress 相关的主题、插件等的
+最新版本，并自动为你安装依赖。
+
+复制以下命令到你的项目中运行：
+
+::: code-tabs
+@tab pnpm
+
+```sh
+pnpm dlx vp-update
+```
+
+@tab yarn
+
+```sh
+yarn dlx vp-update
+```
+
+@tab npm
+
+```sh
+npx vp-update
+```
+
+:::
+
+## 为什么更新主题版本后新的功能没有生效？
+
+由于 VuePress 在启动开发服务时，全量编译源目录中的的 `markdown` 文件耗时较长，主题对 `markdown` 的编译进行了
+缓存，以提高启动速度。主题功能并重启开发服务时，由于源目录中的 `markdown` 文件没有变化，跳过了编译直接使用缓存，
+这会导致与 markdown 有关的新功能没有生效。
+
+**只需要删除缓存文件，并重启即可**。
+
+1. 直接删除 `.vuepress/.cache` 目录。
+2. 在启动开发服务命令后面，添加 `--clean-cache` 参数：
+
+   ```sh
+   vuepress dev docs --clean-cache
+   ```
+
+## 为什么修改主题插件的配置没有生效？
+
+这个文件常见于修改 `plugins.markdownEnhance` 、`plugins.markdownPower` 、`plugins.markdownImage` 和
+`plugins.markdownMath` 的配置。它与 [为什么更新主题版本后新的功能没有生效？](#为什么更新主题版本后新的功能没有生效)
+的原因相同。因此
+
+**只需要删除缓存文件，并重启即可**。
+
+1. 直接删除 `.vuepress/.cache` 目录。
+2. 在启动开发服务命令后面，添加 `--clean-cache` 参数：
+
+   ```sh
+   vuepress dev docs --clean-cache
+   ```
+
+## 更新依赖后重启提示 `import "xxxx" not exist`
+
+有时候更新主题以及相关依赖后，可能会存在 包管理器未能正确生成新的依赖树的问题，导致了 导入一些依赖时，提示找不到该依赖的错误。
+这时候的 依赖锁定文件如 `package-lock.json` 或 `pnpm-lock.yaml` 已经被污染。
+
+请直接删除 `package-lock.json` 或 `pnpm-lock.yaml` 等依赖锁定文件，以及删除 `node_modules` 目录，然后重新安装依赖。
diff --git a/docs/sponsor.md b/docs/sponsor.md
@@ -1,6 +1,5 @@
 ---
 title: 喝杯奶茶
-author: pengzhanbo
 createTime: 2024/04/18 18:03:50
 permalink: /sponsor/
 draft: true