Skip to main content

通过 VuePress 创建文档类网站

已经发展到 v2 了,文档 https://v2.vuepress.vuejs.org/zh/

changelog 可以了解到,从 2021 年开始 beta 至今了,可算比较成熟。

本文档将以最新的 v2 为基础展开。

VuePress 优势

  • 生态好,例如主题、插件、用户数都比较多。
  • 官方支持度好,很多官方插件非常好用。

社区资源

官方主题功能比较基础,先过一遍目前可用的插件更佳。 https://github.com/vuepress/awesome-vuepress/blob/main/v2.md

官方支持的本地搜索插件

太好用了,不需要 docsearch 那么麻烦。同时是官方的插件,成熟度比较高,能在默认主题下开箱即用。

https://v2.vuepress.vuejs.org/zh/reference/plugin/search.html#search

Markdown 文档里面的 script 标签要加 setup 才有效

<script setup> 里面 import 的组件才能在该 Markdown 里面使用。

使用 tailwindcss

Step-1 - 修改默认的 vite 相关配置

docs/.vuepress/config.js
import { viteBundler } from '@vuepress/bundler-vite'
import { defineUserConfig } from '@vuepress/cli'
import autoprefixer from 'autoprefixer'
import tailwindcss from 'tailwindcss'

export default defineUserConfig({
bundler: viteBundler({
viteOptions: {
css: {
postcss: {
plugins: [
autoprefixer,
tailwindcss
]
}
}
},
vuePluginOptions: {},
}),
})

注意点:

  • 要先 import xxx 不能在 plugins 里面直接 require('xxx'),会报错 Error: Dynamic require of "autoprefixer" is not supported

Step-2 - 使 tailwindcss 相关功能对 docs 目录下的文件生效

/** @type {import('tailwindcss').Config} */
module.exports = {
content: [
"./docs/**/*.{vue,js,ts,jsx,tsx,md}",
],
theme: {
extend: {},
},
plugins: [],
}

特别注意要加 md 格式。

Step-3 样式文件引入 @tailwind xxx

示例 - 局部引入

要在 md 文件的 style 标签:

<style lang="less" scoped>
@tailwind base;
@tailwind components;
@tailwind utilities;
</style>

示例 - 全局引入

全局样式文件:

/docs/.vuepress/styles/index.scss
@tailwind base;
@tailwind components;
@tailwind utilities;

解决引入 tailwind 以后项目基础样式被修改的问题

引入 @tailwind base 会跟 VuePress 的默认样式有冲突。因为 Preflight will be injected here。 例如 Mardown 里面的 h1/h2/h3 等等会被 Tailwindcss 重置成无样式的正文文本(因为 tailwindcss 是通过 text-xxx 类去控制字体大小的)。

但不引入的话,很多 tailwind 自带的基础类无法使用。

解决方式是禁用 Preflight:https://tailwindcss.com/docs/preflight#disabling-preflight

module.exports = {
corePlugins: {
preflight: false,
}
}

边框颜色变量是 --c-border

自定义的页面元素为了和主题颜色(包括深色/浅色)更协调,经常要用到全局的边框颜色变量:

border: 1px solid var(--c-border);

预定义 CSS 变量参考:https://v2.vuepress.vuejs.org/zh/reference/default-theme/styles.html#style-%E6%96%87%E4%BB%B6

添加本地搜索功能

https://v2.vuepress.vuejs.org/zh/reference/plugin/search.html#search

配置 @ 前缀指向项目根目录

我们写文档站一般是服务于指定项目,将项目中所有要传达的内容都编写文档。

因此,一般会将 VuePress 跟项目代码放在同一个仓库中,方便引用项目代码做示例。例如目录目录结构如下:

project/
├─ src/ # 项目代码
└─ docs/ # 文档目录
└─ .vuepress/ # VuePress 目录
└─ config.js # 配置文件

为了方便引入项目代码,需要将 @ 前缀自动修改为项目根目录,对应的配置如下:

/docs/.vuepress/config.js
import { viteBundler } from '@vuepress/bundler-vite'
import { defineUserConfig } from '@vuepress/cli'
import { fileURLToPath, URL } from 'node:url'

