主题配置

2024-03-02

基础配置

configFile

类型： string
默认值： ''
详情：
自定义主题配置文件的路径。
查看主题配置文件 plume.config.js 了解更多。

plugins

类型：PlumeThemePluginOptions
默认值： {}
详情：
对主题内部使用的插件进行自定义配置。
主题使用的插件默认已进行了配置，大多数情况下您不需要进行修改，如果需要使用到细致的定制化，请查阅此文档
该字段不支持在主题配置文件 plume.config.js 中进行配置。

hostname

类型： string
默认值： ''
详情：
部署站点域名。
当 hostname 配置为有效域名时，主题将会生成 sitemap 和 seo 相关的内容。
该字段不支持在主题配置文件 plume.config.js 中进行配置。

blog

类型： false | BlogOptions
默认值： { link: '/blog/', include: ['**/*.md'], exclude: [] }
详情：
博客配置。
该字段不支持在主题配置文件 plume.config.js 中进行配置。

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[]

  /**
   * 分页配置
   *
   * - `false` - 不启用分页
   * - `number` - 每页显示的文章数量
   */
  pagination?: false | number | {
    /**
     * 每页显示的文章数量
     * @default 10
     */
    perPage?: number
  }

  /**
   * 是否启用标签页
   * @default true
   */
  tags?: boolean

  /**
   * 自定义标签页链接
   *
   * @default '/blog/tags/'
   */
  tagsLink?: string

  /**
   * 标签颜色主题
   *
   * - `colored`： 彩色标签，不同标签颜色不同
   * - `brand`: 使用主题颜色作为标签颜色
   * - `gray`: 使用 灰色 作为标签颜色
   *
   * @default 'colored'
   */
  tagsTheme?: 'colored' | 'gray' | 'brand'

  /**
   * 是否启用归档页
   * @default true
   */
  archives?: boolean

  /**
   * 自定义归档页链接
   *
   * @default '/blog/archives/'
   */
  archivesLink?: string

  /**
   * 是否启用分类页
   * @default true
   */
  categories?: boolean

  /**
   * 自定义分类页链接
   *
   * @default '/blog/categories/'
   */
  categoriesLink?: string

  /**
   * 分类页展开深度
   *
   * @default 'deep'
   */
  categoriesExpand?: number | 'deep'

  /**
   * 文章分类列表转换函数，比如排除不需要的一级分类
   * @param categories 分类列表
   * @returns 返回一个新的分类列表
   */
  categoriesTransform?: (categories: PageCategoryData[]) => PageCategoryData[]

  /**
   * 博客文章封面图
   *
   * 配置封面图的位置，支持 `'left'`、`'right'`、`'top'`、`'top-inside'`
   *
   * @default 'right'
   */
  postCover?: BlogPostCoverLayout | Omit<BlogPostCover, 'url'>
}

type BlogPostCoverLayout = 'left' | 'right' | 'odd-left' | 'odd-right' | 'top'

interface BlogPostCover {
  /**
   * 封面图链接地址，只能使用 绝对路径 以及 远程图片地址
   */
  url: string
  /**
   * 博客文章封面图的位置
   */
  layout?: BlogPostCoverLayout
  /**
   * 博客文章封面图的比例
   *
   * @default '4:3'
   */
  ratio?: number | `${number}:${number}`

  /**
   * 封面图的宽度, 仅在 layout 为 'left' 或 'right' 时生效
   *
   * @default 240
   */
  width?: number
  /**
   * 是否使用紧凑模式，紧凑模式下，封面图紧贴容器边缘
   * @default false
   */
  compact?: boolean
}

article

类型： string
默认值： /article/
详情：文章链接前缀
该字段不支持在主题配置文件 plume.config.js 中进行配置。

autoFrontmatter

类型： false | AutoFrontmatterOptions

详情：

是否为 markdown 文件自动添加 frontmatter 配置

interface AutoFrontmatterOptions {
  /**
   * glob 匹配，被匹配的文件将会自动生成 frontmatter
   *
   * @default ['**\/*.md']
   */
  include?: string | string[]

  /**
   * glob 匹配，被匹配的文件将不会自动生成 frontmatter
   */
  exclude?: string | string[]

