diff --git a/docs/.vuepress/notes.ts b/docs/.vuepress/notes.ts index 0109a963..43875e22 100644 --- a/docs/.vuepress/notes.ts +++ b/docs/.vuepress/notes.ts @@ -95,6 +95,7 @@ export const zhNotes = definePlumeNotesConfig({ '主题配置', '导航栏配置', 'notes配置', + '侧边栏配置', ], }, { diff --git a/docs/notes/theme/config/notes配置.md b/docs/notes/theme/config/notes配置.md index 8726e347..2d2346d6 100644 --- a/docs/notes/theme/config/notes配置.md +++ b/docs/notes/theme/config/notes配置.md @@ -49,7 +49,7 @@ export default defineUserConfig({ interface NotesDataOptions { /** * 保存所有笔记的目录 - * @default '/notes' + * @default '/notes/' */ dir: string /** @@ -57,22 +57,12 @@ interface NotesDataOptions { * @default '/' */ link: string - /** - * global include,只加载需要加载到笔记中的文件 - */ - include?: string | string[] - /** - * global exclude,排除不需要加载到笔记中的文件 - */ - exclude?: string | string[] /** * 笔记配置 */ - notes: NotesItemOptions[] + notes: NoteItem[] } -type NotesItemOptions = (Omit & { text?: string }) - interface NotesItem { /** * 保存笔记的目录 @@ -85,50 +75,64 @@ interface NotesItem { /** * 当前笔记名称 */ - text: string + text?: string /** - * 当前笔记的侧边栏配置, - * 如果设置为 `auto`,则自动根据目录结构生成侧边栏,根据 `\d+.xxx[.md]` 中 `\d+` 进行排序 + * 当前笔记的侧边栏配置 + * - `'auto'` 根据目录结构自动生成侧边栏 + * - `string` 侧边栏文件路径, 如 `'/notes/sidebar.md'`,主题将会读取该文件作为侧边栏 + * - `SidebarItem` 单项侧边栏配置 */ - sidebar?: NotesSidebar | 'auto' + sidebar?: 'auto' | (string | SidebarItem)[] } -/** - * 可以将配置简写为文件名,主题会自动解析 - */ -type NotesSidebar = (NotesSidebarItem | string)[] - -interface NotesSidebarItem { +export interface SidebarItem { /** - * 侧边栏文本,如果为空,则使用 `dir` + * 侧边栏文本 */ text?: string + /** * 侧边栏链接 */ link?: string + /** - * 次级侧边栏所在目录 + * 侧边栏图标 */ - dir?: string + icon?: ThemeIcon + /** - * 是否折叠, 未定义时不可折叠 - * @default undefined + * 次级侧边栏分组 + * 不超过 3 层 + */ + items?: 'auto' | (string | SidebarItem)[] + + /** + * 如果未指定,组不可折叠。 + * + * 如果为`true`,组可折叠,并默认折叠。 + * + * 如果为`false`,组可折叠,但默认展开。 */ collapsed?: boolean + /** - * 次级侧边栏 + * 当前分组的链接前缀 */ - items?: NotesSidebar - /** - * - 支持 iconify 图标,直接使用 iconify name 即可自动加载 - * @see https://icon-sets.iconify.design/ - * - * - 如果 iconify 图标不满足您的需求,也可以支持传入 svg 字符串。 - * - 还支持使用 本地图片 或 远程图片,本地图片的路径需要以 `/` 开头。 - */ - icon?: string | { svg: string } + prefix?: string + + rel?: string + target?: string } + +/** + * - 支持 iconify 图标,直接使用 iconify name 即可自动加载 + * @see https://icon-sets.iconify.design/ + * + * - 如果 iconify 图标不满足您的需求,也可以支持传入 svg 字符串。 + * - 还支持使用 本地图片 或 远程图片,本地图片的路径需要以 `/` 开头。 + */ +export type ThemeIcon = string | { svg: string } ``` ### 自动生成侧边栏 diff --git a/docs/notes/theme/config/主题配置.md b/docs/notes/theme/config/主题配置.md index 8959d148..972b6be6 100644 --- a/docs/notes/theme/config/主题配置.md +++ b/docs/notes/theme/config/主题配置.md @@ -420,12 +420,6 @@ type NavItem = string | { } ``` -### footer - -- 类型: `false | { message: string; copyright: string }` -- 默认值: `false` -- 详情:页脚配置。 - ### notes - 类型: `false | PlumeThemeNotesOptions` @@ -436,7 +430,73 @@ type NavItem = string | { 你可以将配置的notes 配置到 navbar中,以便浏览查看 -详细配置请查看 [此文档](/config/notes/) +详细配置请查看 [此文档](./notes配置.md) + +### sidebar + +- 类型: `false | SidebarMulti` + +- 详情: + + 侧边栏配置。**主题更推荐在 [notes 配置](./notes配置.md) 中进行侧边栏配置。** + + 当你不希望使用 `notes` 功能,但又期望给文档增加侧边栏时,可以使用此配置。 + + 配置对象的 `key` 为侧边栏公共访问路径前缀。 + + 对于 `value`: + - `'auto'` 表示自动根据目录结构生成侧边栏 + - `string` 表示侧边栏对应的页面文件路径 + - `SidebarItem` 表示侧边栏单项配置 + +```ts +type ThemeIcon = string | { svg: string } + +type SidebarMulti = Record< + string, + | 'auto' + | (string | SidebarItem)[] + | { items: 'auto' | (string | SidebarItem)[], prefix?: string } +> +interface SidebarItem { + /** + * 侧边栏文本 + */ + text?: string + + /** + * 侧边栏链接 + */ + link?: string + + /** + * 侧边栏图标 + */ + icon?: ThemeIcon + + /** + * 次级侧边栏分组 + */ + items?: 'auto' | (string | SidebarItem)[] + + /** + * 如果未指定,组不可折叠。 + * + * 如果为`true`,组可折叠,并默认折叠。 + * + * 如果为`false`,组可折叠,但默认展开。 + */ + collapsed?: boolean + + /** + * 当前分组的链接前缀 + */ + prefix?: string + + rel?: string + target?: string +} +``` ### aside @@ -502,6 +562,12 @@ type NavItem = string | { } ``` +### footer + +- 类型: `false | { message: string; copyright: string }` +- 默认值: `false` +- 详情:页脚配置。 + ### selectLanguageName - 类型: `string` diff --git a/docs/notes/theme/config/侧边栏配置.md b/docs/notes/theme/config/侧边栏配置.md new file mode 100644 index 00000000..813e718b --- /dev/null +++ b/docs/notes/theme/config/侧边栏配置.md @@ -0,0 +1,72 @@ +--- +title: 侧边栏配置 +author: Plume Theme +createTime: 2024/08/15 21:05:36 +permalink: /config/sidebar/ +--- + +## 概述 + +在本主题中,侧边栏 特指 位于页面 最左侧的内容区域,用于导航到不同的页面。 + +在 `vuepress` 的默认主题 `@vuepress/theme-default` 中,侧边栏是通过 `sidebar` 进行配置。 + +**但在本主题中,为使其更具语义化,主题将侧边栏配置整合到了 [notes 配置](./notes配置.md) 中** 。 +通过一个 `note` 对应一个 `sidebar` 的方式,实现更加简洁,语义化的侧边栏配置。 + +同时,为了满足 用户不希望使用 `notes` 功能的需求,本主题也提供了 `sidebar` 的选项进行侧边栏配置。 + +## Notes 中的侧边栏配置 + +`notes` 的功能是聚合一系列的文章,通过侧边栏来导航到 notes 中不同的文章。 + +你可以在 `notes` 目录下创建多个 `note` ,在每一个 `note` 中单独配置 `sidebar`: + +```ts +import { defineUserConfig } from 'vuepress' +import { defineNoteConfig, plumeTheme } from 'vuepress-theme-plume' + +// [!code ++:9] +const noteA = defineNoteConfig({ + dir: 'note A', + link: '/note-a/', + sidebar: [ + { text: 'one item', link: 'one' }, + { text: 'two item', link: 'two' }, + ] +}) + +export default defineUserConfig({ + theme: plumeTheme({ + notes: { + link: '/', + dir: 'notes', + notes: [noteA], // [!code ++] + }, + }) +}) +``` + +主题提供了 `defineNoteConfig` 来帮助你配置 note , 你可以参考 [这里](./notes配置.md)来查看如何配置。 + +## 通用 Sidebar 配置 + +如果你不想使用 `notes` 的方式来管理系列文章,但又期望通过侧边栏来导航到不同的文章, +可以通过 [sidebar](../config/主题配置.md#sidebar) 通用配置来实现。 + +```ts +import { defineUserConfig } from 'vuepress' +import { plumeTheme } from 'vuepress-theme-plume' + +export default defineUserConfig({ + theme: plumeTheme({ + notes: false, + sidebar: { + '/config/': [ + { text: '侧边栏配置', link: 'sidebar-1' }, + { text: '侧边栏配置', link: 'sidebar-2' }, + ] + } + }) +}) +``` diff --git a/docs/notes/theme/config/导航栏配置.md b/docs/notes/theme/config/导航栏配置.md index 567f0a83..d8a27b3e 100644 --- a/docs/notes/theme/config/导航栏配置.md +++ b/docs/notes/theme/config/导航栏配置.md @@ -23,8 +23,10 @@ import { plumeTheme } from 'vuepress-theme-plume' export default defineUserConfig({ theme: plumeTheme({ navbar: [ - { text: '首页', link: '/', icon: 'material-symbols:home-outline' }, - { text: '博客', link: '/blog/', icon: 'material-symbols:article-outline' }, + { text: '首页', link: '/' }, + { text: '博客', link: '/blog/' }, + { text: '标签', link: '/blog/tags/' }, + { text: '归档', link: '/blog/archives/' } ] }) }) @@ -51,14 +53,18 @@ export default defineUserConfig({ locales: { '/': { navbar: [ - { text: '首页', link: '/', icon: 'material-symbols:home-outline' }, - { text: '博客', link: '/blog/', icon: 'material-symbols:article-outline' }, + { text: '首页', link: '/' }, + { text: '博客', link: '/blog/' }, + { text: '标签', link: '/blog/tags/' }, + { text: '归档', link: '/blog/archives/' } ] }, '/en/': { navbar: [ - { text: 'Home', link: '/en/', icon: 'material-symbols:home-outline' }, - { text: 'Blog', link: '/en/blog/', icon: 'material-symbols:article-outline' }, + { text: '首页', link: '/en/' }, + { text: '博客', link: '/en/blog/' }, + { text: '标签', link: '/en/blog/tags/' }, + { text: '归档', link: '/en/blog/archives/' } ] } } @@ -68,7 +74,7 @@ export default defineUserConfig({ ::: -但是,通常情况下,随着站点内容变得越来越丰富,包括了 博客文章列表、notes、友情链接、 外部链接等等, +随着站点内容变得越来越丰富,包括了 博客文章列表、notes、友情链接、 外部链接等等, 默认生成的导航栏配置满足不了您的需求。 这时候,您可以通过 `navbar` 字段来完全自定义导航栏,它将直接覆盖默认的导航栏配置。 @@ -102,6 +108,11 @@ type NavItem = string | { * 控制元素何时被激活 */ activeMatch?: string + /** + * + * 当前分组的页面链接前缀 + */ + prefix?: string /** * 最大深度为 2,生成嵌套的导航栏 */ diff --git a/docs/notes/theme/guide/功能/seo.md b/docs/notes/theme/guide/功能/seo.md index 16f33329..abf23cd2 100644 --- a/docs/notes/theme/guide/功能/seo.md +++ b/docs/notes/theme/guide/功能/seo.md @@ -20,7 +20,7 @@ export default defineUserConfig({ ``` ::: note -示例 Fork 自 [@vuepress/plugin-seo](https://ecosystem.vuejs.press/zh/plugins/seo/), +示例 Fork 自 [@vuepress/plugin-seo](https://ecosystem.vuejs.press/zh/plugins/seo/seo/), 遵循 [MIT](https://github.com/vuepress/ecosystem/blob/main/LICENSE) 许可证。 ::: diff --git a/docs/notes/theme/guide/功能/文章水印.md b/docs/notes/theme/guide/功能/文章水印.md index 56c3982e..3fa89a58 100644 --- a/docs/notes/theme/guide/功能/文章水印.md +++ b/docs/notes/theme/guide/功能/文章水印.md @@ -8,7 +8,7 @@ permalink: /guide/features/watermark/ ## 概述 -文章水印由 [@vuepress/plugin-watermark](https://ecosystem.vuejs.press/zh/plugins/watermark.html) 提供支持。 +文章水印由 [@vuepress/plugin-watermark](https://ecosystem.vuejs.press/zh/plugins/features/watermark.html) 提供支持。 主题支持在文章中添加水印。支持 全屏水印 和 内容水印,同时还支持 图片水印 和 文字水印 。 diff --git a/docs/notes/theme/guide/功能/评论.md b/docs/notes/theme/guide/功能/评论.md index e992a116..d5e9e4f7 100644 --- a/docs/notes/theme/guide/功能/评论.md +++ b/docs/notes/theme/guide/功能/评论.md @@ -8,7 +8,7 @@ permalink: /guide/features/comments/ ## 概述 -文章评论由 [@vuepress/plugin-comment](https://ecosystem.vuejs.press/zh/plugins/comment/) 提供支持。 +文章评论由 [@vuepress/plugin-comment](https://ecosystem.vuejs.press/zh/plugins/blog/comment/) 提供支持。 主题已内置插件,你无需重新安装即可使用。 @@ -42,15 +42,15 @@ export default defineUserConfig({ ### 服务提供商 -[@vuepress/plugin-comment](https://ecosystem.vuejs.press/zh/plugins/comment/) 支持 +[@vuepress/plugin-comment](https://ecosystem.vuejs.press/zh/plugins/blog/comment/) 支持 `"Artalk" | "Giscus" | "Twikoo" | "Waline"` 等多种不同的评论服务提供商。 你可以根据自己的需求进行配置。 -- `Giscus` 是一个基于 GitHub Discussion 的评论系统,启用简便。[查看文档](https://ecosystem.vuejs.press/zh/plugins/comment/giscus/) -- `Waline` 是一个 需要后端的评论系统,安全性较高。[查看文档](https://ecosystem.vuejs.press/zh/plugins/comment/waline/) -- `Twikoo` 一个简洁、安全、免费的静态网站评论系统,基于 腾讯云开发。[查看文档](https://ecosystem.vuejs.press/zh/plugins/comment/twikoo/) -- `Artalk` 是一款简洁的自托管评论系统,你可以在服务器上轻松部署并置入前端页面中。[查看文档](https://ecosystem.vuejs.press/zh/plugins/comment/artalk/) +- `Giscus` 是一个基于 GitHub Discussion 的评论系统,启用简便。[查看文档](https://ecosystem.vuejs.press/zh/plugins/blog/comment/giscus/) +- `Waline` 是一个 需要后端的评论系统,安全性较高。[查看文档](https://ecosystem.vuejs.press/zh/plugins/blog/comment/waline/) +- `Twikoo` 一个简洁、安全、免费的静态网站评论系统,基于 腾讯云开发。[查看文档](https://ecosystem.vuejs.press/zh/plugins/blog/comment/twikoo/) +- `Artalk` 是一款简洁的自托管评论系统,你可以在服务器上轻松部署并置入前端页面中。[查看文档](https://ecosystem.vuejs.press/zh/plugins/blog/comment/artalk/) ::: tip 推荐的评论服务 @@ -59,7 +59,7 @@ export default defineUserConfig({ ::: ::: note -示例 Fork 自 [@vuepress/plugin-comment](https://ecosystem.vuejs.press/zh/plugins/comment/), +示例 Fork 自 [@vuepress/plugin-comment](https://ecosystem.vuejs.press/zh/plugins/blog/comment/), 遵循 [MIT](https://github.com/vuepress/ecosystem/blob/main/LICENSE) 许可证。 ::: @@ -246,7 +246,7 @@ yarn add @waline/client ::: tip -你也可以传入其他 Waline 支持的选项 (除了 `el`)。详情请见 [Waline 配置](https://ecosystem.vuejs.press/zh/plugins/comment/waline/config.html) +你也可以传入其他 Waline 支持的选项 (除了 `el`)。详情请见 [Waline 配置](https://ecosystem.vuejs.press/zh/plugins/blog/comment/waline/config.html) :::