VuePress

superC frontend

从入门到实战，手把手教你使用VuePress搭建个人博客~~~

# 一、VuePress基础

# 1.1 VuePress简介

VuePress官网：https://vuepress.vuejs.org (opens new window)

VuePress中文文档：https://www.vuepress.cn (opens new window)

VuePress是一款由Vue驱动的静态网站生成器。作者是尤雨溪（vue.js 框架作者）。实际上就是一个Vue的SPA应用，内置webpack，结合markdown来搭建个人博客站点。

其他类似的建站工具也有很多，比如 WordPress、Jekyll、Hexo 等。

# 1.2 VuePress优点

界面简洁优雅（个人感觉比 HEXO 好看）
容易上手（半小时能搭好整个项目）
更好的兼容、扩展 Markdown 语法
响应式布局，PC端、手机端
Google Analytics 集成
支持 PWA

# 1.3 VuePress组成

VuePress 由两部分组成：

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

每一个由 VuePress 生成的页面都带有预渲染好的 HTML，也因此具有非常好的加载性能和搜索引擎优化（SEO）。同时，一旦页面被加载，Vue 将接管这些静态内容，并将其转换成一个完整的单页应用（SPA），其他的页面则会只在用户浏览到的时候才按需加载。

# 1.4 VuePress工作原理

事实上，一个 VuePress 网站是一个由 Vue (opens new window) (opens new window)、Vue Router (opens new window) (opens new window)和 webpack (opens new window) (opens new window)驱动的单页应用。如果你以前使用过 Vue 的话，当你在开发一个自定义主题的时候，你会感受到非常熟悉的开发体验，你甚至可以使用 Vue DevTools 去调试你的自定义主题。

在构建时，我们会为应用创建一个服务端渲染（SSR）的版本，然后通过虚拟访问每一条路径来渲染对应的HTML。这种做法的灵感来源于 Nuxt (opens new window) (opens new window)的 nuxt generate 命令，以及其他的一些项目，比如 Gatsby (opens new window) (opens new window)。

# 1.5 VuePress目录结构

VuePress 遵循 “约定优于配置” 的原则，推荐的目录结构如下：

.
├── docs
│   ├── .vuepress (可选的)
│   │   ├── components (可选的)
│   │   ├── theme (可选的)
│   │   │   └── Layout.vue
│   │   ├── public (可选的)
│   │   ├── styles (可选的)
│   │   │   ├── index.styl
│   │   │   └── palette.styl
│   │   ├── templates (可选的, 谨慎配置)
│   │   │   ├── dev.html
│   │   │   └── ssr.html
│   │   ├── config.js (可选的)
│   │   └── enhanceApp.js (可选的)
│   │ 
│   ├── README.md
│   ├── guide
│   │   └── README.md
│   └── config.md
│ 
└── package.json

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22

# 默认跟路径docs

VuePress约定入口目录必须是 docs，下面所有的“文件的相对路径”都是相对于 docs 目录的。。

文件的相对路径	页面路由地址
`/README.md`	`/`
`/guide/README.md`	`/guide/`
`/config.md`	`/config.html`

# 目录结构描述

docs/.vuepress: 用于存放全局的配置、组件、静态资源等。

docs/.vuepress/components: 该目录中的 Vue 组件将会被自动注册为全局组件。
docs/.vuepress/theme: 用于存放本地主题。
docs/.vuepress/styles: 用于存放样式相关的文件。
- docs/.vuepress/styles/index.styl: 将会被自动应用的全局样式文件，会生成在最终的 CSS 文件结尾，具有比默认样式更高的优先级。
- docs/.vuepress/styles/palette.styl: 用于重写默认颜色常量，或者设置新的 stylus 颜色常量。
docs/.vuepress/public: 静态资源目录。
docs/.vuepress/templates: 存储 HTML 模板文件。
- docs/.vuepress/templates/dev.html: 用于开发环境的 HTML 模板文件。
- docs/.vuepress/templates/ssr.html: 构建时基于 Vue SSR 的 HTML 模板文件。
docs/.vuepress/config.js: 配置文件的入口文件，也可以是 YML 或 toml。
docs/.vuepress/enhanceApp.js: 客户端应用的增强。

