vuepress实践录：初步入门

vue 1.6k 字 次

本文初步介绍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