  /**
   * 是否自动生成 permalink
   *
   * @default true
   */
  permalink?: boolean

  /**
   * 是否自动生成 createTime
   *
   * 默认读取 文件创建时间，`createTitme` 比 vuepress 默认的 `date` 时间更精准到秒
   */
  createTime?: boolean

  /**
   * 是否自动生成 title
   *
   * 默认读取文件名作为标题
   */
  title?: boolean
}

cache

类型： false | 'memory' | 'filesystem'
默认值： filesystem
详情：
是否启用编译缓存，或配置缓存方式
此配置项用于解决 VuePress 启动速度慢的问题，在首次启动服务时，对编译结果进行缓存，二次启动时直接读取缓存，跳过编译，从而加快启动速度。
- false：禁用缓存
- 'memory'：使用内存缓存，此方式可获得更快的启动速度，但随着项目文件数量增加，内存占用会增加，适合文章数量较少的项目使用
- 'filesystem'：使用文件系统缓存，此方式可获得相对快且稳定的启动速度，更适合内容多的项目使用
Warning
该字段不支持在主题配置文件 plume.config.js 中进行配置。
为了使缓存能够生效，您应该删除 package.json 中 vuepress dev 开发服务启动脚本中的 --clean-cache 参数。

docsRepo

类型： string
默认值： ''
详情：文档仓库配置, 用于生成 Edit this page 链接。

docsBranch

类型： string
默认值： ''
详情：文档仓库分支配置，用于生成 Edit this page 链接。

docsDir

类型： string
默认值： ''
详情：文档仓库目录配置，用于生成 Edit this page 链接。

editLink

类型： boolean
默认值： true
详情：是否启用编辑链接
该字段不支持在主题配置文件 plume.config.js 中进行配置。

lastUpdated

类型： false | LastUpdatedOptions
默认值： { formatOptions: { dateStyle: 'short', timeStyle: 'short' } }
详情：最后更新时间

interface LastUpdatedOptions {

