VuePress学习路程

---

前言

目前主流的静态网站生成器以VuePress、Docusaurus为主。其目的都是帮你构建并优化网站的速度，让你专心于创作内容。
VuePress 是一个基于 Vue 的轻量级静态网站生成器，以及为编写技术文档而优化的默认主题。它是为了满足Vue自己的子项目文档的需求而创建的。VuePress享用Vue + webpack开发环境，在 markdown 中使用 Vue 组件，并通过 Vue 开发自定义主题。VuePress 为每一个由它生成的页面提供预加载的html，不仅加载速度极佳，同时对seo非常友好。一旦页面被加载之后，Vue 就全面接管所有的静态内容，使其变成一个完全的SPA应用，其他的页面也会在用户使用导航进入的时候来按需加载。其特点有以下几点：

1. 简洁至上：以 Markdown 为中心的项目结构，以最少的配置帮助你专注于写作。
2. Vue 驱动：享受Vue + webpack的开发体验，可以在 Markdown 中使用 Vue 组件，又可以使用 Vue 来开发自定义主题。
3. 高性能：VuePress 会为每个页面预渲染生成静态的 HTML，同时，每个页面被加载的时候，将作为SPA运行。

Docusaurus是Facebook专门为开源项目开发者提供的一款易于维护的静态网站创建工具，基于 React 技术构建，使用 Markdown 即可更新网站。构建一个带有主页、文档、API、帮助以及博客页面的静态网站，只需5分钟。具有以下优点：

1. 启动简单
   ：Docusaurus的构建可以在很短的时间内启动和运行。Docusaurus已经构建了处理网站的过程，开发人员只需专注于项目。
2. 本地化： Docusaurus 通过CrowdIn 提供本地化支持。通过翻译文档增强国际社区的地位。
3. 可自定义：Docusaurus 可自定义项目需要的关键页面，包括主页，文档部分，博客和其他页面。
4. 文档版本化：项目文档的所有版本都支持用户查阅。文档 版本化可帮助你使文档与项目版本保持 同步。
5. 内容可搜索：让你的社区成员轻松地在文档中找到他们所需的内容。 我们自豪地支持 Algolia 文档搜索。

一、介绍

VuePress由两部分组成：第一部分是一个极简静态网站生成器，它包含由Vue驱动的主题系统和插件API，另一个部分是为书写技术文档而优化的默认主题，它的诞生初衷是为了支持 Vue 及其子项目的文档需求。
每一个由 VuePress 生成的页面都带有预渲染好的 HTML，也因此具有非常好的加载性能和搜索引擎优化（SEO）。同时，一旦页面被加载，Vue 将接管这些静态内容，并将其转换成一个完整的单页应用（SPA），其他的页面则会只在用户浏览到的时候才按需加载。

1.1、工作原理

事实上，一个 VuePress 网站是一个由 Vue、Vue Router和 webpack驱动的单页应用。如果你以前使用过 Vue 的话，当你在开发一个自定义主题的时候，你会感受到非常熟悉的开发体验，你甚至可以使用 Vue DevTools 去调试你的自定义主题。
在构建时，我们会为应用创建一个服务端渲染（SSR）的版本，然后通过虚拟访问每一条路径来渲染对应的HTML。这种做法的灵感来源于 Nuxt 的 nuxt generate 命令，以及其他的一些项目，比如 Gatsby 。

1.2、特点

1. 内置的Markdown拓展
2. 在 Markdown中使用Vue
3. Vue驱动的自定义主题系统
4. 默认主题
5. 博客主题
6. Plugin

1.3、同类对比

Docusaurus
Docusaurus与VuePress有很多相似之处，都专注于以内容为中心的网站，并且提供开箱即用的文档功能。但是，VuePress时基于 Vue 构建的，而 Docusaurus 是基于React 构建的。如果您想要一个基于 Vue 的解决方案，那么 VuePress 将是一个不错的选择。
Nuxt
VuePress 能做的事情，Nuxt 理论上确实能够胜任，但 Nuxt 是为构建应用程序而生的，而 VuePress 则专注在以内容为中心的静态网站上，同时提供了一些为技术文档定制的开箱即用的特性。
Docsify / Docute
这两个项目同样都是基于 Vue，然而它们都是完全的运行时驱动，因此对 SEO 不够友好。如果你并不关注 SEO，同时也不想安装大量依赖，它们仍然是非常好的选择！
Hexo
Hexo 一直驱动着 Vue 的文档 —— 事实上，在把我们的主站从 Hexo 迁移到 VuePress 之前，我们可能还有很长的路要走。Hexo 最大的问题在于他的主题系统太过于静态以及过度地依赖纯字符串，而我们十分希望能够好好地利用 Vue 来处理我们的布局和交互，同时，Hexo 的 Markdown 渲染的配置也不是最灵活的。
GitBook
我们的子项目文档一直都在使用 GitBook。GitBook 最大的问题在于当文件很多时，每次编辑后的重新加载时间长得令人无法忍受。它的默认主题导航结构也比较有限制性，并且，主题系统也不是 Vue 驱动的。GitBook 背后的团队如今也更专注于将其打造为一个商业产品而不是开源工具。
Jekyll 是圈内最成熟的静态网站生成器之一，并且已经成为一个很棒工具。实际上，在 Docusaurus 之前，Facebook 的大多数开源网站都是基于 Jekyll 构建的！Jekyll 入门非常简单。我们希望带来与使用 Jekyll 构建静态站点类似的开发人员体验。
与生成静态 HTML 并使用

