约 1930 字大约 6 分钟

2022-04-09

当前主题已支持 零配置 的开箱即用。

但依然支持丰富配置项,保证了一定程度的可定制性。

配置文件

Vuepress 默认的配置文件是.vuepress/config.ts,可能你的项目配置如下,

新建.vuepress/config.ts文件进行配置:

├─ {sourceDir}
│  ├─ .vuepress
│  │  └─ config.ts
│  └─ README.md
├─ .gitignore
└─ package.json

VuePress 支持的配置,请查阅 官方文档

Vuepress@v2中对于主题的配置,引入主题函数,在函数中进行配置

ts
// .vuepress/config.ts
import { defineUserConfig } from 'vuepress'
import { themePlume } from 'vuepress-theme-plume'
export default defineUserConfig({
  base: '/',
  // 推荐声明您的站点所使用的语言编码,如: `zh-CN` `en-US`
  lang: 'zh-CN', 
  theme: themePlume({
    home: '/',  
    // more options...
  })
})

基础配置

plugins

  • 类型:PlumeThemePluginOptions
  • 默认值: {}
  • 详情: 对主题内部使用的插件进行自定义配置。

主题使用的插件默认已进行了配置,大多数情况下您不需要进行任何修改,如果需要使用到细致的定制化,请查阅 此文档

locales

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

多语言配置,参考 此文档

多语言配置支持以下 Locale 所有配置选项

Locale 配置

home

  • 类型: false | string
  • 默认值: /
  • 详情: 首页的路径, 它将被用于:
    • 导航栏中 logo的链接;
    • 404页面的 返回首页 的链接;
  • 类型: 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'
  • 详情: 导航栏中的主题切换按钮的文本。

hostname

  • 类型: string

  • 默认值: ''

  • 详情:

    部署站点域名。

    hostname 配置为有效域名时,主题将会生成 sitemapseo 相关的内容。

avatar

  • 类型: PlumeThemeAvatar
  • 默认值: {}
  • 详情:配置站点博主的个人信息
    • avatar.url: 头像地址,用于右侧博主信息展示
    • avatar.name: 名称, 用于右侧博主信息展示
    • avatar.description: 个人描述,用于右侧博主信息展示
    • avatar.circle: 是否为圆形头像
  • 示例:
    export default {
      theme: themePlume({
        avatar: {
          url: '/avatar.jpg',
          name: '张三',
          description: '此处无银三百两,隔壁王二不曾偷',
          circle: true
        }
      })
    }

social

  • 类型: false | SocialLink[]

  • 默认值: false

  • 详情: 个人社交信息配置。

    将作为 图标链接 展示在 导航栏最右侧。

    图标可选值:'discord' | 'facebook' | 'github' | 'instagram' | 'linkedin' | 'mastodon' | 'npm' | 'slack' | 'twitter' | 'x' | 'youtube' | 'qq' | 'weibo' | 'bilibili' | { svg: string }

  • 示例:

    export default {
      theme: themePlume({
        social: [{
          icon: 'github',
          link: 'https://github.com/zhangsan',
        }]
      })
    }

blog

  • 类型: false | BlogOptions

  • 默认值: { link: '/blog/', include: ['**/*.md'], exclude: [] }

  • 详情:

    博客配置。

interface BlogOptions {
    /**
     * blog list link
     *
     * @default '/blog/'
     */
    link?: string

    /**
     * 在 `blog.dir` 目录中,通过 glob string 配置包含文件
     *
     * @default - ['**\*.md']
     */
    include?: string[]

    /**
     * 在 `blog.dir` 目录中,通过 glob string 配置排除的文件
     *
     * README.md 文件一般作为主页或者某个目录下的主页,不应该被读取为 blog文章
     *
     * @default - ['.vuepress/', 'node_modules/', '{README,index}.md']
     */
    exclude?: string[]

    /**
     * 分页配置
     */
    pagination?: false | {
      /**
       * 每页显示的文章数量
       * @default 10
       */
      perPage?: number
      /**
       * 前一页的文本
       * @default 'Prev'
       */
      prevPageText?: string
      /**
       * 后一页的文本
       * @default 'Next'
       */
      nextPageText?: string
    }

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

article

  • 类型: string
  • 默认值: /article/
  • 详情: 文章链接前缀
  • 类型: NavItem[]

