原创 Gitbook 迁移至 Vuepress 2,真香

用 Gitbook 是几年前的事情,用来做产品文档,效果确实不错。最近换了新电脑,安装 Gitbook 的环境非常坎坷,官方好几年也没更新版本,于是尝试一下 VuePress。

先说结论, VuePress 如同 Vuejs 一样,可以惊艳到我:非常美观的样式、对手机端非常友好、单页应用加载速度块、更新实时预览速度快。

1. 准备 VuePress 环境

1.1 初始化环境

参照 VuePress 2.0 官方文档的快速上手部分open in new window,完成 VuePress 的基础环境配置。

请确保你已经可以通过 npm run docs:dev 来打开开发环境。

1.2 设置站点配置文件

创建 docs/.vuepress/config.js

module.exports = {
  lang: 'zh-CN',
  title: '你好, VuePress !',
  description: '这是我的第一个 VuePress 站点',

  themeConfig: {
    logo: 'https://vuejs.org/images/logo.png',
  },
}
1
2
3
4
5
6
7
8
9

2. 常见用法

运行开发环境

npm run docs:dev
1

生成静态网页

npm run docs:build
1

支持站内搜索

支持两种搜索方式,本站使用的是 本地搜索open in new window

原创 填写原创标识

使用内置的 Badge 组件open in new window

<Badge type="warning" text="原创" vertical="middle" />
1

3.高级用法

register-components

参照 官方文档open in new window,根据组件文件或目录自动注册 Vue 组件

npm i @vuepress/plugin-register-components@2.0.0-beta.23
1

支持自定义 CSS 样式

.vuepress/styles/index.scss 中添加即可,详见 文档open in new window

本站支持 IPv6 HTTPS 访问 一样。

<span id="ipv6">IPv6</span> <span id="ipv6">HTTPS</span>
1
#ipv6
{
    display:inline-block;
    margin-left:4px;
    padding:0 5px;
    border:1px solid #9da3a6;
    border-radius:2px
}
1
2
3
4
5
6
7
8

将 vuepress 运行在 K8S 上

详见文章 Vuepress 部署在 K8S 上

定义 Head 内元素

module.exports = {
    head: [
      ['link', { rel: 'icon', href: '/favicon.ico' }],
      ['meta', { name: 'xxx', content: 'yyy' }]
      ],
}
1
2
3
4
5
6

FAQ

TypeError: Cannot set property 'list' of undefined

使用 axios 发起 HTTP 请求时提示 TypeError: Cannot set property 'list' of undefined

then 的内部不能使用 Vue 的实例化的 this , 因为在内部 this 没有被绑定。

解决办法:

在请求 axios 外面定义一下 var that=this

ReferenceError: path is not defined

开启 register-componentsopen in new window ,出现 ReferenceError: path is not defined 报错

npm run docs:dev

> docs:dev
> vuepress dev docs

ReferenceError: path is not defined
    at Object.<anonymous> (/Users/dhcp/book/docs/.vuepress/config.js:76:26)
    at Module._compile (node:internal/modules/cjs/loader:1095:14)
    at Object.Module._extensions..js (node:internal/modules/cjs/loader:1124:10)
    at Module.load (node:internal/modules/cjs/loader:975:32)
    at Function.Module._load (node:internal/modules/cjs/loader:816:12)
    at Module.require (node:internal/modules/cjs/loader:999:19)
    at require (node:internal/modules/cjs/helpers:93:18)
    at loadUserConfigEs (/Users/dhcp/book/node_modules/@vuepress/cli/lib/config/loadUserConfigEs.js:9:22)
    at Object.loadUserConfig (/Users/dhcp/book/node_modules/@vuepress/cli/lib/config/loadUserConfig.js:16:20)
    at Object.resolveDevUserConfig (/Users/dhcp/book/node_modules/@vuepress/cli/lib/commands/dev/resolveDevUserConfig.js:43:39).
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16

.vuepress/config.js 首行添加 const { path } = require('@vuepress/utils') 即可。

[Vue warn]: Failed to resolve component

参照 register-componentsopen in new window 注册了组件,渲染失败,Chrome 控制台有如下报错,

[Vue warn]: Failed to resolve component
1

下面是本机环境信息。

# vuepress info

Environment Info:

  System:
    OS: macOS 11.4
  Binaries:
    Node: 16.5.0 - /usr/local/bin/node
    Yarn: Not Found
    npm: 7.20.0 - /usr/local/bin/npm
  Browsers:
    Chrome: 92.0.4515.131
    Edge: Not Found
    Firefox: Not Found
    Safari: 14.1.1
  npmPackages:
    @vuepress/core:  2.0.0-beta.22
    @vuepress/theme-default:  2.0.0-beta.22
    vuepress: ^2.0.0-beta.22 => 2.0.0-beta.22
  npmGlobalPackages:
    vuepress: 1.8.2
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21

安装插件 @vuepress/plugin-register-components@2.0.0-beta.23 即可解决。

npm i @vuepress/plugin-register-components@2.0.0-beta.23
1

TypeError: Invalid value used as weak map key

$ npm run docs:build

> docs:build
> vuepress build docs

info Initializing VuePress and preparing data...
✔ Compiling with webpack - done
✖ Rendering pages - failed
TypeError: Invalid value used as weak map key
    at WeakMap.set (<anonymous>)
    at normalizePropsOptions (/Users/bigdatabook/book/node_modules/@vue/runtime-core/dist/runtime-core.cjs.prod.js:2775:15)
    at createComponentInstance (/Users/bigdatabook/book/node_modules/@vue/runtime-core/dist/runtime-core.cjs.prod.js:5546:23)
    at renderComponentVNode (/Users/bigdatabook/book/node_modules/@vue/server-renderer/dist/server-renderer.cjs.prod.js:181:22)
    at ssrRenderComponent (/Users/bigdatabook/book/node_modules/@vue/server-renderer/dist/server-renderer.cjs.prod.js:517:12)
    at ssrRender (/Users/bigdatabook/book/docs/.vuepress/dist/.server/647.app.js:127:48)
    at script.ssrRender (/Users/bigdatabook/book/docs/.vuepress/dist/.server/647.app.js:139:10)
    at renderComponentSubTree (/Users/bigdatabook/book/node_modules/@vue/server-renderer/dist/server-renderer.cjs.prod.js:247:13)
    at renderComponentVNode (/Users/bigdatabook/book/node_modules/@vue/server-renderer/dist/server-renderer.cjs.prod.js:198:16)
    at renderVNode (/Users/bigdatabook/book/node_modules/@vue/server-renderer/dist/server-renderer.cjs.prod.js:288:22)
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19

重点看这 2 行

    at ssrRender (/Users/bigdatabook/book/docs/.vuepress/dist/.server/647.app.js:127:48)
    at script.ssrRender (/Users/bigdatabook/book/docs/.vuepress/dist/.server/647.app.js:139:10)
1
2

打开这个文件就知道了,引用了不存在的组件。 排查出除原因是首页 Markdown 中引用 vue component标签的内容为空,添加一个空格就解决了。

错误

<IndexSearch></IndexSearch>
1

正确为

<IndexSearch />
1