二、快速上手

前提条件： VuePress 需要Node.js>= 8.6

本文会帮助你从头搭建一个简单的 VuePress 文档。如果你想在一个现有项目中使用 VuePress 管理文档，从步骤 3 开始。

1. 创建并进入一个新目录

mkdir vuepress-starter && cd vuepress-starter

2. 使用你喜欢的包管理器进行初始化

yarn init # npm init

3. 将 VuePress 安装为本地依赖（我们已经不再推荐全局安装 VuePress）

yarn add -D vuepress # npm install -D vuepress

注意
如果你的现有项目依赖了 webpack 3.x，我们推荐使用 Yarn而不是npm来安装
VuePress。因为在这种情形下，npm会生成错误的依赖树。

4. 创建你的第一篇文档

mkdir docs && echo '# Hello VuePress' > docs/README.md

5. 在 package.json 中添加一些 scripts

{
  "scripts": {
    "docs:dev": "vuepress dev docs",
    "docs:build": "vuepress build docs"
  }
}

6. 在本地启动服务器

yarn docs:dev # npm run docs:dev

VuePress 会在http://localhost:8080 启动一个热重载的开发服务器。现在，你应该已经有了一个简单可用的 VuePress 文档。接下来，了解一下推荐的目录结构和 VuePress 中的基本配置。
等你了解完上文介绍的基础概念，再去学习一下如何使用 静态资源，Markdown 拓展和 在Markdown中使用Vue来丰富你的文档内容。
当你的文档逐渐成型的时候，不要忘记 VuePress的多语言支持并了解一下如何将你的文档部署到任意静态文件服务器上。

三、目录结构

VuePress 遵循 “约定优于配置” 的原则，推荐的目录结构如下：

.
├── docs
│   ├── .vuepress (可选的)
│   │   ├── components (可选的)
│   │   ├── theme (可选的)
│   │   │   └── Layout.vue
│   │   ├── public (可选的)
│   │   ├── styles (可选的)
│   │   │   ├── index.styl
│   │   │   └── palette.styl
│   │   ├── templates (可选的, 谨慎配置)
│   │   │   ├── dev.html
│   │   │   └── ssr.html
│   │   ├── config.js (可选的)
│   │   └── enhanceApp.js (可选的)
│   │ 
│   ├── README.md
│   ├── guide
│   │   └── README.md
│   └── config.md
│ 
└── package.json

请留意目录名的大写。

docs/.vuepress: 用于存放全局的配置、组件、静态资源等。
docs/.vuepress/components: 该目录中的 Vue 组件将会被自动注册为全局组件。
docs/.vuepress/theme: 用于存放本地主题。
docs/.vuepress/styles: 用于存放样式相关的文件。
docs/.vuepress/styles/index.styl: 将会被自动应用的全局样式文件，会生成在最终的 CSS 文件结尾，具有比默认样式更高的优先级。
docs/.vuepress/styles/palette.styl: 用于重写默认颜色常量，或者设置新的 stylus 颜色常量。
docs/.vuepress/public: 静态资源目录。
docs/.vuepress/templates: 存储 HTML 模板文件。
docs/.vuepress/templates/dev.html: 用于开发环境的 HTML 模板文件。
docs/.vuepress/templates/ssr.html: 构建时基于 Vue SSR 的 HTML 模板文件。
docs/.vuepress/config.js: 配置文件的入口文件，也可以是 YML 或 toml。
docs/.vuepress/enhanceApp.js: 客户端应用的增强。

当你想要去自定义 templates/ssr.html 或 templates/dev.html 时，最好基于默认的模板文件来修改，否则可能会导致构建出错。

3.1、默认的页面路由

此处我们把docs目录作为 targetDir ，下面所有的“文件的相对路径”都是相对于docs目录的。在项目根目录下的 package.json 中添加 scripts ：

{
  "scripts": {
    "dev": "vuepress dev docs",
    "build": "vuepress build docs"
  }
}

对于上述的目录结构，默认页面路由地址如下：

文件的相对路径	页面路由地址
/README.md	/
/guide/README.md	/guide/
/config.md	/config.html

四、基本配置

4.1、配置文件

如果没有任何配置，这个网站将会是非常局限的，用户也无法在你的网站上自由导航。为了更好地自定义你的网站，让我们首先在你的文档目录下创建一个 .vuepress 目录，所有 VuePress 相关的文件都将会被放在这里。你的项目结构可能是这样：

