VuePress 是一个静态网站生成工具，它的功能和我之前用来给 MWordStar 制作帮助文档的 Docusaurus 差不多，它可以根据 Markdown 生成静态页面，可以很方便的部署到 Github Pages 的纯静态环境。

就像它的名字一样，VuePress 在生成页面的时候会使用 Vue 来构建，也会用到 Vue-Router 来管理路由，生成的页面也能实现无刷新跳转，同时它也会给每个页面生成单独的 HTML 文件，让搜索引擎也能访问。

最近我需要给我的 Typecho 博客主题 Facile 编写帮助文档，本来准备使用 Docusaurus 生成，但是我在 Docusaurus 的官网看到了 VuePress。Docusaurus 是使用 React 构建的，VuePress 是使用 Vue 构建，因为我使用 Vue 的时间比较长，相对更熟练一些，所以准备尝试使用 VuePress 来生成帮助文档。

我为 Facile主题 生成的帮助文档：https://facile.misterma.com/

Facile 主题帮助文档的 Github 仓库：https://github.com/changbin1997/facile-doc

所有的 Markdown 文档和配置文件都在 Github 仓库里。

安装和创建项目

VuePress 可以使用全局安装，也可以在项目中安装，官方更推荐在项目中安装，我这里写的也是在项目中安装。

VuePress 是使用 Node.js 编写的，在使用 VuePress 之前也需要安装 Node.js，我使用的包管理工具是 Node.js 默认的 npm。

创建一个项目目录，然后在命令行进入项目目录，使用 npm 初始化项目：

npm init -y

初始化完成后项目目录会生成 package.json 文件，

安装 VuePress：

npm install -D vuepress

安装完成后打开 package.json ，在 scripts 中添加两条脚本命令：

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

在项目根目录创建一个 docs 目录，在 docs 目录中创建一个 README.md 的 Markdown 文件，在这个文件中随便写一些内容，然后运行本地服务器：

npm run docs:dev

打开浏览器，访问 http://localhost:8080/ ，现在应该可以看到 docs 中的 README.md 的内容。

站点配置

VuePress 的站点和主题配置需要存放在 docs/.vuepress/config.js ，这个配置文件需要自己手动创建，在刚才创建的 docs 目录下再创建一个 .vuepress 目录，在 .vuepress 目录下创建一个 config.js 文件。

config.js 需要导出一个模块，模块内容是一个对象，下面配置网站名称和描述：

module.exports = {
  title: '网站标题',
  description: '这是我的网站描述'
};

其中 description 的网站描述会显示在标签页标题的后面。

配置顶部导航栏

导航栏还是在 .vuepress/config.js 文件中配置，导航栏、侧边栏之类的在 VuePress 中属于主题配置，需要写在 themeConfig 下，下面配置导航栏：

module.exports = {
  title: '网站标题',
  description: '这是我的网站简介',
  themeConfig: {
    nav: [
      {text: '文档首页', link: '/'},
      {text: '博客', link: 'https://www.misterma.com/'},
      {text: '留言板', link: 'https://www.misterma.com/msg.html'}
    ]
  }
};

themeConfig 下的 nav 数组就是导航栏，导航项的 text 是名称，link 是链接地址，我上面写的 / 地址默认会链接到 docs 目录下的 README.md 页面。

上面配置的导航栏如下：

VuePress的顶部导航栏

导航栏如果检测到有外部链接就会在链接名称后面添加一个图标和设置在新标签页打开。

VuePress 在转换页面的时候，也会生成一份文章标题作为索引，导航栏的搜索功能可以支持搜索文章标题跳转。

配置侧边栏

VuePress 默认的主题就是专为文档系统设计的，对于文档来说，侧边栏肯定是少不了的。

侧边栏还是在 .vuepress/config.js 的 themeConfig 下配置，下面配置简单的侧边栏：

module.exports = {
  themeConfig: {
    sidebar: [
      '/',
      '/下载和安装.md',
      '/文章设置.md'
    ]
  }
};

我上面配置的 .md 文件都放在 docs 目录，docs 目录相当于是文档的根目录，内部链接需要以 / 开头，如果只包含 / ，默认还是会跳转到 docs/README.md 页面。

侧边栏效果如下：

VuePress的普通侧边栏

如果 Markdown 文件里设置了标题的话，侧边栏配置可以只写文件名，VuePress 在生成页面的时候会自动查找链接文件的标题。

你也可以手动设置侧边栏的文件名：

module.exports = {
  themeConfig: {
    sidebar: [
      {title: '这是首页', path: '/'},
      {title: '这里是下载和安装说明', path: '/下载和安装.md'},
      {title: '这里是文章设置123', path: '/文章设置.md'},
      {title: '我的博客', path: 'https://www.misterma.com/'}
    ]
  }
};

效果如下：

VuePress自定义侧边栏链接名称和地址

多级侧边栏：

module.exports = {
  themeConfig: {
    sidebar: [
      '/',
      '/下载和安装.md',
      {
        title: '设置相关',
        children: [
          '/文章设置.md'
        ]
      },
      {
        title: '外部链接',
        children: [
          {title: '我的博客', path: 'https://www.misterma.com/'},
          {title: '我的 Github', path: 'https://github.com/changbin1997'}
        ]
      }
    ]
  }
};

