vuepress2.0使用教程（4）- 搭建一个vuepress支撑的网站 -详细配置默认模板

       百家饭团队开发的百家饭OpenAPI平台是用vuepress2.0搭建的，搭建的时候不知道2.0还处在beta状态，所以导致后来踩了一些坑，使用过程中vuepress2.0也从2.0.0-beta.18升到了2.0.0-beta.48，有很多的变化，所以想写一个教程介绍一下vuepress2.0的情况以及使用经验。

大致计划写这些内容吧：

1. vuepress介绍、选型原因及使用感受（先介绍一下自己用的情况吧）
2. vuepress2.0使用（搭建一个vuepress支撑的网站）-第一部分
3. vuepress2.0使用（搭建一个vuepress支撑的网站）-修改默认模板配置
4. vuepress2.0使用（搭建一个vuepress支撑的网站）-详细配置默认模板
5. vuepress2.0使用（搭建一个vuepress支撑的网站）-md文件的玩法
6. vuepress2.0使用（扩展默认主题）- 准备及扩展页面组件
7. vuepress2.0使用（扩展默认主题）- 提供更多页面模板并引入ElementUI
8. vuepress2.0使用（扩展默认主题）- 扩展MD页面功能（Section扩展及自定义语法）
9. vuepress2.0使用（扩展默认主题）- 引入百度搜索支持及其他库的引用
10. 编写vuepress主题（自定义自己的框架，开发复杂程序）
11. vuepress2.0使用——编译及站点部署
12. vuepress2.0当前的状态（版本变化，方便大家升级，占位中，未书写）
13. 更多读者发起话题点击这里进专题查看，就不更新标题了

这里先给搜索进来的同学提个醒：凡是网上搜索到需要修改clientAppEnhance.js 文件的教程都已经过时，最新版本已不再使用。另外说个题外话，我查了下，我为数不多的搜索关键词里面，vuepress的占了大部分，这里感谢大家的关注，这个教程肯定有不合理的地方，如果有任何需要帮助的，大家都可以留言，我尽力解答。

上周我们完成了一个基础的，基于vuepress搭建的博客网站的搭建，这种我们继续为希望深入使用vuepress 2.0的同学进行默认模板的进一步配置和自定义，以满足更丰富的网站搭建需求。大概用一篇详细配置介绍，一篇md文件高级用法，和一篇扩展默认模板来讲解这一部分内容。

基础配置

colorModeSwitch

显示模式设置，近两年随处可见的夜间模式开启/关闭功能，就是首页右边的小太阳图标，一键切换到夜间模式

colorMode 

自定义显示模式，当colorModeSwitch设置为false时生效（beta-0.49版本测试），可设置为”light"或“dark”

logo

设置后在顶部菜单显示logo图片，支持文件名称或者url

 logoDark

可为深色模式设置单独的logo地址

home

自定义主页地址，用于顶部菜单配置的logo的点击效果和404页面的返回主页效果。

repo

版本仓库地址，就是大家经常在开源软件介绍站点看见的那个Github按钮，如果你设置的是类似“extrame/baijiafan”这种/风格的两段字符串，会被默认按github渲染，显示效果如下：

如果是个完整链接，就显示成这样：

repoLabel

上一项配置中显示的Source字样可以通过这个配置项修改，例如配置为“源代码仓库”则显示为

tip和warning

两个容器（tip和warning）的标题，

容易是指在文章md文件中可以使用的一些特殊的样式模板，vuepress将其定义为一个“容器”，可以使用这些容器进行特殊样式渲染，例如这个warning样式，就显示如下，下一篇md的扩展用法，我们详细介绍这块的内容 

notFound和backToHome

两个和4404等功能页面相关的配置，如下图

改配置为

        notFound:["你搞错了吧"],
        backToHome:"去主页看看吧",

 显示如下：

 注意，notFound为字符串数组，用于当你想显示多种提示语言的时候，随机选择一种显示。

国际化配置

上述配置既可以作为基础配置，还可以作为一个语言项配置，例如配置中文和英文两种。这种配置方法需要配合站点的locales才能生效，也就是如下配置方法：

