配置说明

约 904 字大约 3 分钟

2024-03-02

概述

vuepress-theme-plume 是基于 VuePress 开发的主题，其配置完全遵循 VuePress 的配置规范。

VuePress 提供三种配置类型：

站点配置：在配置文件（如 .vuepress/config.ts）中直接导出的对象
主题配置：传递给 plumeTheme() 函数的参数对象
页面配置：基于 YAML 语法在页面 Frontmatter 中定义

VuePress 配置文件

VuePress 的基础配置文件通常是 .vuepress/config.js，同时也支持 TypeScript 配置文件。使用 .vuepress/config.ts 可以获得更完善的类型提示。

VuePress 按以下优先顺序解析配置文件：

当前工作目录 (cwd) 下：

vuepress.config.ts
vuepress.config.js
vuepress.config.mjs

源文件目录 (sourceDir) 下：

.vuepress/config.ts 推荐使用
.vuepress/config.js
.vuepress/config.mjs

基础配置示例：

.vuepress/config.ts
import { viteBundler
 } from '@vuepress/bundler-vite'
import { defineUserConfig
 } from 'vuepress'
import { plumeTheme
 } from 'vuepress-theme-plume'

export default defineUserConfig
({
  // VuePress 基础配置
  lang
: 'zh-CN',
  title
: '你好， VuePress ！',
  description
: '这是我的第一个 VuePress 站点',
  // ...

  // 使用 Vite 作为构建工具
  bundler
: viteBundler
(),

  // 启用 Plume 主题
  theme
: plumeTheme
({ 
    // 主题配置项
    // ...
  }),
})

主题配置文件

通常我们在 .vuepress/config.ts 中配置主题：

.vuepress/config.ts
import { defineUserConfig
 } from 'vuepress'
import { plumeTheme
 } from 'vuepress-theme-plume'

export default defineUserConfig
({
  theme
: plumeTheme
({
    // 主题配置
  }),
  // ...
})

然而，修改此文件会导致 VuePress 服务重启并全量刷新。对于小型站点，这个过程很快；但对于内容较多的站点，每次重启都需要较长时间。

频繁修改配置文件还容易导致 VuePress 服务崩溃，需要手动重启服务，严重影响内容编写效率。

解决方案：主题热更新配置：

主题提供了 plume.config.ts 配置文件，对该文件的修改支持热更新，无需重启服务。

你可以在其中配置支持热更新的字段，如 navbar、profile 等。

提示

这些字段仍可在 VuePress 配置文件的 theme 中配置，但主题配置文件的设置最终会合并到主配置中。

为避免数据重复，请勿在两地同时配置同一字段。

什么是热更新？

热更新 是一种开发技术，在 VuePress 中体现为：

配置修改实时生效，无需重启服务，浏览器不刷新页面
页面修改实时生效，浏览器无刷新更新内容

配置方法

在 VuePress 配置文件同级目录下创建 plume.config.ts 文件：

docs

.vuepress

config.ts

plume.config.ts

plume.config.ts
import { defineThemeConfig
 } from 'vuepress-theme-plume'
import navbar
 from './navbar'

export default defineThemeConfig
({
  // 主题配置
  profile
: {
    name
: 'Your name',
  },
  navbar
,
})

defineThemeConfig(config) 函数提供完整的类型提示。除 plugins 外，大多数配置都可在此文件中定义。

注意事项

主题配置文件仅支持部分热更新字段
避免在 VuePress 配置文件中重复配置已在主题配置文件中设置的字段

自定义配置文件路径

如需使用非默认路径，可在 VuePress 配置中指定：

.vuepress/config.ts
import path
 from 'node:path'
import { defineUserConfig
 } from 'vuepress'
import { plumeTheme
 } from 'vuepress-theme-plume'

export default defineUserConfig
({
  theme
: plumeTheme
({
    // 自定义配置文件路径
    configFile
: path
.join
(__dirname
, 'custom/config.ts'), 
  }),
})

新手不建议自定义路径，可能引发意外问题

页面配置

通过页面顶部的 YAML Frontmatter，可为每个页面单独配置主题：

article.md
---
title: 文章标题
createTime: 2024/09/08 22:53:34
permalink: /article/xxx/
---

在 Markdown 文件顶部，使用 --- 分隔符包裹的部分即为 Frontmatter，采用 YAML 语法配置。

如需了解 YAML 基础语法，可参考这篇博客

贡献者

pengzhanbo

更新日志

2025/10/7 15:13

查看所有更新日志

4d236-feat(theme)!: add collections support (#704)于 2025/10/7