diff --git a/docs/.vuepress/notes.ts b/docs/.vuepress/notes.ts index 98c9bd90..8e0003b6 100644 --- a/docs/.vuepress/notes.ts +++ b/docs/.vuepress/notes.ts @@ -108,7 +108,7 @@ export const zhNotes = definePlumeNotesConfig({ { text: '插件', items: [ - 'caniuse', + // 'caniuse', 'iconify', 'shiki', 'md-power', diff --git a/docs/notes/theme/config/plugins/百度统计.md b/docs/notes/theme/config/plugins/百度统计.md index e13f89a7..63b8b470 100644 --- a/docs/notes/theme/config/plugins/百度统计.md +++ b/docs/notes/theme/config/plugins/百度统计.md @@ -5,6 +5,10 @@ createTime: 2024/03/06 12:22:57 permalink: /config/plugins/baidu-tongji/ --- +::: caution +主题计划在 未来的版本中 从内置插件中移除此插件。 +::: + ## 概述 为站点添加 百度统计。该插件默认不启用。 diff --git a/docs/notes/theme/config/主题配置.md b/docs/notes/theme/config/主题配置.md index d89793f5..4304398f 100644 --- a/docs/notes/theme/config/主题配置.md +++ b/docs/notes/theme/config/主题配置.md @@ -7,15 +7,31 @@ permalink: /config/basic/ ## 基础配置 +### configFile + +- 类型： `string` +- 默认值： `''` +- 详情： + + 自定义主题配置文件的路径。 + + 查看 [主题配置文件 `plume.config.js`](./配置说明.md#主题配置文件) 了解更多。 + ### plugins - 类型：`PlumeThemePluginOptions` - 默认值： `{}` -- 详情： 对主题内部使用的插件进行自定义配置。 +- 详情： -主题使用的插件默认已进行了配置，大多数情况下您不需要进行任何修改，如果需要使用到细致的定制化，请查阅 + 对主题内部使用的插件进行自定义配置。 + + 主题使用的插件默认已进行了配置，大多数情况下您不需要进行修改，如果需要使用到细致的定制化，请查阅 [此文档](/config/plugins/) + ::: warning + 该字段不支持在 [主题配置文件 `plume.config.js`](./配置说明.md#主题配置文件) 中进行配置。 + ::: + ### hostname - 类型： `string` @@ -26,6 +42,10 @@ permalink: /config/basic/ 当 `hostname` 配置为有效域名时，主题将会生成 `sitemap` 和 `seo` 相关的内容。 + ::: warning + 该字段不支持在 [主题配置文件 `plume.config.js`](./配置说明.md#主题配置文件) 中进行配置。 + ::: + ### blog - 类型： `false | BlogOptions` @@ -44,18 +64,16 @@ interface BlogOptions { link?: string /** - * 在 `blog.dir` 目录中，通过 glob string 配置包含文件 + * 在 `{sourceDir}` 目录中，通过 glob string 配置包含文件 * * @default - ['**\*.md'] */ include?: string[] /** - * 在 `blog.dir` 目录中，通过 glob string 配置排除的文件 + * 在 `{sourceDir}` 目录中，通过 glob string 配置排除的文件 * - * README.md 文件一般作为主页或者某个目录下的主页，不应该被读取为 blog文章 - * - * @default - ['.vuepress/', 'node_modules/', '{README,index}.md'] + * @default - ['.vuepress/', 'node_modules/'] */ exclude?: string[] @@ -89,6 +107,54 @@ interface BlogOptions { - 默认值： `/article/` - 详情： 文章链接前缀 +### autoFrontmatter + +- 类型： `false | AutoFrontmatter` +- 详情： + + 是否为 markdown 文件自动添加 frontmatter 配置 + + ```ts + interface AutoFrontmatter { + /** + * glob 匹配，被匹配的文件将会自动生成 frontmatter + * + * @default ['**\/*.md'] + */ + include?: string | string[] + + /** + * glob 匹配，被匹配的文件将不会自动生成 frontmatter + */ + exclude?: string | string[] + + /** + * 是否自动生成 permalink + * + * @default true + */ + permalink?: boolean + /** + * 是否自动生成 createTime + * + * 默认读取 文件创建时间，`createTitme` 比 vuepress 默认的 `date` 时间更精准到秒 + */ + createTime?: boolean + /** + * 是否自动生成 author + * + * 默认读取 `profile.name` 或 `package.json` 的 `author` + */ + author?: boolean + /** + * 是否自动生成 title + * + * 默认读取文件名作为标题 + */ + title?: boolean + } + ``` + ### locales - 类型： `Record` @@ -235,13 +301,22 @@ export default { - 默认值： `[]` - 详情： 导航栏配置。 - 为了配置导航栏元素，你可以将其设置为 导航栏数组 ，其中的每个元素是 `NavItem` 对象、 + 为了配置导航栏元素，你可以将其设置为 导航栏数组 ，其中的每个元素是 `string` 或 `NavItem` 对象、 - `NavItem` 对象应该有一个 text 字段和一个 link 字段，还有一个可选的 `activeMatch` 字段。 + - `string` 表示是一个页面文件路径，或者是一个页面的访问路径。 ``` ts type NavItem = string | { text: string link: string + + /** + * 当前分组的页面前缀 + */ + prefix?: string + /** + * 该分组下的导航项 + */ items?: NavItem[] /** * 支持 iconify 图标，直接使用 iconify name 即可自动加载 @@ -267,10 +342,11 @@ type NavItem = string | { // NavbarGroup { text: 'Group', - item: ['/group/foo/', '/group/bar/'], + prefix: '/group/', + item: ['foo/', 'bar/'], }, // 字符串 - 页面文件路径 - '/bar/', + '/bar', // 可以直接省略后缀 `.md` ], }), } diff --git a/docs/notes/theme/config/多语言配置.md b/docs/notes/theme/config/多语言配置.md index a03f8c9a..d4ea24b7 100644 --- a/docs/notes/theme/config/多语言配置.md +++ b/docs/notes/theme/config/多语言配置.md @@ -61,11 +61,18 @@ export default defineUserConfig({ - 简体中文 (zh-CN) - 英文(美国) (en-US) +::: tip + +如果您希望支持更多语言，欢迎通过 +[PR](https://github.com/pengzhanbo/vuepress-theme-plume/pulls?q=sort%3Aupdated-desc+is%3Apr+is%3Aopen) 在 主题仓库的 `/theme/src/node/locales` 目录中按照相同的方式添加语言。 + +::: + ## 为每个语言设置主题选项 与站点配置和 `@vuepress/theme-default` 的主题配置相同，`vuepress-theme-plume` 也支持你在主题选项中设置 locale 选项，并为每种语言设置不同的配置。 -```ts +```ts :no-line-numbers import { defineUserConfig } from 'vuepress' import { plumeTheme } from 'vuepress-theme-plume' @@ -95,3 +102,49 @@ export default defineUserConfig({ }), }) ``` + +**使用主题配置文件：** + +::: code-tabs +@tab .vuepress/config.ts + +```ts +import { defineUserConfig } from 'vuepress' +import { plumeTheme } from 'vuepress-theme-plume' + +export default defineUserConfig({ + locales: { + '/': { + lang: 'en-US', + }, + '/zh/': { + lang: 'zh-CN', + }, + }, + + theme: plumeTheme(), +}) +``` + +@tab .vuepress/plume.config.ts + +```ts +import { defineThemeConfig } from 'vuepress-theme-plume' + +export default defineThemeConfig({ + // 通用配置 + // ... + locales: { + '/': { + // 英文配置 + // ... + }, + '/zh/': { + // 中文配置 + // ... + }, + }, +}) +``` + +::: diff --git a/docs/notes/theme/config/配置说明.md b/docs/notes/theme/config/配置说明.md index c4003ffb..c24c5fec 100644 --- a/docs/notes/theme/config/配置说明.md +++ b/docs/notes/theme/config/配置说明.md @@ -5,7 +5,9 @@ createTime: 2024/03/02 10:48:14 permalink: /config/intro/ --- -## 概述 +## VuePress 配置文件 + +### 概述 VuePress 站点的基本配置文件是 `.vuepress/config.js` ，但也同样支持 TypeScript 配置文件。 你可以使用 `.vuepress/config.ts` 来得到更好的类型提示。 @@ -33,7 +35,10 @@ import { defineUserConfig } from 'vuepress' export default defineUserConfig({ bundler: viteBundler(), - theme: plumeTheme(), + + theme: plumeTheme({ + // 在这里配置主题 + }), lang: 'zh-CN', title: '你好， VuePress ！', @@ -41,10 +46,94 @@ export default defineUserConfig({ }) ``` -## 类型 +### 类型 在 VuePress 中，有三种配置类型: - 站点配置: 这是你在 配置文件 中直接导出的对象 - 主题配置: 传递给 `plumeTheme` 的对象参数 - 页面配置: 由在页面顶部基于 YAML 语法的 Frontmatter 提供 + +## 主题配置文件 + +### 概述 + +一般我们使用 `.vuepress/config.js` 或者 `.vuepress/config.ts` 来配置主题。 + +```ts +import { plumeTheme } from 'vuepress-theme-plume' +import { defineUserConfig } from 'vuepress' + +export default defineUserConfig({ + theme: plumeTheme({ + // 在这里配置主题 + }), +}) +``` + +但是当我们已经启动了 VuePress 服务，对该文件的修改会导致 VuePres 服务重启，然后站点进行全量刷新， +这可能需要等待一段时间才能恢复， 如果你的站点内容不多还能够接受， +而对于一些较大的站点，可能需要等待漫长的时间。 + +特别是当我们频繁修改，或者修改的间隔较短时，很容易使 VuePress 服务 崩溃，我们不得不手动重启。 + +**这给我们在编写站点内容时带来的极大的不便。** + +为了解决这一问题，主题支持在 单独的 主题配置文件中进行配置。 + +**对该文件的修改将通过热更新的方式实时生效。** + +### 配置 + +你可以直接在 [VuePress 配置文件](#vuepress-配置文件) 相同的路径下创建一个 `plume.config.js` 文件，这样就可以在该文件中进行主题配置。 +你也可以使用 TypeScript 来创建一个 `plume.config.ts` 文件，以获得更好的类型提示。 + +```txt :no-line-numbers +{sourceDir}/.vuepress/ +├── config.ts +└── plume.config.ts // [!code ++] +``` + +::: code-tabs +@tab plume.config.ts + +```ts +import { defineThemeConfig } from 'vuepress-theme-plume' +import navbar from './navbar' + +export default defineThemeConfig({ + // 在这里配置主题 + profile: { + name: 'Your name', + }, + navbar, +}) +``` + +::: + +主题提供了 `defineThemeConfig(config)` 函数，为主题使用者提供主题配置的类型帮助。 +你可以直接在这个文件中配置除了 `plugins` 字段外的其他配置。 + +### 自定义配置文件路径 + +如果你不希望按照 VuePress 默认的配置文件路径管理你的主题配置文件， +你也可以在 VuePress 配置文件中指定自己的主题配置文件路径。 + +```ts +import path from 'node:path' +import { plumeTheme } from 'vuepress-theme-plume' +import { defineUserConfig } from 'vuepress' + +export default defineUserConfig({ + theme: plumeTheme({ + // 在这里定义自己的主题配置文件路径 + configFile: path.join(__dirname, 'custom/config.ts'), // [!code ++] + }), +}) +``` + +::: tip +更推荐 使用 主题配置文件 来单独管理 主题配置，你不必再为频繁修改配置而一直等待 +VuePress 重启。 +::: diff --git a/docs/notes/theme/guide/介绍.md b/docs/notes/theme/guide/介绍.md index 4af1d6d4..3ab2b410 100644 --- a/docs/notes/theme/guide/介绍.md +++ b/docs/notes/theme/guide/介绍.md @@ -11,19 +11,22 @@ tags: ## 介绍 -vuepress-theme-plume 是一个基于 VuePress 的主题。适用于 博客、文档 和 知识笔记 。 +**vuepress-theme-plume** 是一个基于 VuePress 的主题，适用于 博客、文档 和 知识笔记 。 VuePress 是一个 [静态站点生成器](https://en.wikipedia.org/wiki/Static_site_generator) (SSG) 。 专为构建快速、以内容为中心的站点而设计。 简而言之，VuePress 获取用 Markdown 编写的内容，对其应用主题，并生成可以轻松部署到任何地方的静态 HTML 页面。 ::: tip + 本主题 基于 [vuepress-next](https://github.com/vuepress/vuepress-next), 目前处于 RC 阶段。 当前主题 功能和 API 趋于稳定，但在未来的更新中仍有小概率出现破坏更改。 -如果您在使用过程中遇到问题，或者有新的想法，请在 [Issues](https://github.com/pengzhanbo/vuepress-theme-plume/issues) 里提出， +如果您在使用过程中遇到问题，或者有新的想法， +请在 [Issues](https://github.com/pengzhanbo/vuepress-theme-plume/issues) 里提出， 也欢迎 通过 [PR](https://github.com/pengzhanbo/vuepress-theme-plume/pulls) 帮助完善主题。 + ::: ## 优势 @@ -33,6 +36,8 @@ VuePress 是一个 [静态站点生成器](https://en.wikipedia.org/wiki/Static_ - 大幅度优化了界面、交互，更具美观度，更好的用户体验。 - 同时，还添加了大量的丰富实用的功能，如 代码分组、提示容器、任务列表、数学公式、代码演示、 内容搜索、文章评论、加密 等。 +- 新增编译缓存，加快启动速度。 +- 支持使用单独的主题配置文件，避免修改配置导致频繁重启 VuePress 服务。 - 大幅度简化了配置，更易于使用，同时还保留了丰富灵活的配置项，满足个性化的需求。 `plume` 主题尽可能的内置你可能需要的功能，以及搭建站点所需要的一般性配置，您无需关注这些细节。 diff --git a/docs/notes/theme/guide/博客.md b/docs/notes/theme/guide/博客.md index 745a3193..369c0800 100644 --- a/docs/notes/theme/guide/博客.md +++ b/docs/notes/theme/guide/博客.md @@ -89,10 +89,27 @@ tags: | sticky | `boolean \| number` | false | 是否置顶, 如果为数字，则数字越大，置顶越靠前 | | draft | `boolean` | false | 是否为草稿，草稿文章不会被展示 | +除了以上的字段，你还可以使用 [通用 frontmatter 配置](../config/frontmatter/basic.md) 中的字段， +灵活的控制当前页面的行为。 + ## 文章摘要 如果你想要为文章添加摘要，你可以使用 `` 注释来标记它。任何在此注释之前的内容会被视为摘要。 +***示例：** + +```md +--- +title: 标题 +--- + +这里的内容会被作为摘要 + + + +这里的内容不会被作为摘要 +``` + ## 标签页和归档页 主题除了自动生成 **博客文章列表页** 以外，还会自动生成 **标签页** 和 **归档页**。 diff --git a/docs/notes/theme/guide/知识笔记.md b/docs/notes/theme/guide/知识笔记.md index 428b7c0d..7504ff54 100644 --- a/docs/notes/theme/guide/知识笔记.md +++ b/docs/notes/theme/guide/知识笔记.md @@ -11,10 +11,10 @@ tags: ## 概述 -在本主题满足了 Blog的基本功能后，期望能够 以 note 或者 book 的形式聚合文章，形式上类似于 vuepress 默认主题。 +在本主题满足了 Blog 的基本功能后，期望能够 以 note 或者 book 的形式聚合文章，形式上类似于 vuepress 默认主题。 同时也减少配置的复杂度。 -它能够让你以更加友好的方式，组织管理你的文档，或者 知识笔记。 +它能够让你以更加友好的方式，组织管理你的文档。 ## 目录 @@ -72,8 +72,10 @@ export default defineUserConfig({ 主题会根据配置，为对应目录中的 md 文件，生成 永久链接，以及侧边栏。 ::: tip + 你应该在创建文件之前，先把笔记的目录和链接前缀等配置好，主题需要根据配置， 为目录中的 md 文件生成永久链接，以及侧边栏。 + ::: 完整配置查看 [notes配置](/config/notes/)