gitea-yuany3721/vuepress-theme-plume
1
0
Fork 1
mirror of https://github.com/pengzhanbo/vuepress-theme-plume.git synced 2026-04-23 10:58:13 +08:00
Code Issues Packages Projects Releases Wiki Activity

docs: update docs

Browse Source
This commit is contained in:
pengzhanbo 2024-08-16 01:59:35 +08:00
parent fbcd141a39
commit c9d58bd418
8 changed files with 215 additions and 61 deletions
Show Stats Download Patch File Download Diff File Expand all files Collapse all files

1
docs/.vuepress/notes.ts
View File

@ -95,6 +95,7 @@ export const zhNotes = definePlumeNotesConfig({
'主题配置',
'导航栏配置',
'notes配置',
'侧边栏配置',
],
},
{

78
docs/notes/theme/config/notes配置.md
View File

@ -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<NotesItem, 'text'> & { 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 }
```
### 自动生成侧边栏

80
docs/notes/theme/config/主题配置.md
View File

@ -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`

72
docs/notes/theme/config/侧边栏配置.md Normal file
View File

@ -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' },
]
}
})
})
```

25
docs/notes/theme/config/导航栏配置.md
View File

@ -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，生成嵌套的导航栏
*/

2
docs/notes/theme/guide/功能/seo.md
View File

@ -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) 许可证。
:::

2
docs/notes/theme/guide/功能/文章水印.md
View File

@ -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) 提供支持。
主题支持在文章中添加水印。支持 全屏水印 和 内容水印，同时还支持 图片水印 和 文字水印 。

16
docs/notes/theme/guide/功能/评论.md
View File

@ -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)
:::