大家好,我是鸿雁。不久之前,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 官方文档一样的界面风格:
暗黑模式:
响应式:
VitePress
整个网站项目是基于VitePress
来构建的,为何会选择 VitePress ,它又有什么优点呢?
首先,需要知道 Vitepress 是基于Vite
的基础上来构建的,并利用Vue3
改进模板静态分析尽可能字符串化静态内容。
它具有以下优点:
- 更快的开发服务启动
- 更快的热更新
- 更快的构建
另一方面,之所以选择 VitePress 还在于它推丛更少配置,更轻量页面的极简主义。
对于 VitePress 的使用,我们这里不过多介绍,大家可以前往官网查阅:
此外,我们还要谈谈其不足之处,当一个项目的导航菜单,边栏菜单比较多时,往往需要将其拆分到不同文件中进行配置并导入到主配置文件中使用。但 VitePress 对其配置文件中所导入的其他模块并不能监视热更新,这会导致我们的配置改动不生效,需要手动保存主配置文件才能触发热更新。虽然可以将所有配置融合到配置文件中来避免这个问题,但确实不利于代码阅读和管理。
最后我们总结一下:
VitePress = Vite + Vue3 + Markdown-It
主题
只有 VitePress 并不能实现像 Vue 官方文档一样的界面风格,项目还内置了一个主题插件:VitePress-Theme-Vue
。
VitePress-Theme-Vue 主题是基于@vue/theme
的基础上开发的。为什么不直接使用 @vue/theme 主题呢?
@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
项目地址:
VitePress-Theme-Vue
文档手册:
结语
create-docs
项目现在已经开源,欢迎各位感兴趣的小伙伴参与贡献提交 PR 或反馈 issue,给予 star 支持。
开始你的文档写作吧!
npm init @quick-start/docs
复制代码