小驿搭建（二）——用VuePress做静态博客

Kelmory 5/10/2021 前端VuePress

# Vuepress

VuePress (opens new window) 由两部分组成：第一部分是一个极简静态网站生成器 (opens new window)，它包含由 Vue 驱动的主题系统和插件 API，另一个部分是为书写技术文档而优化的默认主题，它的诞生初衷是为了支持 Vue 及其子项目的文档需求。

以上是Vuepress的官方介绍，从这里我们可以看到，这是一个由Vue驱动的项目，并提供了灵活的主题配置和插件配置。由此，我们可以通过Vuepress实现一个博客，事实上采用Vuepress作为博客的极客并不少，在这里 (opens new window)你可以找到很多案例，以及有用的资源。

Vuepress在其基础使用中提供了两种模式——dev和build，在dev模式下，可以撰写Markdown文档并在本地浏览器上实时预览；在build模式下，写好的文章会被Vuepress打包并转化为一套基于Vue的HTML+CSS+JS+Static文件，只要把这组打包好的文件使用服务器伺服即可实现访问。关于Vuepress的实现原理和更多使用方法，请参考官方文档 (opens new window)。

# Vuepress的安装

Vuepress使用了npm进行依赖管理，更进一步的，使用了yarn。在使用yarn之前，首先需要安装npm，再通过npm安装yarn：

# Debian
$ apt install npm
# Windows 
> choco install npm
# After installing npm
$ npm install --global yarn
# Test if installed successfully
$ yarn --version

这里我们使用了--global来在npm全局安装yarn，从而在任意目录下使用yarn。

接下来我们就可以开始安装和使用Vuepress了，需要注意的是官方文档首页上的安装方法已经不适用，因为全局安装Vuepress并不是一个好的选择。请参考快速上手 (opens new window)中的内容。此处不做描述，以防止描述过期带来的误导。

在yarn的package.json中，我们可以看到两条脚本——"docs:dev"和"docs:build"，docs是我们放置文档的目录，dev即是用于预览博客的模式，而build则是发布模式。