  • 默认值: []

  • 详情: 导航栏配置。

    为了配置导航栏元素,你可以将其设置为 导航栏数组 ,其中的每个元素是 NavItem 对象、

    • NavItem 对象应该有一个 text 字段和一个 link 字段,还有一个可选的 activeMatch 字段。
type NavItem = string | {
  text: string
  link: string
  items?: NavItem[]
  /**
   * 支持 iconify 图标,直接使用 iconify name 即可自动加载
   * 
   * @see https://icon-sets.iconify.design/
   */
  icon: string
  /**
   * 控制元素何时被激活
   */
  activeMatch?: string
}
  • 示例1:
    module.exports = {
      theme: plumeTheme({
        navbar: [
          // NavbarItem
          { text: 'Foo', link: '/foo/' },
          // NavbarGroup
          {
            text: 'Group',
            item: ['/group/foo/', '/group/bar/'],
          },
          // 字符串 - 页面文件路径
          '/bar/',
        ],
      }),
    }
  • 示例2:
    module.exports = {
      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/',
              },
            ],
          },
        ],
      }),
    }
  • 类型: false | { message: string; copyright: string }
  • 默认值: false
  • 详情:页脚配置。

notes

  • 类型: false | PlumeThemeNotesOptions

  • 默认值: { link: '/note', dir: 'notes', notes: [] }

  • 详情: 笔记配置, 笔记中的文章默认不会出现在首页文章列表

    你可以将配置的notes 配置到 navbar中,以便浏览查看

详细配置请查看 此文档

selectLanguageName

  • 类型: string

  • 默认值: ''

  • 详情:

    Locale 的语言名称。

    该配置项 仅能在主题配置的 locales 的内部生效 。它将被用作 locale 的语言名称,展示在 选择语言菜单 内。

selectLanguageText

  • 类型: string

  • 默认值: ''

  • 详情:

    选择语言菜单 的文字。

    如果你在站点配置中设置了多个 locales ,那么 选择语言菜单 就会显示在导航栏中仓库按钮的旁边。

selectLanguageAriaLabel

  • 类型: string

  • 默认值: ''

  • 详情:

    选择语言菜单 的 aria-label 属性。

    它主要是为了站点的可访问性 (a11y) 。

sidebarMenuLabel

  • 类型: string

  • 默认值: 'Menu'

  • 详情:

    移动设备下的导航栏中 菜单选项的文字。

returnToTopLabel

  • 类型: string

  • 默认值: 'return to top'

  • 详情:

    移动设备下的导航栏中返回顶部的文字。

outlineLabel

  • 类型: string

  • 默认值: 'On this page'

  • 详情:

    移动设备下的导航栏中大纲标题的文字

repo

  • 类型: string
  • 默认值: ''
  • 详情: 仓库配置
  • 类型: boolean
  • 默认值: true
  • 详情: 是否启用 编辑链接

editLinkText

  • 类型: string
  • 默认值: 'Edit this page'
  • 详情: 编辑链接文字

editLinkPattern

  • 类型: string

  • 默认值: ''

  • 详情: 编辑链接的正则表达式

    示例: ':repo/edit/:branch/:path'

docsRepo

  • 类型: string
  • 默认值: ''
  • 详情: 文档仓库配置, 用于生成 Edit this page 链接,如果为空,默认使用 repo 配置的值

docsBranch

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

docsDir

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

lastUpdated

  • 类型: boolean
  • 默认值: true
  • 详情: 是否显示最后更新时间

lastUpdatedText

  • 类型: string
  • 默认值: 'Last Updated'
  • 详情: 最后更新时间的文字

contributors

  • 类型: boolean
  • 默认值: true
  • 详情: 是否显示贡献者

contributorsText

  • 类型: string
  • 默认值: 'Contributors'
  • 详情: 贡献者的文字

prevPageLabel

  • 类型: string
  • 默认值: 'Previous Page'
  • 详情: 上一页的文字

nextPageLabel

  • 类型: string
  • 默认值: 'Next Page'
  • 详情: 下一页的文字

notFound

  • 类型: NotFound | undefined
  • 默认值: undefined
  • 详情: 404 页面配置
interface NotFound {
  code?: string
  title?: string
  quote?: string
  linkLabel?: string
  linkText?: string
  }