VuePress 建站速记

持续写作已经有两年多了，19年年初再次折腾建立自己的站点，主要基于以下原因

1. 和其他网站比起来，是比较清爽的，编辑器也非常好用，但推荐的文章层次太低，不符合程序员的气质
2. 自己建站，但不想关注除了文章内容以外的事情，即写完 Markdown 文件，提交到 github 上，文章会自动展现到页面上——让写文章和写代码保持一致的流程，方便管理

按照这个思路，我们可以把这个流程想的更具体点，例如我现在要写一篇文章，步骤是这样的：

1. 打开自己喜欢的编辑器（例如 Typora ），打开本地存放文章的目录（Typora 中敲 control + ⌘ + 3），新建一个 Markdown 文件
2. 开始写作
3. 写完后，打开终端，执行 git add -> git commit -> git push ，将文章提交到 github
4. 远端的 ECS 发现 github 上具体的 repo 下有更新，便自动执行 git pull 进行同步，并将 Markdown 文件渲染成静态页面，之后通过浏览器访问你的站点，就可以看到这篇文章了

这种方法有一个非常好的地方，它将写作的行为和写代码的行为保持一致，都是在本地完成，然后通过 git 进行管理，且无需担心备份、迁移等问题，这有效的减少了额外能量的消耗，能让我更快的进入写作状态，于是就可以把这个事情长期做下去。

用 github 管理自己的文章已有一段时间，但一直没有动手搭建远程站点，直到无意中看到了 VuePress 这个开源的软件，它可以很容易将 Markdown 渲染成 html 页面，同时我被它的简洁和专为技术站点打造所吸引，决定花点时间尝试一下。

大概折腾了一天，就把自己想要的效果实现了，如果不踩坑，可能不需要这么久。网上介绍 VuePress 的文章已经很详细了，这里就不重复了，有兴趣的同学可以查看文章最后的参考链接。

这里我简单讲下作为一个不懂前端的同学，我有哪些疑惑、它们是如何解除的；以及自己踩了什么坑、怎么爬出来的。

在使用 VuePress 中，我最大的疑惑是如何成功添加一个 Markdown 插件，它的步骤是什么，怎么知道引入的插件是否生效。经过了一番尝试后，总结为 3 个步骤（意味着你脑海中的额外的想法都是多余的）：

1. 安装插件
2. 将插件添加到配置中
3. 重新构建：yarn docs:build

拿数学公式插件 markdown-it-katex 作为例子，首先通过以下命令安装该插件

$ yarn add markdown-it-katex

修改 .vuepress/config.js 下的配置，添加一行 md.use(require("markdown-it-katex"))，如下：

module.exports = {
  markdown: {
    config: md => {
      md.set({html: true})
      md.use(require("markdown-it-katex"))
    }
  }
}

构建后，一般的插件安装到此就完成了，对于 markdown-it-katex 来说，你还需要修改 head 项，依旧是 .vuepress/config.js 文件，在 head 中添加如下两行：

module.exports = {
  head: [
    // ...
    ['link', { rel: 'stylesheet', href: 'https://cdnjs.cloudflare.com/ajax/libs/KaTeX/0.7.1/katex.min.css' }],
    ['link', { rel: "stylesheet", href: "https://cdnjs.cloudflare.com/ajax/libs/github-markdown-css/2.10.0/github-markdown.min.css" }]
  ]
  // ...
}

大功告成，现在 VuePress 可以识别出你文章中的数学公式了，如下所示：

最后，说下自己的采坑经历，我在修改完以上配置后，发现文章中的数学公式还是不能正常显示，于是各种 google、global 安装等，最后发现是自己写错了配置：把配置中的 markdown 对象写到 themeConfig 中了，如下

  // ...
  themeConfig: {
    markdown: {
      // ...
    }
  }

这种错很难发现，花了不少时间，希望写出来，能帮犯同样错误的同学节省时间。

原文：http://yaje.fun/tools/vuepress_website.html

参考：

• VuePress官网文档
• 如何使用 VuePress 编写静态博客
• VuePress 快速踩坑
• VuePress 手摸手教你搭建一个类Vue文档风格的技术文档/博客