# Develop the blog
$ yarn docs:dev
success [14:58:26] Build 3d2b99 finished in 292 ms! ( http://localhost:8080/ )
# Package the blog
$ yarn docs:build
✔ Client
  Compiled successfully in 18.85s

✔ Server
  Compiled successfully in 13.54s

wait Rendering static HTML...
success Generated static files in docs/.vuepress/dist.

以上分别是使用dev和build的部分log。首先你可以看到dev模式下，如果你使用默认配置或是使用主题并配置无误，你就可以看到成功success的信息，并根据括号提示中的地址访问。如果你使用的是build模式，你就能看到生成的静态文件位于dist目录下。

# Vuepressd的文件结构

在上一节我们提到了生成的静态文件存放在的dist目录，那么对于整个Vuepress，其文件结构如何呢？这里我们使用tree命令在项目目录（包含yarn.lock, package.json的那层）的输出作为展示(此处参考Vuepress使用指南(reco) (opens new window)：

.
├── .git (git仓库)
├─ node_modules #存放着项目所需的依赖，我们不需要关心
├─ docs  #该目录下存放您编写的文档
│  └─ theme-reco
│    ├─ api.md
│    ├─ plugin.md
│    ├─ theme.md
│    └─ README.md
├─ blogs #该目录下存放您编写的博客文章
│    ├─ category1
│    │  ├─ 2018
│    │  │  └─ 121501.md
│    │  └─ 2019
│    │    └─ 092101.md
│    ├─ category2
│    │  ├─ 2016
│    │  │  └─ 121501.md
│    │  └─ 2017
│    │    └─ 092101.md
│    └─ other
│        └─ guide.md
├─ .vuepress # 该目录下存放项目配置文件与静态资源
│  ├─ config.js #该文件用于配置项目
│  └─ public # 该目录下存放网页中所需的静态资源
│    ├─ hero.png # 首页大图
│    ├─ logo.png # 站点logo
│    ├─ favicon.ico #站点图标
│    └─ avatar.png #头像
├─ package.json #依赖管理文件
├─ README.md #这里存放着博客首页的内容
└── yarn.lock （yarn的包管理文件）

在这里我们省略了node_module目录，只需知道其是存放这个项目依赖的文件的目录即可，并可以通过在有yarn.lock和package.json的目录下执行yarn install安装复原即可。

# 配置主题

正如在文章最开始的引用中所写的，Vuepress包含了一个默认主题，这个主题非常适合展示文档，但不一定适合做博客。为此，我们需要更换主题。

在Awesome-Vuepress (opens new window)里有不少主题，可以任选一个加以使用。不过，要注意不同的主题可能有不同的配置方法，最好的还是参考作者本人的文档。

这里我使用的是vuepress-reco (opens new window)，这个主题的主页比较灵动，且展示效果不错。具体配置过程请参考其官方文档 (opens new window)，主要的配置工作在config.js和docs的readme.md中开展。

以下是一个config.js的示例：

module.exports = {
    title: 'Kelforest', //　主标题
    description: '代码小驿 - 至简致知',　//　副标题
    theme: 'reco', 
    themeConfig: { //　主题内配置
        type: 'blog',
        blogConfig: {
            category: {
                location: 2,
                text: 'Category'
            },
            tag: {
                location: 3,
                text: 'Tag'
            },
            socialLinks: [
                { icon: 'reco-github', link: 'https://github.com/Kelmory' },
            ]
        },
        nav: [ //　主页作者页面下的链接，以object方式记录
            { text: 'Home', link: '/', icon: 'reco-home' },
        ],
        author: 'Kelmory',
        authorAvatar: '/avatar.jpg'
    }
}

更多的信息请参考上文提到的使用指南，此处不做赘述。

# 写一篇Blog

配置完成后，我们就可以以markdown写一篇博客了。首先我们使用yarn docs:dev创建一个开发服务器，然后我们就可以在docs目录中创建markdown文件作为博客了。在docs目录下，docs/README.md会被解析为首页内容。对于docs的子目录，子目录会被作为url中的一部分使用。例如在docs下有一个blogs目录，该目录下有一个first.md，则这个first.md文件会被渲染为first.html，并通过URLhttp(s)://{domain}/{baseURL}/blogs/first.html定位。

# Markdown

Markdown (opens new window)是一种轻量级标记语言，排版语法简洁，让人们更多地关注内容本身而非排版。它使用易读易写的纯文本格式编写文档，可与HTML混编，可导出 HTML、PDF 以及本身的 .md 格式的文件。因简洁、高效、易读、易写，Markdown被大量使用，如Github、Wikipedia等网站，如各大博客平台：WordPress、Drupal、简书等。

关于Markdown写作请参考上方引用内链接。

# Front Matter

Vuepress支持的Markdown解释器不仅提供了对内容的格式控制，且提供了对一些被称为Front Matter的内容的解析功能，这些Front Matter在vuepress系统中提供了一些渲染相关的配置。以下是一个FrontMatter示例：

---
title: 标题
date: 2021-05-10 (日期)
description: (博客描述，类似摘要)
categories: (分类)
    - Blog
tags: (标签)
    - VuePress
sidebar: auto (开启侧边栏，boolean或"auto")
publish: true (是否发布)
keys: (密码)
    - '123456'
---

注意到，FrontMatter是一段以---作为起始行和终结行的内容。这里可以看到其中的项主要分为内容和控制两类，对于内容类你可以指定标题、作者、写作日期、分类和标签等；对于控制类则需要参考

# Next Step

至此，我们就初步搭建了一个可用于发布markdown写作的博客的vuepress框架。为了使它更好地服务，我们还可以为它配置诸多周边配套的服务，如反向代理服务器Nginx、面向CICD的组合Gitea+Drone、面向评论的Valine。