660 lines
14 KiB
Markdown
660 lines
14 KiB
Markdown
---
|
||
title: 主题配置
|
||
author: pengzhanbo
|
||
createTime: 2024/03/02 18:07:03
|
||
permalink: /config/basic/
|
||
---
|
||
|
||
## 基础配置
|
||
|
||
### configFile
|
||
|
||
- 类型： `string`
|
||
- 默认值： `''`
|
||
- 详情：
|
||
|
||
自定义主题配置文件的路径。
|
||
|
||
查看 [主题配置文件 `plume.config.js`](./配置说明.md#主题配置文件) 了解更多。
|
||
|
||
### plugins
|
||
|
||
- 类型：`PlumeThemePluginOptions`
|
||
- 默认值： `{}`
|
||
- 详情：
|
||
|
||
对主题内部使用的插件进行自定义配置。
|
||
|
||
主题使用的插件默认已进行了配置，大多数情况下您不需要进行修改，如果需要使用到细致的定制化，请查阅
|
||
[此文档](/config/plugins/)
|
||
|
||
::: warning
|
||
该字段不支持在 [主题配置文件 `plume.config.js`](./配置说明.md#主题配置文件) 中进行配置。
|
||
:::
|
||
|
||
### hostname
|
||
|
||
- 类型： `string`
|
||
- 默认值： `''`
|
||
- 详情：
|
||
|
||
部署站点域名。
|
||
|
||
当 `hostname` 配置为有效域名时，主题将会生成 `sitemap` 和 `seo` 相关的内容。
|
||
|
||
::: warning
|
||
该字段不支持在 [主题配置文件 `plume.config.js`](./配置说明.md#主题配置文件) 中进行配置。
|
||
:::
|
||
|
||
### blog
|
||
|
||
- 类型： `false | BlogOptions`
|
||
- 默认值： `{ link: '/blog/', include: ['**/*.md'], exclude: [] }`
|
||
- 详情：
|
||
|
||
博客配置。
|
||
|
||
```ts
|
||
interface BlogOptions {
|
||
/**
|
||
* blog list link
|
||
*
|
||
* @default '/blog/'
|
||
*/
|
||
link?: string
|
||
|
||
/**
|
||
* 在 `{sourceDir}` 目录中，通过 glob string 配置包含文件
|
||
*
|
||
* @default - ['**\*.md']
|
||
*/
|
||
include?: string[]
|
||
|
||
/**
|
||
* 在 `{sourceDir}` 目录中，通过 glob string 配置排除的文件
|
||
*
|
||
* @default - ['.vuepress/', 'node_modules/']
|
||
*/
|
||
exclude?: string[]
|
||
|
||
/**
|
||
* 分页配置
|
||
*/
|
||
pagination?: false | {
|
||
/**
|
||
* 每页显示的文章数量
|
||
* @default 10
|
||
*/
|
||
perPage?: number
|
||
}
|
||
|
||
/**
|
||
* 是否启用标签页
|
||
* @default true
|
||
*/
|
||
tags?: boolean
|
||
/**
|
||
* 是否启用归档页
|
||
* @default true
|
||
*/
|
||
archives?: boolean
|
||
|
||
/**
|
||
* 是否启用分类页
|
||
* @default true
|
||
*/
|
||
categories?: boolean
|
||
}
|
||
```
|
||
|
||
### article
|
||
|
||
- 类型： `string`
|
||
- 默认值： `/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
|
||
}
|
||
```
|
||
|
||
### cache
|
||
|
||
- 类型： `false | 'memory' | 'filesystem'`
|
||
- 默认值： `filesystem`
|
||
- 详情：
|
||
|
||
是否启用 编译缓存，或配置缓存方式
|
||
|
||
此配置项用于解决 VuePress 启动速度慢的问题，在首次启动服务时，对编译结果进行缓存，二次启动时
|
||
直接读取缓存，跳过编译，从而加快启动速度。
|
||
|
||
- `false`：禁用 缓存
|
||
- `'memory'`：使用内存缓存，此方式可获得更快的启动速度，但随着项目文件数量增加，内存占用会增加，
|
||
适合文章数量较少的项目使用
|
||
- `'filesystem'`：使用文件系统缓存，此方式可获得相对快且稳定的启动速度，更适合内容多的项目使用
|
||
|
||
::: warning
|
||
该字段不支持在 [主题配置文件 `plume.config.js`](./配置说明.md#主题配置文件) 中进行配置。
|
||
:::
|
||
|
||
### locales
|
||
|
||
- 类型： `Record<string, PlumeThemeLocaleConfig>`
|
||
- 默认值： `{}`
|
||
- 详情： 多语言配置
|
||
|
||
多语言配置，参考 [此文档](/config/locales/)
|
||
|
||
多语言配置支持以下 [Locale](#locale-配置) 所有配置选项
|
||
|
||
## Locale 配置
|
||
|
||
### home
|
||
|
||
- 类型： `false | string`
|
||
- 默认值： `/`
|
||
- 详情：
|
||
首页的路径， 它将被用于：
|
||
- 导航栏中 logo的链接；
|
||
- 404页面的 *返回首页* 的链接；
|
||
|
||
### logo
|
||
|
||
- 类型: `false | string`
|
||
- 默认值： `false`
|
||
- 详情： 导航栏中的logo。
|
||
|
||
### logoDark
|
||
|
||
- 类型 `false | string`
|
||
- 默认值： `false`
|
||
- 详情： Dark模式下，导航栏中的logo。
|
||
|
||
### appearance
|
||
|
||
- 类型： `boolean | 'dark' | 'force-dark`
|
||
- 默认值： `true`
|
||
|
||
是否启用 深色模式。
|
||
|
||
- 如果该选项设置为 `true`，则默认主题将由用户的首选配色方案决定。
|
||
- 如果该选项设置为 `dark`，则默认情况下主题将是深色的，除非用户手动切换它。
|
||
- 如果该选项设置为 `false`，用户将无法切换主题。
|
||
- 如果该选项设置为 `force-dark`，则用户将无法切换主题，但会强制将主题更改为深色。
|
||
|
||
此选项注入一个内联脚本，从本地存储恢复用户设置。这确保在呈现页面之前应用 `.dark` 类以避免闪烁。
|
||
|
||
### appearanceText
|
||
|
||
- 类型： `string`
|
||
- 默认值： `'Appearance'`
|
||
- 详情： 导航栏中的主题切换按钮的文本。
|
||
|
||
### avatar <Badge type="danger" text="弃用" />
|
||
|
||
弃用，请使用 [profile](#profile)。
|
||
|
||
### profile
|
||
|
||
- 类型： `PlumeThemeProfile`
|
||
- 默认值： `{}`
|
||
- 详情：配置站点博主的个人信息
|
||
- `profile.avatar`: 头像地址，用于右侧博主信息展示
|
||
- `profile.name`: 名称， 用于右侧博主信息展示
|
||
- `profile.description`: 个人描述，用于右侧博主信息展示
|
||
- `profile.circle`: 是否为圆形头像
|
||
- `profile.location`: 用户地理位置
|
||
- `profile.organization`: 用户所在组织/公司
|
||
|
||
示例：
|
||
|
||
``` ts
|
||
export default {
|
||
theme: themePlume({
|
||
profile: {
|
||
avatar: '/avatar.jpg',
|
||
name: '张三',
|
||
description: '此处无银三百两，隔壁王二不曾偷',
|
||
circle: true,
|
||
location: '杭州，中国',
|
||
organization: 'xxx公司',
|
||
}
|
||
})
|
||
}
|
||
```
|
||
|
||
### social
|
||
|
||
- 类型： `false | SocialLink[]`
|
||
- 默认值： `false`
|
||
- 详情： 个人社交信息配置。
|
||
|
||
将作为 图标链接 展示在 导航栏最右侧。
|
||
|
||
图标可选值：
|
||
- `'github'`
|
||
- `'gitlab'`
|
||
- `'npm'`
|
||
- `'docker'`
|
||
- `'discord'`
|
||
- `'facebook'`
|
||
- `'instagram'`
|
||
- `'linkedin'`
|
||
- `'mastodon'`
|
||
- `'slack'`
|
||
- `'twitter'`
|
||
- `'x'`
|
||
- `'youtube'`
|
||
- `'juejin'`
|
||
- `'stackoverflow'`
|
||
- `'qq'`
|
||
- `'weibo'`
|
||
- `'bilibili'`
|
||
- `'zhihu'`
|
||
- `'douban'`
|
||
- `'steam'`
|
||
- `'xbox'`
|
||
- `{ svg: string }`: 自定义图标，传入 svg 字符串
|
||
|
||
示例：
|
||
|
||
``` ts
|
||
export default {
|
||
theme: themePlume({
|
||
social: [
|
||
{ icon: 'github', link: 'https://github.com/zhangsan' }
|
||
]
|
||
})
|
||
}
|
||
```
|
||
|
||
### navbarSocialInclude
|
||
|
||
- 类型： `string[]`
|
||
- 默认值： `['github', 'twitter', 'discord', 'facebook']`
|
||
- 详情：
|
||
|
||
允许显示在导航栏的社交链接。
|
||
该配置仅在 PC 端下有效。
|
||
|
||
### navbar
|
||
|
||
- 类型： `NavItem[]`
|
||
- 默认值： `[]`
|
||
- 详情： 导航栏配置。
|
||
|
||
为了配置导航栏元素，你可以将其设置为 导航栏数组 ，其中的每个元素是 `string` 或 `NavItem` 对象、
|
||
- `NavItem` 对象应该有一个 text 字段和一个 link 字段，还有一个可选的 `activeMatch` 字段。
|
||
- `string` 表示是一个页面文件路径，或者是一个页面的访问路径。
|
||
|
||
``` ts
|
||
type NavItem = string | {
|
||
text: string
|
||
link: string
|
||
|
||
/**
|
||
* 当前分组的页面前缀
|
||
*/
|
||
prefix?: string
|
||
/**
|
||
* 该分组下的导航项
|
||
*/
|
||
items?: NavItem[]
|
||
/**
|
||
* 支持 iconify 图标，直接使用 iconify name 即可自动加载
|
||
*
|
||
* @see https://icon-sets.iconify.design/
|
||
*/
|
||
icon: string
|
||
/**
|
||
* 控制元素何时被激活
|
||
*/
|
||
activeMatch?: string
|
||
}
|
||
```
|
||
|
||
- 示例1：
|
||
|
||
``` js
|
||
export default {
|
||
theme: plumeTheme({
|
||
navbar: [
|
||
// NavbarItem
|
||
{ text: 'Foo', link: '/foo/' },
|
||
// NavbarGroup
|
||
{
|
||
text: 'Group',
|
||
prefix: '/group/',
|
||
item: ['foo/', 'bar/'],
|
||
},
|
||
// 字符串 - 页面文件路径
|
||
'/bar', // 可以直接省略后缀 `.md`
|
||
],
|
||
}),
|
||
}
|
||
```
|
||
|
||
- 示例2：
|
||
|
||
``` js
|
||
export default {
|
||
theme: plumeTheme({
|
||
navbar: [
|
||
// 嵌套 Group - 最大深度为 2
|
||
{
|
||
text: 'Group',
|
||
items: [
|
||
{
|
||
text: 'SubGroup',
|
||
items: ['/group/sub/', '/group/sub/bar/'],
|
||
},
|
||
],
|
||
},
|
||
// 控制元素何时被激活
|
||
{
|
||
text: 'Group 2',
|
||
items: [
|
||
{
|
||
text: 'Always active',
|
||
link: '/',
|
||
// 该元素将一直处于激活状态
|
||
activeMatch: '/',
|
||
},
|
||
{
|
||
text: 'Active on /foo/',
|
||
link: '/not-foo/',
|
||
// 该元素在当前路由路径是 /foo/ 开头时激活
|
||
// 支持正则表达式
|
||
activeMatch: '^/foo/',
|
||
},
|
||
],
|
||
},
|
||
],
|
||
}),
|
||
}
|
||
```
|
||
|
||
### footer
|
||
|
||
- 类型： `false | { message: string; copyright: string }`
|
||
- 默认值： `false`
|
||
- 详情：页脚配置。
|
||
|
||
### notes
|
||
|
||
- 类型： `false | PlumeThemeNotesOptions`
|
||
- 默认值： `{ link: '/note', dir: 'notes', notes: [] }`
|
||
- 详情：
|
||
|
||
笔记配置， 笔记中的文章默认不会出现在首页文章列表
|
||
|
||
你可以将配置的notes 配置到 navbar中，以便浏览查看
|
||
|
||
详细配置请查看 [此文档](/config/notes/)
|
||
|
||
### aside
|
||
|
||
- 类型： `boolean | 'left'`
|
||
- 默认值： `true`
|
||
- 详情：
|
||
|
||
是否显示侧边栏
|
||
|
||
- `false` 表示禁用 右侧边栏
|
||
- `true` 表示启用 右侧边栏
|
||
- `'left` 表示将有侧边栏移动到文章内容左侧，sidebar 右侧
|
||
|
||
每个页面可以通过 [frontmatter aside](./frontmatter/basic.md#aside) 覆盖层级配置。
|
||
|
||
### outline
|
||
|
||
- 类型： `false | number | [number, number] | 'deep'`
|
||
- 默认值： `[2, 3]`
|
||
- 详情：
|
||
|
||
要显示的标题级别。
|
||
|
||
单个数字表示只显示该级别的标题。
|
||
|
||
如果传递的是一个元组，第一个数字是最小级别，第二个数字是最大级别。
|
||
|
||
`'deep'` 与 `[2, 6]` 相同，将显示从 `<h2>` 到 `<h6>` 的所有标题。
|
||
|
||
当 [aside](#aside) 被禁用时，`outline` 也会被禁用
|
||
|
||
每个页面可以通过 [frontmatter outline](./frontmatter/basic.md#outline) 覆盖层级配置。
|
||
|
||
### transition
|
||
|
||
- 类型： `boolean | ThemeTransition`
|
||
- 默认值： `true`
|
||
- 详情：
|
||
|
||
是否启用过渡动画。
|
||
|
||
传入 `boolean` 类型时，`true` 代表启用，`false` 代表禁用。
|
||
|
||
也可以传入一个对象，具体配置见下
|
||
|
||
```ts
|
||
interface ThemeTransition {
|
||
/**
|
||
* 是否启用 页面间跳转过渡动画
|
||
* @default true
|
||
*/
|
||
page?: boolean
|
||
/**
|
||
* 是否启用 博客文章列表过渡动画
|
||
* @default true
|
||
*/
|
||
postList?: boolean
|
||
/**
|
||
* 是否启用 深色/浅色 模式切换过渡动画
|
||
* @default true
|
||
*/
|
||
appearance?: boolean
|
||
}
|
||
```
|
||
|
||
### selectLanguageName
|
||
|
||
- 类型： `string`
|
||
- 默认值： `''`
|
||
- 详情：
|
||
|
||
Locale 的语言名称。
|
||
|
||
该配置项 **仅能在主题配置的 [locales](#locales) 的内部生效** 。它将被用作 locale 的语言名称，展示在 _选择语言菜单_ 内。
|
||
|
||
### selectLanguageText
|
||
|
||
- 类型： `string`
|
||
- 默认值： `''`
|
||
- 详情：
|
||
|
||
_选择语言菜单_ 的文本。
|
||
|
||
如果你在站点配置中设置了多个 [locales](#locales) ，那么 _选择语言菜单_ 就会显示在导航栏中仓库按钮的旁边。
|
||
|
||
### selectLanguageAriaLabel
|
||
|
||
- 类型： `string`
|
||
- 默认值： `''`
|
||
- 详情：
|
||
|
||
_选择语言菜单 的 `aria-label` 属性。_
|
||
|
||
它主要是为了站点的可访问性 (a11y) 。
|
||
|
||
### sidebarMenuLabel
|
||
|
||
- 类型： `string`
|
||
- 默认值： `'Menu'`
|
||
- 详情：
|
||
|
||
移动设备下的导航栏中 菜单选项的文本。
|
||
|
||
### returnToTopLabel
|
||
|
||
- 类型： `string`
|
||
- 默认值： `'return to top'`
|
||
- 详情：
|
||
|
||
移动设备下的导航栏中返回顶部的文本。
|
||
|
||
### outlineLabel
|
||
|
||
- 类型： `string`
|
||
- 默认值： `'On this page'`
|
||
- 详情：
|
||
|
||
移动设备下的导航栏中大纲标题的文本
|
||
|
||
### editLink
|
||
|
||
- 类型： `boolean`
|
||
- 默认值： `true`
|
||
- 详情： 是否启用 编辑链接
|
||
|
||
### editLinkText
|
||
|
||
- 类型： `string`
|
||
- 默认值： `'Edit this page'`
|
||
- 详情： 编辑链接文本
|
||
|
||
### editLinkPattern
|
||
|
||
- 类型： `string`
|
||
- 默认值： `''`
|
||
- 详情： 编辑链接的正则表达式
|
||
|
||
示例： `':repo/edit/:branch/:path'`
|
||
|
||
### docsRepo
|
||
|
||
- 类型： `string`
|
||
- 默认值： `''`
|
||
- 详情： 文档仓库配置, 用于生成 `Edit this page` 链接。
|
||
|
||
### docsBranch
|
||
|
||
- 类型： `string`
|
||
- 默认值： `''`
|
||
- 详情： 文档仓库分支配置，用于生成 `Edit this page` 链接。
|
||
|
||
### docsDir
|
||
|
||
- 类型： `string`
|
||
- 默认值： `''`
|
||
- 详情： 文档仓库目录配置，用于生成 `Edit this page` 链接。
|
||
|
||
### lastUpdated
|
||
|
||
- 类型： `false | LastUpdatedOptions`
|
||
- 默认值： `{ text: 'Last Updated', formatOptions: { dateStyle: 'short', timeStyle: 'short' } }`
|
||
- 详情： 最后更新时间
|
||
|
||
```ts
|
||
interface LastUpdatedOptions {
|
||
/**
|
||
* 设置 最后更新时间 的文本
|
||
*
|
||
* @default 'Last updated'
|
||
*/
|
||
text?: string
|
||
|
||
/**
|
||
* 设置最后更新时间格式的选项。
|
||
* @see https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/Intl/DateTimeFormat#using_options
|
||
*
|
||
* @default
|
||
* { dateStyle: 'short', timeStyle: 'short' }
|
||
*/
|
||
formatOptions?: Intl.DateTimeFormatOptions & { forceLocale?: boolean }
|
||
}
|
||
```
|
||
|
||
### contributors
|
||
|
||
- 类型： `boolean`
|
||
- 默认值： `true`
|
||
- 详情： 是否显示贡献者
|
||
|
||
### contributorsText
|
||
|
||
- 类型： `string`
|
||
- 默认值： `'Contributors'`
|
||
- 详情： 贡献者的文本
|
||
|
||
### prevPageLabel
|
||
|
||
- 类型： `string`
|
||
- 默认值： `'Previous Page'`
|
||
- 详情： 上一页的文本
|
||
|
||
### nextPageLabel
|
||
|
||
- 类型： `string`
|
||
- 默认值： `'Next Page'`
|
||
- 详情： 下一页的文本
|
||
|
||
### notFound
|
||
|
||
- 类型： `NotFound | undefined`
|
||
- 默认值： `undefined`
|
||
- 详情： 404 页面配置
|
||
|
||
```ts
|
||
interface NotFound {
|
||
code?: string
|
||
title?: string
|
||
quote?: string
|
||
linkLabel?: string
|
||
linkText?: string
|
||
}
|
||
```
|