vuepress实践录:初步入门

初试

环境

安装 yarn,并添加国内源:

1
2
3
npm install -g yarn

yarn config set registry "https://registry.npm.taobao.org"

初始化

创建并进入一个新目录

1
mkdir vuepress-starter && cd vuepress-starter

初始化:

1
yarn init

注:在 Windows 下用 cmd 执行。用 git bash 会报错:

1
error An unexpected error occurred: "Can't answer a question unless a user TTY".

生成如下 package.json

1
2
3
4
5
6
{
"name": "vuepress-starter",
"version": "1.0.0",
"main": "index.js",
"license": "MIT"
}

注:可以只使用 cmd 生成 json 文件,或手动写 json 文件。再用回 git bash。

运行

(官方当前推荐)本地安装 vuepress:

1
yarn add -D vuepress

会生成 node_modules目录(通过 yarn 安装的插件、主题等在此目录)。

创建一篇文档:

1
mkdir docs && echo '# Hello VuePress' > docs/README.md

在 package.json 中添加 scripts,以便执行:

1
2
3
4
"scripts": {
"dev": "vuepress dev docs",
"build": "vuepress build docs"
},

启动服务器:

1
yarn dev

即可用浏览器访问本地 8080 端口,观看效果。

如需构建静态页面,执行:

1
yarn build

注:构建后在 docs 下有 .vuepress/dist目录,dist 即为静态网站文件所在目录。将其放到其它 web 服务器的资源目录中,即为网站。

**注意:官方使用 docs 目录作为工程目录,为了不让目录过深,也可以不使用,此时vuepress dev docs改为vuepress dev即可。

进阶

创建目录和文件:

1
2
mkdir -p docs/.vuepress docs/.vuepress/public
touch .vuepress/config.js

注:.vuepress 目录为 vuepress 的配置根目录。所有的配置文件均在其下。public 为公共访问目录,可存放 icon、logo等资源,config.js 是配置文件,非常重要。

修改 docs/README.md 文件:

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
---
home: true
heroImage: /hero.png
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
---

下面是常规 markdown 文件。
# Hello VuePress theme!
这是中文示例。
上面这句最后空了2个空格,预期效果应为换行。

上上面这句后多了一个窄,预期效果应该是空了一行。

## 这是二级header

### This is 三级标题

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
module.exports = {
title: '大锤与大妞', // 设置网站标题
description: '大锤与大妞的网站',
head: [
['link', { rel: 'icon', href: '/favicon.ico' }], // favicon.ico在public目录
],
// markdown 的配置
markdown: {
lineNumbers: false // 代码块显示行号
},
themeConfig: {
logo: '/logo.png',
// repo: 'https://github.com/latelee', // 不使用
sidebar: 'auto',
sidebarDepth: 2,
activeHeaderLinks: false, // 默认值:true 禁用活动的标题链接
// 默认值是 true 。设置为 false 来禁用所有页面的 下一篇 链接
nextLinks: true,
// 默认值是 true 。设置为 false 来禁用所有页面的 上一篇 链接
prevLinks: true,
smoothScroll: true,
nav: [
{ text: 'Home', link: '/' },
{ text: 'Guide', link: '/guide/' },
{ text: 'External', link: 'https://google.com' },
// 子导航条
{
text: 'Languages',
ariaLabel: 'Language Menu',
items: [
{ text: 'Chinese', link: '/language/chinese/' },
{ text: 'Japanese', link: '/language/japanese/' }
]
},
// 子导航条的分组
{
text: 'Languages',
items: [
{ text: 'Group1', items: [
{ text: 'Chinese1', link: '/language/chinese/' },
{ text: 'Japanese1', link: '/language/japanese/' }
] },
{ text: 'Group2', items: [
{ text: 'Chinese2', link: '/language/chinese/' },
{ text: 'Japanese2', link: '/language/japanese/' }
] }
]
}
]
}
}

注:favicon.ico、logo.png、hero.png等在 public 目录。

主题

获取默认主题:

1
yarn vuepress eject

在当前目录的 .vuepress 有 theme 目录,其下即为默认主题所有文件。
将 theme 目录放到 docs/.vuepress 目录下。

扩展

文章加密插件:

1
yarn add -D @oak-tree-house/vuepress-plugin-encrypt

参考:
https://www.imaegoo.com/2020/vuepress-encrypt/ https://szp15.com/2020/02/04/plugin-encrypt-doc/
还不成功

知识点

路径路由默认使用目录的 README.md 文件。
markdown 有扩展功能。
vuepress 大部分文件都支持热更新,但有的配置可能不会,如 config.js,需要重启服务。当修改 markdown 文档时,浏览器会自动刷新。
主题可继承,从默认主题继承。
执行vuepress无命令,使用yarn vuepress代替。

markdown 小记录:

1
2
3
4
站内跳转,/表示从根目录开始
[XXX](/doc/foo/XXX.md)
插入当前目录的图片,默认情况下路径和图片名称不能有中文
![XXX](./01.png)

内嵌 vue 代码:

1
2
// 循环,输出1 2 3
<span v-for="i in 3">{{ i }} </span>

问题及解决

支持中文名称图片。
安装:

1
yarn add markdown-it-disable-url-encode

.vuepress/config.js添加:

1
2
3
4
5
6
7
8
9
module.exports = {
// .....
markdown: {
// ......
extendMarkdown: md => {
md.use(require("markdown-it-disable-url-encode"));
}
}
};

另一个主题的安装

下载新版本node http://npm.taobao.org/mirrors/node/v16.2.0/,双击安装之。

在某目录执行:

1
yarn create vuepress-theme-hope vue-hope

一路回车即可。进入vue-hope目录,执行:

1
yarn install

注:该主题依赖的node版本必须高于13.7。 修改后的package.json:

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
{
"name": "vuepress-theme-hope-project",
"version": "1.0.0",
"description": "A project of vuepress-theme-hope",
"license": "MIT",
"scripts": {
"build": "vuepress build",
"clean-dev": "vuepress dev --no-cache",
"dev": "vuepress dev",
"eject-theme": "vuepress eject-hope"
},
"devDependencies": {
"vuepress": "^1.8.2",
"vuepress-theme-hope": "^1.17.2"
}
}

常用命令:

1
2
3
4
5
6
7
启动服务:
yarn run dev
生成网页:
yarn run build
导出主题(在.vuepress下):
yarn run eject-theme

参考:https://vuepress-theme-hope.github.io/zh/guide/

资源

参考:
快速上手:https://vuepress.vuejs.org/zh/guide/
主题:https://vuepress.vuejs.org/zh/theme/
资源(主题、插件):https://github.com/vuepress/awesome-vuepress
默认主题:https://github.com/vuejs/vuepress 仓库 packages/@vuepress 目录
主题:
https://github.com/xuzhongpeng/vuepress-theme-reform
https://github.com/vuepress-reco/vuepress-theme-reco
https://github.com/xugaoyi/vuepress-theme-vdoing

查看 markdown 中支持语法的语言名称:https://prismjs.com/#languages-list

李迟 2021.4.30