module.exports = {
    locales: {
        // 键名是该语言所属的子路径
        // 作为特例，默认语言可以使用 '/' 作为其路径。
        '/': {
            lang: 'en-US',
            title: 'VuePress',
            description: 'Vue-powered Static Site Generator',
        },
        '/zh/': {
            lang: 'zh-CN',
            title: 'VuePress',
            description: 'Vue 驱动的静态网站生成器',
        },
    },
    theme: defaultTheme({
        // 默认主题配置
        locales: {
            "en-US": {
                navbar: [
                    {
                        text: 'HOME',
                        link: '/',
                    },
                ],
                colorModeSwitch: true,
                colorMode: "dark",
                logo: "http://rongapi.cn/images/logo.png",
                repo: 'http://gitee.org/vuejs/vuepress',
                repoLabel: "Source",
            }
        },
        navbar: [
            {
                text: '首页',
                link: '/',
            },
        ],
        selectLanguageText: "I18N",

上面的示例中，有两个locales，一个在exports对象的顶层，官方定义是站点的locales配置，而在theme里面的locales是默认模板的locales配置，顶层那个配置的是全局的国际化选项，例如站点名称，语言名称（用于显示或配合模板的selectLanguageName选项，详见下方），介绍，配置站点内容的结构，可以实现国际化文档覆盖

docs
├─ README.md
├─ foo.md
├─ nested
│  └─ README.md
└─ zh
   ├─ README.md
   ├─ foo.md
   └─ nested
      └─ README.md

 主题相关国际化配置

selectLanguageText

选择语言的显示文字，字符串，我配置的I18N,显示效果如下：

selectLanguageName

为站点的locales里的每一种语言配置对应的显示文字，map形式，和站点locales一一对应，例如

      '/': {
        selectLanguageName: 'English',
      },
      '/zh/': {
        selectLanguageName: '简体中文',
      },

Navbar和Sidebar

顶部菜单配置和侧面菜单配置上一篇文章介绍过了，大家可以翻看上一篇，其他相关配置还有：

sidebarDepth

侧面菜单的显示深度，仅当sidebar为auto时有效，用于设定渲染的文章目录深度。

版本仓库配合设置

vuepress还可以设置若干选项用于和github等版本仓库配合，提供“编辑本文”等功能，下述内容摘抄自官方中文网站：

editLink

• 类型： boolean

• 默认值： true

• 详情：

  是否启用 编辑此页 链接。

  你可以通过页面的 editLink frontmatter 来覆盖这个全局配置。

#editLinkText

• 类型： string

• 默认值： 'Edit this page'

• 详情：

  编辑此页 链接的文字。

#editLinkPattern

• 类型： string

• 详情：

  编辑此页 链接的 Pattern 。

  它将会用于生成 编辑此页 的链接。

  如果你不设置该选项，则会根据 docsRepo 配置项来推断 Pattern 。但是如果你的文档仓库没有托管在常用的平台上，比如 GitHub 、 GitLab 、 Bitbucket 、 Gitee 等，那么你必须设置该选项才能使 编辑此页 链接正常工作。

• 用法：

  Pattern	描述
  :repo	文档仓库 URL ，即 docsRepo
  :branch	文档仓库分支 ，即 docsBranch
  :path	页面源文件的路径，即 docsDir 拼接上页面文件的相对路径

• 示例：

module.exports = {
  theme: defaultTheme({
    docsRepo: 'https://gitlab.com/owner/name',
    docsBranch: 'master',
    docsDir: 'docs',
    editLinkPattern: ':repo/-/edit/:branch/:path',
  }),
}

则会生成类似于 'https://gitlab.com/owner/name/-/edit/master/docs/path/to/file.md' 的链接。

#docsRepo

• 类型： string

• 详情：

  文档源文件的仓库 URL 。

  它将会用于生成 编辑此页 的链接。

  如果你不设置该选项，则默认会使用 repo 配置项。但是如果你的文档源文件是在一个不同的仓库内，你就需要设置该配置项了。

#docsBranch

• 类型： string

• 默认值： 'main'

• 详情：

  文档源文件的仓库分支。

  它将会用于生成 编辑此页 的链接。

#docsDir

• 类型： string

• 默认值： ''

• 详情：

  文档源文件存放在仓库中的目录名。

  它将会用于生成 编辑此页 的链接。

可访问性 (a11y）

a11y，我们要求的比较少，我们提倡为公开网站设计丰富的a11y功能，但是因为我们接触较少，所以大家还是详见官方配置说明吧