当你想要去自定义 templates/ssr.html 或 templates/dev.html 时，最好基于默认的模板文件 (opens new window) (opens new window)来修改，否则可能会导致构建出错。

# 1.6 VuePress产出

# 1 文档主题的个人站点

# 2 博客主题的个人站点

# 二、VuePress上手

VuePress快速上手官方文档（1.x） (opens new window)

# 资源准备

windows笔记本电脑：用于搭建环境
github账户（可选，二选一）
云服务器（可选，二选一）
- 阿里云服务器：用于部署博客站点
- 域名：用于便捷访问博客站点

# 前置安装

安装node.js

请确保你的 Node.js 版本 >= 8.6。
安装npm/cnpm

# 搭建步骤

# 创建项目

创建一个文件夹，来搭建个人博客项目。

mkdir myPress
cd myPress

1
2

# 创建git忽略文件

在根目录创建.gitignore文件

# Project directories
node_modules/
docs/.vuepress/dist/
dist/

# Editor directories and files
.idea
.vscode
*.suo
*.ntvs*
*.njsproj
*.sln

# Tool directories
.git
.svn

# vuepress temp file
.temp

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19

# 创建目录结构

在根目录创建docs文件夹和package.json文件；
在 docs 中创建README.md文件、 .vuepress 文件夹、guide文件夹；
在.vuepress中创建 public 文件夹和 config.js 文件；
在guide中创建README.md文件；

cd . > package.json
md docs
cd docs
cd . > README.md
md .vuepress guide
cd . > guide/README.md
cd .vuepress
cd . > config.js
md public
cd public
md img

1
2
3
4
5
6
7
8
9
10
11

最终的项目目录结构如下：

myPress
├─── docs
│   ├── README.md
│   └── .vuepress
│       ├── public
│       	└── img
│       └── config.js
│   └── guide
│       ├── README.md
└── package.json

1
2
3
4
5
6
7
8
9
10

# 填充内容

在根目录创建package.json文件

{
  "name": "myPress",
  "version": "1.0.0",
  "description": "我的个人博客",
  "author": "superC",
  "main": "index.js",
  "license": "MIT",
  "dependencies": {
    "vuepress": "^1.9.9",
    "vuepress-theme-reco": "^1.6.16"
  },
  "devDependencies": {
    "vuepress-plugin-container": "^2.1.5"
  },
  "scripts": {
    "test": "echo \"Error: no test specified\" && exit 1",
    "dev": "vuepress dev docs --temp .temp",
    "build": "vuepress build docs"
  },
  "keywords": [],
  "directories": {
    "doc": "docs"
  }
}

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24

说明：

1. --temp .temp 表示开发环境实现热编译，浏览器自动更新。

在README.md添加如下内容：

---

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

---

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16

在guide目录创建README.md

首页内容

在config.js文件中配置网站标题、描述、主题等信息。

module.exports = {
  title: '我的博客',
  description: '苦海无涯，学无止境！',
  port: '8080', //端口号
  head: [ // 注入到当前页面的 HTML <head> 中的标签
    ['link', { rel: 'icon', href: '/img/logo.png' }], // favicon图标
	['link', { rel: 'manifest', href: '/img/home.png' }], // 主页图片
	['link', { rel: 'apple-touch-icon', href: '/img/logo.png' }], // app主页图片
  ],
  base: '/', // 基础路径
  serviceWorker: true, // 是否开启 PWA
  markdown: {
    lineNumbers: true // 代码块显示行号
  },
  themeConfig: {
    // 导航栏配置
    nav:[],
    sidebar: 'auto', // 侧边栏配置
    sidebarDepth: 2, // 侧边栏显示2级
  }
};

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21

说明

在public/img文件夹下存入.jpg图片。
/views目录的/指的是docs目录，所有md文档都归纳至views目录，然后根据类别区分存储。
你可以省略 .md 扩展名，以 / 结尾的路径被推断为 */README.md 。

