VuePress 入门-CSDN博客

VuePress 是一款使用 Vue 驱动的静态网站生成器，是 Vue 的作者 Evan You 为了方便文档的编写而开发的。

默认主题与 Vue 官方文档一致
简洁，少配置，高性能
Markdown 专为技术文档提供拓展
自带 PWA
自定义主题，可定制程度完全由自己决定

官方文档：由于 1.x 还处于测试阶段，可能随时变更，所以建议选用 0.x 版本

0.x 版本
1.x 版本

1. 初始化

安装

首先需要安装 vuepress

可以使用全局安装：（选一个版本安装即可，使用 yarn 或 npm 都可以）

yarn add global vuepress # 0.x 版本
yarn add global vuepress@next # 1.x 版本
复制代码

也可以使用局部安装，在你的项目根目录下：

yarn add -D vuepress
yarn add -D vuepress@next
复制代码

注意有一个坑，我遇到过，安装 vuepress@next 以及其他插件时，默认会安装 alpha 0 版本，需要修改 package.json 文件，更改版本号，再重新使用 yarn 安装一下。

另外，全局安装与局部安装在后面的部署命令中会有些差别。

结构目录

.
├── docs
│   ├── .vuepress
│   │   ├── public
│   │   └── config.js
│   │ 
│   └── README.md
│ 
└── package.json
复制代码

可详细查看：目录结构

2. 配置 config.js 文件

基础配置

module.exports = {
  title: "destiny'Note",
  description: "生命的意义不仅是活着，而是我们给别人的生命带来了何种不同。",
  base: '/', // 项目根路径
  dest: '/dist/', // 打包后的文件夹路径，为了方便，我把 dist 文件夹放到了根目录上
  // head 标签中的额外内容
  head: [
    ['link', { rel: 'icon', href: '/favicon.ico' }] // 这个是标签页 logo
  ],
  // 语言配置
  locales: {
    // 键名是该语言所属的子路径
    // 作为特例，默认语言可以使用 '/' 作为其路径。
    '/': {
      lang: 'zh-CN', // 将会被设置为 <html> 的 lang 属性
    }
  }
}
复制代码

可详细查看：配置

主题配置

module.exports = {
  ...
  // 主题配置
  themeConfig: {
    // 顶部导航
    nav: [
      { text: '首页', link: '/' },
      { text: '归档', link: '/archives/'},
      { text: '分类', link: '/categories/' },
      { text: '标签', link: '/tags/' },
      { text: '关于我', link: '/about/' }
    ],
    
    // 侧边栏
    sidebar: [
      '/'
    ],
    sidebarDepth: 2, // 默认 1 提取到 h2，0 为禁用，2 为 h2，h3
    displayAllHeaders: false, // 默认值：false 侧边栏只会显示由当前活动页面的标题组成的链接
    activeHeaderLinks: true, // 默认值：true 滚动时通过 hash 高亮侧边栏标题

    // Git 仓库和编辑链接
    repo: 'username/repo', // 你的仓库
    repoLabel: 'GitHub', // 导航栏上的文本

    editLinks: true,
    // 默认为 "Edit this page"
    editLinkText: '编辑此页面'
  }
}
复制代码

可详细查看：默认主题配置

3. 首页

配置 docs 下的 README.md 文件即可：

---
home: true
heroImage: /hero.jpg
heroText: Hero
tagline: Hero 副标题
actionText: 快速上手 →
actionLink: /zh/guide/
features:
- title: 简洁至上
  details: 以 Markdown 为中心的项目结构，以最少的配置帮助你专注于写作。
- title: Vue驱动
  details: 享受 Vue + webpack 的开发体验，在 Markdown 中使用 Vue 组件，同时可以使用 Vue 来开发自定义主题。
- title: 高性能
  details: VuePress 为每个页面预渲染生成静态的 HTML，同时在页面被加载的时候，将作为 SPA 运行。
footer: MIT Licensed | Copyright © 2018-present Evan You
---
复制代码

首页必须设置 home 为 true。默认样式与官方文档首页一致。

4. 开发和部署

定义脚本

初始化 package.json，如果是局部安装的话，这个文件已经存在，不需要执行这个命令

yarn init
复制代码

编辑 package.json 文件，添加如下脚本：（这里需要注意）

{
  ...
  // 全局安装
  "scripts": {
    "dev": "vuepress dev docs",
    "build": "vuepress build docs"
  }
  // 局部安装
  "scripts": {
    "dev": "npx vuepress dev docs",
    "build": "npx vuepress build docs"
  }
}
复制代码

个人不喜欢官方的写法，就把名称写的简洁一些。

运行脚本命令：

yarn dev # 开发
yarn build # 打包
复制代码

部署到 GitHub Pages 上

部署到 GitHub 上，首先要在 GitHub 上建立仓库，这里省略。

然后再本地初始化仓库，并关联远程仓库

git init
git remote add origin <repo> # 你的远程仓库
复制代码

打包之后把整个项目上传到 master 分支上，方便管理

git add -A
git commit -m 'init blog'
# 首次提交需要 --set-upstream，后续可以去掉
git push --set-upstream origin master # 所有代码推送到远程仓库的 master 分支上
复制代码

单独将打包好的文件上传到 gh-pages 分支上，自动会生成 GitHub Pages，在仓库设置里可以查看到相应地址。

git subtree push --prefix dist origin gh-pages # 只将 dist 上传到 gh-pages 分支
复制代码

注意，最好配置一个 .gitignore 文件，去掉不需要上传的文件和文件夹。

自动化部署

每一次更新完文章之后，都需要敲一大串代码，才能重新部署，显得很繁琐。那么我们来让这些命令合并成一个命令吧。

项目根目录下创建 deploy.sh 文件：

#!/usr/bin/env sh

# 确保脚本抛出遇到的错误
set -e

# 生成静态文件
yarn build

# 提交到历史区，$1 为运行 sh 时的第一个参数
git add -A
git commit -m $1

# 提交到 master 分支
git push origin master

# 将 dist 文件提交到 gh-pages 分支
git subtree push --prefix dist origin gh-pages

# 退出命令
exit 0
复制代码

然后在 package.json 文件中配置脚本：

{
  "scripts": {
    //...
    "deploy": "bash deploy.sh"
  }
}
复制代码

后续部署直接使用命令：

yarn deploy "updatedBlog"
复制代码

需要注意的是，后面带的消息，不能使用空格隔开（本人对 shell 脚本不熟悉，查找了也没明白，希望有大神指点一下），使用了空格，就会导致只提交了空格前的消息

另外，这个命令需要在 git bash 中使用，不能在 Windows 的命令行中使用。

5. 后续

太喜欢 VuePress 了，因为后面都托管给 Vue 了，所以速度飞快。

后续会出一个如何修改默认主题的文章。