module.exports = {
  title: 'Hello VuePress',
  description: 'Just playing around'
}

对于上述的配置，如果你运行起 dev server，你应该能看到一个页面，它包含一个页头，里面包含一个标题和一个搜索框。VuePress 内置了基于 headers 的搜索 —— 它会自动为所有页面的标题、h2 和 h3 构建起一个简单的搜索索引。
参见配置来查看所有可配置的选项。

其他配置格式你也可以使用 YAML (.vuepress/config.yml) 或是 TOML
(.vuepress/config.toml) 格式的配置文件。

4.2、主题配置

一个 VuePress 主题应该负责整个网站的布局和交互细节。在 VuePress 中，目前自带了一个默认的主题（正是你现在所看到的），它是为技术文档而设计的。同时，默认主题提供了一些选项，让你可以去自定义导航栏（navbar）、 侧边栏（sidebar）和 首页（homepage） 等，详情请参见默认主题配置。
如果你想开发一个自定义主题，可以参考自定义主题。

4.3、应用级别配置

由于 VuePress是一个标准的Vue应用，你可以通过创建一个 .vuepress/enhanceApp.js 文件来做一些应用级别的配置，当该文件存在的时候，会被导入到应用内部。enhanceApp.js 应该 export default 一个钩子函数，并接受一个包含了一些应用级别属性的对象作为参数。你可以使用这个钩子来安装一些附加的 Vue 插件、注册全局组件，或者增加额外的路由钩子等：

// 使用异步函数也是可以的
export default ({
  Vue, // VuePress 正在使用的 Vue 构造函数
  options, // 附加到根实例的一些选项
  router, // 当前应用的路由实例
  siteData, // 站点元数据
  isServer // 当前应用配置是处于 服务端渲染 或 客户端
}) => {
  // ...做一些其他的应用级别的优化
}

五、静态资源

5.1、相对路径

5.2、公共文件

5.3、基础路径

六、Markdown扩展

七、在Markdown中使用Vue

八、多语言支持

8.1、站点多语言配置

要启用 VuePress 的多语言支持，首先需要使用如下的文件结构：

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

然后，在 .vuepress/config.js 中提供 locales 选项：

module.exports = {
  locales: {
    // 键名是该语言所属的子路径
    // 作为特例，默认语言可以使用 '/' 作为其路径。
    '/': {
      lang: 'en-US', // 将会被设置为 <html> 的 lang 属性
      title: 'VuePress',
      description: 'Vue-powered Static Site Generator'
    },
    '/zh/': {
      lang: 'zh-CN',
      title: 'VuePress',
      description: 'Vue 驱动的静态网站生成器'
    }
  }
}

如果一个语言没有声明 title 或者 description，VuePress 将会尝试使用配置顶层的对应值。如果每个语言都声明了 title 和 description，则顶层的这两个值可以被省略。

8.2、默认主题多语言配置

默认主题也内置了多语言支持，可以通过 themeConfig.locales 来配置。该选项接受同样的 { path: config } 格式的值。每个语言除了可以配置一些站点中用到的文字之外，还可以拥有自己的导航栏和侧边栏配置：

module.exports = {
  locales: { /* ... */ },
  themeConfig: {
    locales: {
      '/': {
        selectText: 'Languages',
        label: 'English',
        ariaLabel: 'Languages',
        editLinkText: 'Edit this page on GitHub',
        serviceWorker: {
          updatePopup: {
            message: "New content is available.",
            buttonText: "Refresh"
          }
        },
        algolia: {},
        nav: [
          { text: 'Nested', link: '/nested/', ariaLabel: 'Nested' }
        ],
        sidebar: {
          '/': [/* ... */],
          '/nested/': [/* ... */]
        }
      },
      '/zh/': {
        // 多语言下拉菜单的标题
        selectText: '选择语言',
        // 该语言在下拉菜单中的标签
        label: '简体中文',
        // 编辑链接文字
        editLinkText: '在 GitHub 上编辑此页',
        // Service Worker 的配置
        serviceWorker: {
          updatePopup: {
            message: "发现新内容可用.",
            buttonText: "刷新"
          }
        },
        // 当前 locale 的 algolia docsearch 选项
        algolia: {},
        nav: [
          { text: '嵌套', link: '/zh/nested/' }
        ],
        sidebar: {
          '/zh/': [/* ... */],
          '/zh/nested/': [/* ... */]
        }
      }
    }
  }
}

九、部署

下述的指南基于以下条件：

1. 文档放置在项目的 docs 目录中；
2. 使用的是默认的构建输出位置；
3. VuePress 以本地依赖的形式被安装到你的项目中，并且配置了如下的 npm scripts:

{
  "scripts": {
    "docs:build": "vuepress build docs"
  }
}

参考文档：
VuePress 中文网
Docusaurus中文网
基于Vue的静态网站生成器
Docusaurus静态网站建站工具