# 在img添加图片

在public/img中添加logo.png、home.png。

# 启动运行

一切就绪跑起来看看吧

cnpm install
cnpm run dev

1
2

# nginx部署

进入项目路径，执行build

cnpm run build

会在docs/vuepress下生成dist目录，该文件夹的内容拷贝至nginx的html中即可。

# 三、VuePress配置

VuePress配置官方文档（1.x） (opens new window)

# 四、VuePress插件

VuePress插件官方文档（1.x） (opens new window)

# 4.1 配置侧边栏激活跟随

配置页面滚动时自动激活侧边栏链接

1、安装依赖

cnpm install -D @vuepress/plugin-active-header-links

2、添加配置

在config.js——plugins中添加如下配置：

vi ./config.js

module.exports = {
  plugins: ['@vuepress/active-header-links']
}

1
2
3

# 4.2 配置代码复制

集成代码复制插件：vuepress-plugin-code-copy (opens new window)

1、安装依赖

cnpm install -D vuepress-plugin-code-copy

2、添加配置

在config.js——plugins中添加如下配置：

vi ./config.js

	// 代码复制
    'vuepress-plugin-code-copy': true

1
2

# 4.3 配置全文搜索

集成全文搜索插件：vuepress-plugin-flexsearch (opens new window)

1、安装依赖

cnpm install -D vuepress-plugin-flexsearch

2、添加配置

在config.js——plugins中添加如下配置：

vi ./config.js

    // 全文搜索
    'flexsearch': {
      /*
        Plugin custom options
      */
      maxSuggestions: 10, // how many search suggestions to show on the menu, the default is 10.
      searchPaths: ['path1', 'path2'], // an array of paths to search in, keep it null to search all docs.
      searchHotkeys: ['s'], // Hot keys to activate the search input, the default is "s" but you can add more.
      searchResultLength: 60, // the length of the suggestion result text by characters, the default is 60 characters.
      splitHighlightedWords: ' ', // regex or string to split highlighted words by, keep it null to use flexsearch.split
      noExtraSpaceAfterHtmlTag: false, // don't add extra spaces in highlighted results
      /*
        Default FlexSearch options
        To override the default options you can see available options at https://github.com/nextapps-de/flexsearch
      */
      search_options: {
        encode: "icase",
        tokenize: "forward",
        resolution: 9,
        doc: {
          id: "key",
          field: ["title", "content", "headers"],
        }
      }
    }

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25

# 4.4 配置评论

集成评论系统leancloud。

1、注册账户

注册leancloud (opens new window)账号
实名认证
创建应用
复制 AppID 和 AppKey

2、安装依赖

cnpm install -D vuepress-plugin-comment

3、添加配置

在config.js——plugins中添加如下配置：

vi ./config.js

  // 评论插件
  'vuepress-plugin-comment': {
    choosen: "valine",
    // options选项中的所有参数，会传给Valine的配置
    options: {
      el: "#valine-vuepress-comment",
      appId: "你在leancloud的ID",
      appKey: "你在leancloud的KEY",
      path: '<%- frontmatter.to.path %>'
    }
  }

1
2
3
4
5
6
7
8
9
10
11
12

# 4.5 配置随机名言

集成插件自动随机获取名人名言，vuepress-plugin-boxx (opens new window)

vuepress插件-Boxx 相关文档 (opens new window)

1、安装依赖

cnpm install -D vuepress-plugin-boxx:0.0.7

2、添加配置

在config.js——plugins中添加如下配置：

vi ./config.js

module.exports = {
  plugins: ['vuepress-plugin-boxx']
}

1
2
3

3、使用

在所需页面使用

<Boxx :titleStyle="titleStyle" />
<script>
	export default {
		data() {
			return {
        titleStyle: {'font-weight': 'bold'},
			}
		}
	}
</script>

1
2
3
4
5
6
7
8
9
10

# 4.6 配置百度广告

# 4.7 配置百度统计

# 4.8 插件配置清单

VuePress 社区-插件 (opens new window)

