mirror of
https://github.com/pengzhanbo/vuepress-theme-plume.git
synced 2026-04-23 10:58:13 +08:00
docs: update doc
This commit is contained in:
pengzhanbo
parent
1ef9744e04
commit
0142fe9fa3
@ -108,7 +108,7 @@ export const zhNotes = definePlumeNotesConfig({
|
||||
{
|
||||
text: '插件',
|
||||
items: [
|
||||
'caniuse',
|
||||
// 'caniuse',
|
||||
'iconify',
|
||||
'shiki',
|
||||
'md-power',
|
||||
|
||||
@ -5,6 +5,10 @@ createTime: 2024/03/06 12:22:57
|
||||
permalink: /config/plugins/baidu-tongji/
|
||||
---
|
||||
|
||||
::: caution
|
||||
主题计划在 未来的版本中 从内置插件中移除此插件。
|
||||
:::
|
||||
|
||||
## 概述
|
||||
|
||||
为站点添加 百度统计。该插件默认不启用。
|
||||
|
||||
@ -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<string, PlumeThemeLocaleConfig>`
|
||||
@ -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`
|
||||
],
|
||||
}),
|
||||
}
|
||||
|
||||
@ -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/': {
|
||||
// 中文配置
|
||||
// ...
|
||||
},
|
||||
},
|
||||
})
|
||||
```
|
||||
|
||||
:::
|
||||
|
||||
@ -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 重启。
|
||||
:::
|
||||
|
||||
@ -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` 主题尽可能的内置你可能需要的功能，以及搭建站点所需要的一般性配置，您无需关注这些细节。
|
||||
|
||||
@ -89,10 +89,27 @@ tags:
|
||||
| sticky | `boolean \| number` | false | 是否置顶, 如果为数字，则数字越大，置顶越靠前 |
|
||||
| draft | `boolean` | false | 是否为草稿，草稿文章不会被展示 |
|
||||
|
||||
除了以上的字段，你还可以使用 [通用 frontmatter 配置](../config/frontmatter/basic.md) 中的字段，
|
||||
灵活的控制当前页面的行为。
|
||||
|
||||
## 文章摘要
|
||||
|
||||
如果你想要为文章添加摘要，你可以使用 `<!-- more -->` 注释来标记它。任何在此注释之前的内容会被视为摘要。
|
||||
|
||||
***示例：**
|
||||
|
||||
```md
|
||||
---
|
||||
title: 标题
|
||||
---
|
||||
|
||||
这里的内容会被作为摘要
|
||||
|
||||
<!-- more -->
|
||||
|
||||
这里的内容不会被作为摘要
|
||||
```
|
||||
|
||||
## 标签页和归档页
|
||||
|
||||
主题除了自动生成 **博客文章列表页** 以外，还会自动生成 **标签页** 和 **归档页**。
|
||||
|
||||
@ -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/)
|
||||
|
||||
Loading…
x
Reference in New Issue
Block a user