只用一行命令!快速构建像Vue最新官方文档一样的网站

2,313 阅读4分钟

大家好,我是鸿雁。不久之前,Vue3 官方文档焕然一新,这次改变令人称赞。作为开发人员,为自己作品编写技术文档也是一项重要的能力。下面我们就来详细介绍,如何用命令行脚手架的方式,快速构建一个像 Vue 最新官方文档一样的网站。

快速开始

在命令行中执行以下命令:

npm init @quick-start/docs

该命令将安装并执行脚手架工具 create-docs。你将看到一些可选功能的提示,例如主题和 TypeScript 支持:

✔ Project name: … <my-docs>
✔ Select a theme: › vue
✔ Add TypeScript? … No / Yes

Scaffolding project in ./<my-docs>...
Done.

创建项目后,按照说明安装依赖项并启动开发服务器:

> cd <my-docs>
> npm install
> npm run dev

项目主体目录结构:

.
├──.vitepress
│  ├──theme
│  │  └──index.ts
│  └──index.ts
├──.vscode
├──docs
│  ├──public
│  │  └──...
│  ├──...
│  └──index.md
├──.editorconfig
├──.prettierrc.yaml
├──env.d.ts
├──package.json
└──tsconfig.json

展示

与 Vue 官方文档一样的界面风格:

create-docs.gif

暗黑模式:

create-docs.png

响应式:

z.jpg

VitePress

整个网站项目是基于VitePress来构建的,为何会选择 VitePress ,它又有什么优点呢?

首先,需要知道 Vitepress 是基于Vite的基础上来构建的,并利用Vue3改进模板静态分析尽可能字符串化静态内容。

它具有以下优点:

  • 更快的开发服务启动
  • 更快的热更新
  • 更快的构建

另一方面,之所以选择 VitePress 还在于它推丛更少配置更轻量页面的极简主义。

对于 VitePress 的使用,我们这里不过多介绍,大家可以前往官网查阅:

vitepress.vuejs.org/

此外,我们还要谈谈其不足之处,当一个项目的导航菜单,边栏菜单比较多时,往往需要将其拆分到不同文件中进行配置并导入到主配置文件中使用。但 VitePress 对其配置文件中所导入的其他模块并不能监视热更新,这会导致我们的配置改动不生效,需要手动保存主配置文件才能触发热更新。虽然可以将所有配置融合到配置文件中来避免这个问题,但确实不利于代码阅读和管理。

最后我们总结一下:

VitePress = Vite + Vue3 + Markdown-It

主题

只有 VitePress 并不能实现像 Vue 官方文档一样的界面风格,项目还内置了一个主题插件:VitePress-Theme-Vue

VitePress-Theme-Vue 主题是基于@vue/theme的基础上开发的。为什么不直接使用 @vue/theme 主题呢?

desc.png

@vue/theme 存在一些硬编码和bug,也许开发之初就没有为其通用性考虑,只为 Vue 官网打造。

VitePress-Theme-Vue@vue/theme 不同之处,或者说做了哪些优化工作:

  • 移除硬编码,让其更通用
  • 优化样式,更好看
  • 支持公共目录下部署(这部分 @vue/theme 存在若干 bug)
  • 支持YAML配置主页(@vue/theme 无主页功能)
  • 更多实用组件支持(如Tag等)

对于这些优化工作,并不是通过 Fork 方式来修改代码实现,而是仍然依赖它,以获得更新和维护支持,不重复造轮子。

具体改造工作从两方面入手:

一方面,基于 @vue/theme 导出的 Layout 布局组件插槽(slots),重新编写组件对硬编码组件进行覆盖,再导出新的 Layout 布局组件。

另一方面,在前文中提到 VitePress 的本质核心还是 Vite,我们可以通过编写 Vite 插件,在构建编译时将相关组件进行替换。以下是 Vite 插件代码示例:

const bugFix = function () {
  return {
    name'replace-navbar',
    enforce'pre',
    transform(code, id) {
      if (id.includes('VPNavBarTitle.vue') {
        return `
        // Replace Component Code
        `
      }
    }
  }
}

同时,我们将这些配置变更重新导出以便使用者扩展使用:

const baseConfig = require('@vue/theme/config')

module.exports = async () => {
  let config = await baseConfig()
  config.vite.plugins = [bugFix()]
  //...
  return config
}

在使用 VitePress-Theme-Vue 主题时,需在 VitePress 配置文件中继承配置:

// .vitepress/config.js
import { defineConfig } from 'vitepress'
import baseConfig from 'vitepress-theme-vue/config'

export default defineConfig({
  extends: baseConfig,
  themeConfig: {
    // ...
  }
})

上述方式也给我们一个思考,有时我们可以通过这种方式来紧急修复一些第三方组件bug,而不是干等。

VitePress-Theme-Vue 项目地址:

github.com/alex8088/vi…

VitePress-Theme-Vue 文档手册:

alex8088.github.io/vitepress-t…

结语

create-docs项目现在已经开源,欢迎各位感兴趣的小伙伴参与贡献提交 PR 或反馈 issue,给予 star 支持。

github.com/alex8088/qu…

开始你的文档写作吧!

npm init @quick-start/docs