export default defineUserConfig({
bundler: viteBundler({
viteOptions: {
resolve: {
alias: {
'@': fileURLToPath(new URL('../../', import.meta.url))
}
},
}),
})

添加全局样式

https://v2.vuepress.vuejs.org/zh/reference/default-theme/styles.html#style-%E6%96%87%E4%BB%B6

文件的路径 .vuepress/styles/index.scss

默认主题自带的主页

v2 文档:https://v2.vuepress.vuejs.org/zh/reference/default-theme/frontmatter.html#%E9%A6%96%E9%A1%B5

v1 文档:https://v1.vuepress.vuejs.org/zh/theme/default-theme-config.html#%E9%A6%96%E9%A1%B5

注意两个版本关于首页的 frontmatter 配置会有细微差别。

允许 Markdown 内容中的回车转成换行

默认是严格遵循 markdown 的语法定义,要行尾两个空格才会转换行。既不符合我们的写作习惯,也容易出现 markdown 原始内容在实际预览时,排版不符合预期的情况。

/docs/.vuepress/config.js
import { defineUserConfig } from '@vuepress/cli'

export default defineUserConfig({
markdown: {
breaks: true, // Convert '\n' in paragraphs into <br>
}
})

markdown 配置详解 (markdown-it Github): https://github.com/markdown-it/markdown-it#init-with-presets-and-options

VuePress 关于 markdown 的说明:https://v2.vuepress.vuejs.org/zh/reference/config.html#markdown

默认主题的 CodeGroupItem 注意事项

  • 必须配合 CodeGroup 使用,否则一片空白渲染无效。
  • <CodeGroupItem></CodeGroupItem> 里面的 Markdown 内容相对于 <CodeGroupItem> 不能有缩进,否则会识别失败(markdown-it 无法将其渲染成 SFC 合法模板)。
  • <CodeGroupItem></CodeGroupItem> 里面只有合法的 SFC 模板标签,则不受影响,怎么缩进都可以正常渲染。

其它注意点看文档:https://v2.vuepress.vuejs.org/zh/reference/default-theme/components.html#codegroupitem

添加 jsx 支持

VuePress 内置的 Vite 没有配 VueJsx 这个插件,需要手动添加。

/docs/.vuepress/config.js
import { defineUserConfig } from '@vuepress/cli'
import { viteBundler } from '@vuepress/bundler-vite'
import vueJsx from '@vitejs/plugin-vue-jsx'

export default defineUserConfig({
bundler: viteBundler({
viteOptions: {
plugins: [vueJsx()],
)}
)}

@[code] 语法支持 @ 指向项目源码 src/ 目录

以下假设文档目录 docs/ 与源码目录 src/ 同级。

/docs/.vuepress/config.js
import { defineUserConfig } from '@vuepress/cli'

export default defineUserConfig({
markdown: {
importCode: {
handleImportPath: (str) =>
str.replace(/^@/, '../../src'),
},
},
)}

TOC Table of Contents

默认能在 markdown 下使用 [[toc]] 生成目录,它的机制是用了 markdown-it 的插件。

增强版,可以用 <toc /> 组件,任何地方都能用,是官方开发的 VuePress 插件,可以阅读源码了解。 https://v2.vuepress.vuejs.org/zh/reference/plugin/toc.html

要注意两者的区别,虽然最终呈现的样式是一样的,但机制不同,生成的代码也不同。

定制 VuePress 的相关技巧

在页面上渲染输出 Markdown 内容

有个全局组件,叫做 <content />。 只要你的模板上有该标签,它就会渲染输出 Markdown 内容。

例如在你的 .vuepress/layouts/Layout.vue 里面加上 <content /> 就可以直接变成最简陋的文档模板了。

// your_project/vuepress.client.js
import { defineClientConfig } from '@vuepress/client'
import Layout from './layouts/Layout.vue'

export default defineClientConfig({
layouts: {
Layout
}
})
<!-- your_project/layouts/Layout.vue -->
<template>
<content />
</template>

要定制自己的 VuePress 此项知识点必备。

更改默认 docs 文档目录

通常,我们的文档站(例如 VuePress/Docsify 等)以及 Markdown 文档源文件都是互相独立的。

因此有将 VuePress 的文档目录,改为实际 Markdown 文档源文件目录的需要。

如下分析过程:

首先,VuePress 并没有硬性要求目录结构必须是 $root/docs/ 存放 Mardown 文档。 在官方文档的指引中,要求在 package.json 中添加如下 script:

{
"scripts": {
"docs:dev": "vuepress dev docs",
"docs:build": "vuepress build docs"
}
}

我们可看出,指定的文档目录 docs 是在 cli 中传参的。

因此,改为 vuepress dev ${your_docs_dir} 即可将根目录作为文档目录。

验证:有关 cli 的文档有说明传参用途 https://v2.vuepress.vuejs.org/zh/reference/cli.html#dev

多个 VuePress 文档实例共用同一个 docs 目录

由于 VuePress 的缓存文件默认是 ${source_dir}/.vuepress/,因此多个实例必然会造成冲突。

我们需要修改相关缓存至各实例自己的目录。

https://v2.vuepress.vuejs.org/zh/reference/config.html#dest

V2 版本的官方插件安装要加后缀 @next

1.x 版本:

npm install -D @vuepress/plugin-search

2.x 版本:

npm install -D @vuepress/plugin-search@next