使用 VuePress 搭建博客

发表于 分类于 阅读次数： 本文字数： 2.3k 阅读时长 ≈ 2 分钟
默认

前排提醒: 你也许需要一定的前端基础（非传统前端）才能读懂此篇文章的内容。

我认为 Vue 的生态是有够好的了——有 Router，有 Vuex，还有更多，都是非常有用处的。其中就包含 VuePress，原本是尤雨溪先生用来提高写文档效率而写的一个小作品，现在被发展后可以用作电子书/教程编写和博客的编写。本篇文章介绍的是后者，实际上两者是相通的。

[TOC]

流程

VuePress 与其它静态博客软件的发布流程基本一样——写完文章后 build 成为静态文件。所以如果是 Hexo 或者 Hugo 用户看到这篇文章中的流程也许会感觉很熟悉，不过这里还是提到一下。

也正因为是静态文件，所以可以使用 GitHub 托管——当然也可以使用你自己的主机，仅需将网站根目录设置为 build 产生的静态文件的目录即可。这会在下文中提到。

安装

首先选择一个你想要用来作为博客源代码放置之处的文件夹，下文中如果没有特殊声明，所有的文件、目录均指创建在此文件夹里。

通过 npm 和 yarn 均可安装。本文主要使用 yarn。

1
2
3
mkdir blog && cd blog
yarn init # npm init
yarn add -D vuepress # npm install -D vuepress

搭建

创建你的第一篇文档

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

在 package.json 中添加一些 scripts

这一步骤是可选的，但我们推荐你完成它。在下文中，我们会默认这些 scripts 已经被添加。

1
2
3
4
5
6
{
  "scripts": {
    "docs:dev": "vuepress dev docs",
    "docs:build": "vuepress build docs"
  }
}

写作与发布

如果你的环境已经搭建完毕，那么你可以选择在纯 Markdown 下进行写作，然后直接 push 到你的仓库中去。

而如果你想要实时预览自己的文章在博客上的样子，或者调试一些应用层面的东西，你就需要启动开发服务器。

与 Vue 的开发服务器相同，VuePress 的服务器也是支持热重载的。

1
yarn docs:dev # npm run docs:dev

这样，在默认情况下会在 https://localhost:8080 开放你的开发服务器，访问即可看到你的网站。

最后，写完了就可以进行构建了——将你的网站样式和内容编译成静态网页。

1
yarn docs:build # npm run docs:build

默认情况下这个静态网页会被保存到 docs/.vuepress/dist 内，在后文会介绍修改方法。

配置、主题、插件

VuePress 之所以适合开发者，是因为它可以通过配置、主题和插件三方面高程度个性化——当然，是在你会 Vue 而且会看 VuePress 的 API 的前提下。

VuePress 的配置文件存储在 .vuepress 里，一般情况下是没有这个文件夹的，我们可以自己创建。

进入后，创建 config.js，这就是 VuePress 的配置文件。

1
2
mkdir docs/.vuepress  && cd docs/.vuepress
vi config.js

config.js 在写入一个语句之后即可当作一般的 JSON 文件来使用——它比 JSON 要宽松得多。

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

具体配置项目可以参考 VuePress 官方文档的配置

要切换主题，首先使用 npm 安装你想要的主题，比如

1
yarn add vuepress-theme-reco # npm install vuepress-theme-example --save-dev

然后在 config.js 里添加一行

1
2
3
4
module.export = {
    // ...
    theme: "reco",
}

即可。

1
yarn docs:dev # npm run docs:dev

在这里需要注意的一点是，VuePress 的所有主题、Plugin，根据官方的建议，均是以 vuepress-theme- 和 vuepress-plugin- 开头。也正因此，安装以他们开头的主题或插件，在填写的时候则可以省略 vuepress-theme- 这样的开头。当然，这只是一般情况，具体请以你所看到的主题或插件为准。

关于 VuePress 原版主题的相关配置可以看官方文档的默认主题。

参考

这是阅读完文章后，我个人推荐去参考的一些文档，以及一些可能需要的插件。

  • config.js 里完整的配置项有多少、哪些，有何作用？
  • Google 搜索 VuePress 的主题
  • meteorlxy/awesome-vuepress - 丰富的 VuePress 周边生态推荐
  • vuejs/vuepress/packages/@vuepress - VuePress 官方开发的插件
  • vuepress-plugin-mathjax - 在你的博客里写 公式。
  • vuepress-plugin-last-updated - 根据 Git Log 显示文章最后修改时间
  • vuepress-plugin-pwa - 将你的博客变成具有 PWA 性质的 Web App
  • Subilan/Blog - 本博客的 GitHub 仓库