插件名称：版本	描述	来源
@vuepress/plugin-active-header-links	页面滚动时自动激活侧边栏链接
vuepress-plugin-boxx	自动随机添加名人名言	第三方库
vuepress-plugin-container
vuepress-plugin-comment	评论插件
vuepress-plugin-dynamic-title	图片放大插件
vuepress-plugin-flexsearch	全文搜索
vuepress-plugin-nuggets-style-copy	代码复制	第三方库
vuepress-sidebar-atuo	侧边栏配置

# 五、VuePress主题

VuePress主题官方文档（1.x） (opens new window)

VuePress默认主题配置官方文档（1.x） (opens new window)

# 5.1 vuePress-theme-reno

vuepress-theme-reco 官方插件 (opens new window)

vuepress-theme-reco 官方插件广场 (opens new window)

vuepress-theme-reco 案例 (opens new window)

# 六、VuePress开发

# 6.1 首页配置

首页配置官方文档（1.x） (opens new window)

文档主题的首页

---
home: true
heroImage: /hero.png
heroImageStyle: {
  maxHeight: '200px',
  display: block,
  margin: '6rem auto 1.5rem',
  borderRadius: '50%',
  boxShadow: '0 5px 18px rgba(0,0,0,0.2)'
}
---

1
2
3
4
5
6
7
8
9
10
11

博客主题的首页

---
home: true
bgImage:  '/img/home.png'
bgImageStyle: {
  height: '350px'
}
---

1
2
3
4
5
6
7

# 6.2 在md文档中的配置

关闭导航栏

navbar: false

关闭评论

isShowComments: false

关闭左边侧边栏菜单

sidebar: false

# 6.3 icon使用

icon来源

vuePress-theme-reno 内置图标清单 (opens new window)

vuePress-theme-reno主题支持 Font Awesome 免费图标 (opens new window)

使用示例

{
	text: "首页",
	link: "/",
	icon: 'reco-home'
}

1
2
3
4
5

# 七、VuePress部署

VuePress部署官方文档（1.x） (opens new window)

# 7.1 GitHub部署

# 7.2 云服务器部署

# 八、VuePress资料

VuePress官网：https://vuepress.vuejs.org (opens new window)

VuePress中文文档：https://www.vuepress.cn (opens new window)

VuePress快速上手官方文档（1.x） (opens new window)

VuePress配置官方文档（1.x） (opens new window)

VuePress插件官方文档（1.x） (opens new window)

VuePress主题官方文档（1.x） (opens new window)

VuePress默认主题配置官方文档（1.x） (opens new window)

vuepress-theme-reco 官方文档（1.x） (opens new window)

vuepress-theme-reco 官方插件 (opens new window)

vuepress-theme-reco 官方插件广场 (opens new window)

VUE2实战 Jmeter

超炫之家

VuePress

VuePress

# 一、VuePress基础

# 1.1 VuePress简介

# 1.2 VuePress优点

# 1.3 VuePress组成

# 1.4 VuePress工作原理

# 1.5 VuePress目录结构

# 默认跟路径docs

# 目录结构描述

# 1.6 VuePress产出

# 1 文档主题的个人站点

# 2 博客主题的个人站点

# 二、VuePress上手

# 资源准备

# 前置安装

# 搭建步骤

# 创建项目

# 创建git忽略文件

# 创建目录结构

# 填充内容

# 在img添加图片

# 启动运行

# nginx部署

# 三、VuePress配置

# 四、VuePress插件

# 4.1 配置侧边栏激活跟随

# 4.2 配置代码复制

# 4.3 配置全文搜索

# 4.4 配置评论

# 4.5 配置随机名言

# 4.6 配置百度广告

# 4.7 配置百度统计

# 4.8 插件配置清单

# 五、VuePress主题

# 5.1 vuePress-theme-reno

# 六、VuePress开发

# 6.1 首页配置

# 6.2 在md文档中的配置

# 6.3 icon使用

# 七、VuePress部署

# 7.1 GitHub部署

# 7.2 云服务器部署

# 八、VuePress资料