  /**
   * 设置最后更新时间格式的选项。
   * @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 }
}

该字段不支持在主题配置文件 plume.config.js 中进行配置。

contributors

类型： boolean | ContributorsOptions
默认值： true
详情：是否显示贡献者
更多配置请参考此文档
该字段不支持在主题配置文件 plume.config.js 中进行配置。

changelog

类型： boolean | ChangelogOptions
默认值： false
详情：是否显示页面变更历史
更多配置请参考此文档
该字段不支持在主题配置文件 plume.config.js 中进行配置。

locales

类型： Record<string, PlumeThemeLocaleConfig>
默认值： {}
详情：多语言配置

不同语言的文本配置，参考此文档

多语言配置支持以下 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，则用户将无法切换主题，但会强制将主题更改为深色。

此选项注入一个内联脚本，从本地存储恢复用户设置。这确保在呈现页面之前应用 [data-theme="dark"] 以避免闪烁。

profile

类型： ProfileOptions
默认值： {}
详情：配置站点博主的个人信息
- profile.avatar: 头像地址，用于右侧博主信息展示
- profile.name: 名称，用于右侧博主信息展示
- profile.description: 个人描述，用于右侧博主信息展示
- profile.circle: 是否为圆形头像
- profile.location: 用户地理位置
- profile.organization: 用户所在组织/公司
- profile.layout: 个人信息展示在左侧还是右侧，'left' | 'right'

示例：

export default {
  theme: plumeTheme({
    profile: {
      avatar: '/avatar.jpg',
      name: '张三',
      description: '此处无银三百两，隔壁王二不曾偷',
      circle: true,
      location: '杭州，中国',
      organization: 'xxx公司',
      layout: 'right',
    }
  })
}

类型： 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, name?: string }: 自定义图标，传入 svg 源码字符串，可选 name 字段，用于配置 navbarSocialInclude

示例：

export default {
  theme: plumeTheme({
    social: [
      { icon: 'github', link: 'https://github.com/zhangsan' },
      {
        icon: { svg: '<svg>xxxxx</svg>', name: 'xxx' },
        link: 'https://xxx.com'
      },
    ]
  })
}

navbarSocialInclude

类型： string[]
默认值： ['github', 'twitter', 'discord', 'facebook']
详情：
允许显示在导航栏的社交链接。该配置仅在 PC 端下有效。
如果 social 配置为 { svg: string, name: string} 则可将 name 作为 navbarSocialInclude 的值。

类型： NavItem[]
默认值： []
详情：导航栏配置。
为了配置导航栏元素，你可以将其设置为导航栏数组，其中的每个元素是 string 或 NavItem 对象、
- NavItem 对象应该有一个 text 字段和一个 link 字段，还有一个可选的 activeMatch 字段。
- string 表示是一个页面文件路径，或者是一个页面的访问路径。

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：

export default {
  theme: plumeTheme({
    navbar: [
      // NavbarItem
      { text: 'Foo', link: '/foo/' },
      // NavbarGroup
      {
        text: 'Group',
        prefix: '/group/',
        item: ['foo/', 'bar/'],
      },
      // 字符串 - 页面文件路径
      '/bar', // 可以直接省略后缀 `.md`
    ],
  }),
}

示例2：

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

notes

类型： false | NotesOptions
默认值： { link: '/note', dir: 'notes', notes: [] }
详情：
笔记配置，笔记中的文章默认不会出现在首页文章列表
你可以将配置的notes 配置到 navbar中，以便浏览查看

详细配置请查看此文档

类型： false | SidebarMulti
详情：
侧边栏配置。主题更推荐在 notes 配置中进行侧边栏配置。
当你不希望使用 notes 功能，但又期望给文档增加侧边栏时，可以使用此配置。
配置对象的 key 为侧边栏公共访问路径前缀。
对于 value:
- 'auto' 表示自动根据目录结构生成侧边栏
- string 表示侧边栏对应的页面文件路径
- SidebarItem 表示侧边栏单项配置

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
}

sidebarScrollbar

类型： boolean
默认值： true
详情：是否显示侧边栏滚动条
设置为 false 时，仅隐藏滚动条，但不改变滚动行为。

aside

类型： boolean | 'left'
默认值： true
详情：
是否显示侧边栏
- false 表示禁用右侧边栏
- true 表示启用右侧边栏
- 'left 表示将有侧边栏移动到文章内容左侧，sidebar 右侧
每个页面可以通过 frontmatter aside 覆盖层级配置。

outline

类型： false | number | [number, number] | 'deep'
默认值： [2, 3]
详情：
要显示的标题级别。
单个数字表示只显示该级别的标题。
如果传递的是一个元组，第一个数字是最小级别，第二个数字是最大级别。
'deep' 与 [2, 6] 相同，将显示从 <h2> 到 <h6> 的所有标题。
当 aside 被禁用时，outline 也会被禁用
每个页面可以通过 frontmatter outline 覆盖层级配置。

transition

类型： boolean | TransitionOptions
默认值： true

详情：

是否启用过渡动画。

传入 boolean 类型时，true 代表启用，false 代表禁用。

也可以传入一个对象，具体配置见下

interface TransitionOptions {
  /**
   * 是否启用 页面间跳转过渡动画
   * @default true
   */
  page?: boolean
  /**
   * 是否启用 博客文章列表过渡动画
   * @default true
   */
  postList?: boolean
  /**
   * 是否启用 深色/浅色 模式切换过渡动画，
   * 或配置过渡动画类型
   * @default 'fade'
   */
  appearance?: boolean | 'fade' | 'circle-clip' | 'horizontal-clip' | 'vertical-clip' | 'skew-clip'
}

类型： false | { message: string; copyright: string }
默认值： false
详情：页脚配置。

bulletin

类型： boolean | BulletinOptions
默认值： false
详情：公告板配置
详情请参考公告板

editLinkPattern

类型： string
默认值： ''
详情：编辑链接的正则表达式
示例： ':repo/edit/:branch/:path'

copyright

类型： boolean | CopyrightLicense | CopyrightOptions
默认值： false

类型： boolean
默认值： true
详情：是否显示上一页

类型： boolean
默认值： true
详情：是否显示下一页

createTime

类型： boolean | 'only-blog'
默认值： true
详情：是否显示创建时间
- false - 不显示
- 'only-blog' - 只显示在博客文章页面
- true - 显示在所有文章页面