VuePress 搭建站点

本文最后更新于:2022年9月22日 下午

VuePress 是静态站点生成框架之一,界面简介优雅,本文记录使用方法。

简介

  • VuePress 是尤雨溪(vue.js 框架作者)发布的一个全新的基于 vue 的静态网站生成器,实际上就是一个 vue 的 spa 应用,内置 webpack,可以用来写文档。
  • VuePress 有很多优点:
    • 界面简洁优雅,不同于 Hexo,个人觉得更适合作为说明文档页
    • 容易上手(半小时能搭好整个项目)
    • 更好的兼容、扩展 Markdown 语法
    • 响应式布局,PC端、手机端
    • Google Analytics 集成
    • 支持 PWA
  • 中文官网:https://vuepress.docschina.org/

安装

nodejs

  • VuePress 需要安装 Node.js,且版本要求 >= 8。

vuepress

  • 在 nodejs 平台下安装 vuepress
1
2
3
npm install -g vuepress
# 或
yarn global add vuepress

使用方法

创建框架

  • 以 Cellink 项目的说明文档为例,创建 cellink-docs 文件夹
1
mkdir cellink-docs 
  • 初始化项目
1
npm init -y
  • 在 VueDemo 文件夹中创建 docs 文件夹,在其中加入 README.md 文件,写入 hello world!
  • 在 docs 中创建 .vuepress 文件夹,在.vuepress中创建 public 文件夹和 config.js 文件,最终项目结构如下所示:
1
2
3
4
5
6
7
VueDemo 
├─── docs
│ ├── README.md
│ └── .vuepress
│ ├── public
│ └── config.js
└── package.json
  • 添加 vue-template-compiler 模块
1
npm install vue-template-compiler

配置站点信息

  • 在 config.js 文件中配置网站标题、描述、主题等信息
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
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
module.exports = {
locales: {
// 键名是该语言所属的子路径
// 作为特例,默认语言可以使用 '/' 作为其路径。
'/': {
lang: 'zh-CN', // 将会被设置为 <html> 的 lang 属性
title: 'Cellink 用户手册',
description: '一款可视化代码流程管理框架',
},
},
title: 'Cellink',
base: '/cellink-docs/',
head: [
['link', { rel: 'icon', href: '/imgs/icon.png' }],
['meta', { name: 'keywords', content: 'cellink,可视化,流程管理,cellink文档,用户文档'}]
],
themeConfig: {
locales: {
'/': {
// 多语言下拉菜单的标题
selectText: 'Languages',
// 该语言在下拉菜单中的标签
label: '🇨🇳 简体中文',
// 编辑链接文字
editLinkText: '帮助我们完善文档',
// 最后更新的描述
lastUpdated: '文档更新于',
// Service Worker 的配置
serviceWorker: {
updatePopup: {
message: '发现新内容可用.',
buttonText: '刷新',
},
},
nav: [
{ text: '开始使用', link: '/start/' },
{ text: '配置指南', link: '/guide/' },
{ text: '进阶用法', link: '/advance/' },
{ text: 'Cellink 实践', link: '/practice/' },
{ text: 'GitHub', link: 'https://github.com/viibridges/cellink' },
],
},
},
sidebar: 'auto',
// 假如你的文档仓库和项目本身不在一个仓库:
docsRepo: 'zywvvd/cellink-docs',
// 假如文档不是放在仓库的根目录下:
docsDir: 'docs',
// 假如文档放在一个特定的分支下:
docsBranch: 'source',
// 默认是 false, 设置为 true 来启用
editLinks: true,
}
};
  • 此时站点框架完成,已经可以进行初步测试,执行命令:
1
npm run dev

填充内容

  • 按照导航配置的 link 我们分别创建文件夹和对应的 markdown 文件
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
│  package.json
│ README.md

└─docs
│ README.md
├─.vuepress
│ │ config.js
│ └─public
├─advance
│ README.md
├─guide
│ README.md
├─practice
│ README.md
└─start
README.md
  • 如果需要图像资源,需要放在 public 文件夹下:
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
26
27
│  package.json
│ README.md

└─docs
│ README.md
├─.vuepress
│ │ config.js
│ ├─public
│ │ │ .nojekyll
│ │ │
│ │ └─imgs
│ │ adc-graph.png
│ │ bearing-graph.png
│ │ demo-graph.png
│ │ icon.png
│ │ node-types.png
│ │ nozzle-graph.png
│ │ quantum-graph.png
│ └───────── slogan.png
├─advance
│ README.md
├─guide
│ README.md
├─practice
│ README.md
└─start
README.md
  • 引用图片示例:
1
![](/imgs/adc-graph.png)

如果需要在 github 仓库中引用该图像,在前面加入仓库名称

1
![](/cellink-docs/imgs/adc-graph.png)

示例效果

  • 这样一个说明文档站点就创建完成了

生成静态文件

  • 部署时需要生成静态文件
1
npm run build
  • 得到静态文件后可以推送到服务器、Github Pages 等进行站点托管

示例工程

参考资料


VuePress 搭建站点
https://www.zywvvd.com/notes/tools/vuepress/usage/
作者
Yiwei Zhang
发布于
2022年9月22日
许可协议