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