效果如下：

VuePress多级侧边栏

配置首页

VuePress 在没有配置首页的情况下，打开网站后默认显示的是包含侧边栏的 README.md 文档页面，VuePress 和 Docusaurus 一样，也支持首页。

首页需要在 docs 目录下的 README.md 文件配置，以我的 Facile 主题帮助文档的首页为例，如下：

---
home: true
heroText: Facile
tagline: 一个简洁的 Typecho 博客主题
actionText: 开始使用 →
actionLink: 主题简介.md
features:
- title: 深色模式
  details: Facile 包含深色和浅色两套配色，主题配色可以根据用户的设备主题配色模式自动切换，也可以由站长或用户根据偏好在前台或后台手动切换。
- title: Emoji表情
  details: Facile 评论区包含一个 Emoji 表情面板，目前共有 1466 个表情，几乎涵盖了所有类型的表情，这些表情都是根据类型动态加载的，不用担心性能问题。
- title: 丰富的设置选项
  details: Facile 提供了丰富的设置选项，你可以根据偏好调整主题的外观、导航、侧边栏、文章阅读、评论区，甚至连文章代码块是否显示行号你都可以自己决定。
footer: Copyright © 2022 Facile, Inc. Built with VuePress.
---

下面是配置项说明：

  • home 设置为 true 是启用首页
  • heroText 首页标题
  • tagline 简单描述，会显示在首页标题下方
  • actionText 首页显示的最大的链接名称，一般用于下载或进入文档
  • actionLink 链接地址
  • features 产品功能说明相关的配置
  • title 功能标题
  • details 功能描述

访问 https://facile.misterma.com/ 可以查看我配置的 Facile 主题帮助文档的首页。

撰写文章

Markdown 文章需要放到 docs 目录或 docs 目录下的其它目录，文章的开头可以声明标题和语言，如下：

---
title: 下载和安装
lang: zh-CN
---

在配置侧边栏的时候，如果没有手动指定链接标题，VuePress 就会使用文章的 title 标题作为链接标题。

文章内用到的图片可以放到图床，也可以直接放到项目的 docs 目录下的 public 目录，public 目录是用来存储静态文件的，你也可以在 public 目录下创建不同的目录来存储不同类型的图片。

在文章中如果需要使用 public 目录中的图片，可以使用 ./public/文件名.jpg 的方式插入，如下：

![支付宝和微信的收款码](./public/qr-code.jpeg)

文章内如果需要插入跳转到其他页面的链接可以直接使用 /文件名.md 的地址，比如我想跳转到同一目录下的 download.md 页面：

[下载](/download.md)

内部链接在编译的时候会被转换为 router-link 链接，可以无刷新跳转，外部链接会被加入 target="_blank" ，会在新标签页打开。

编译

上面在 package.json 的运行脚本中加入了 docs:build 命令，编译可以输入：

npm run docs:build

生成的静态页面默认在项目目录下的 docs/.vuepress/dist 目录。

VuePress 会为每个页面生成单独的 HTML 文件，搜索引擎也能获取内容。放在 public 目录中的图片会被拷贝到网站目录下的 assets/img 目录。

部署

如果你有服务器或虚拟主机的话，只需要把 dist 目录中的页面文件上传到网站目录就可以访问了。

上传到 Github Pages

Github Pages 是一个免费的静态网站托管服务，很多开源项目的官网或帮助文档也会存放到 Github Pages。

创建一个 Github 仓库，仓库名 Repository name 就是你的 Github 用户名 + .github.io ，例如我的 Github 用户名是 changbin1997 ，我的 Github Pages 的仓库名就是 changbin1997.github.io 。

把 dist 内的静态页面上传到 username.github.io 的仓库就可以访问了。

注意，普通用户的 Github Pages 仓库必须公开，否则无法使用 Github Pages 服务。

上传到 Cloudflare Pages

Cloudflare Pages 是一个和 Github Pages 差不多的静态网站托管服务，Cloudflare Pages 免费用户可以创建多个站点，而且网站页面文件可以不用公开。

Cloudflare Pages 可以直接上传 HTML文件，也可以关联一个 Github 存储库，从存储库编译部署。

对于 VuePress 这一类前端项目来说，最好的方式就是从 Github 存储库部署。

随便创建一个 Github 仓库，可以不用公开，把你的 VuePress 项目提交推送到 Github，提交的时候不用提交 node_modules 目录和里面的文件，可以使用 .gitignore 过滤一下。

可以参考我之前写的 使用 Cloudflare Pages 托管静态网站 ，创建 Cloudflare Pages 站点，关联你的 VuePress 项目的 Github 仓库。

编译命令是：

npm run docs:build

静态页面的存放位置是 docs/.vuepress/dist 。

配置完成后，如果以后更改了 VuePress 项目的内容，只需要推送提交到 Github，Cloudflare Pages 就可以自动更新内容。

以上就是 VuePress 的简单使用说明，更详细的配置可以查看官方的 中文帮助文档 。

相关文章：