用更合适的文档库！打造专属品质，尽显码农风采！

发布于：2024-04-28 ⋅ 阅读:(22) ⋅ 点赞:(0)

作者： 、

声明：本文为稀土掘金技术社区首发签约文章，30天内禁止转载，30天后未获授权禁止转载，侵权必究！

前言

这是一个之文档篇。

承接上文，我们已经知道了如何去实现一个 headless ui 无头组件的测试用例环节，那么我们继续往下走；

一个合格的组件工具等库，我们不仅要会知其然，更要知其所以然；

同时我们也要 高效的传播知识和技能 和 促进大家交流和协作，达到让别人开箱即用，尽量降低使用成本，提升大家的研发使用效率；

那么一个文档就必不可少了，而且还要一看秒懂的文档。

一、调研&对比

随着技术的发展，到了 4202 年，市面上已经有了许许多多的文档开源仓库可以开箱即用了；

有一键生成的，有高度可定制的，有支持多语言的；

我想选择哪个呢，你有你的决定，我这里就分析对比一下现在市面上用的较多的库。

1.

Storybook 是一个开源的 UI 组件开发与文档生成工具，广泛应用于 React、Vue、Angular、Svelte 等多种前端框架的组件开发环境；它可以让你独立于主应用程序创建和展示 UI 组件，并生成详细的文档。

优点：

  • 支持多种前端框架，高度可定制。
  • 提供交互式的组件演示和测试环境。
  • 强大的故事（stories）管理功能，利于组件的迭代和复用。
  • 丰富的插件生态系统，支持多种附加功能如可视化测试、性能监控等。

缺点：

  • 对于小型项目或简单组件集，搭建 Storybook 可能显得较为繁琐。
  • 学习曲线对于初次使用者可能稍陡峭。

2.

Docz 是一个专门为 React 组件编写的静态站点生成器，旨在简化组件文档的创建过程，并提供一种优雅的方式来演示和记录组件库。它利用 Markdown 和 MDX（Markdown 扩展）语法，允许开发者在撰写文档的同时直接嵌入 React 组件，从而实现对组件功能、API 和使用示例的可视化展示。

优点

  • 组件驱动：非常适合展示 React 组件库及其 API，让开发者能够快速理解和使用组件。
  • 即时反馈：内置热重载功能，编辑文档和组件时可立即在预览窗口看到变化。
  • 定制化：提供主题定制能力，可以根据项目需求打造个性化的文档界面。
  • 高性能：基于 Gatsby 构建，因此性能优化较好，生成的文档站点加载速度快。

缺点

  • 框架局限：相较于其他通用文档生成工具，Docz 更专注于 React 生态系统，对于非 React 组件的支持相对有限。
  • 社区支持与更新：随着类似工具的发展，Docz 社区活跃度和更新速度可能会随着时间变化而有所波动。
  • 配置灵活性：尽管 Docz 提供了一些高级配置选项，但对于一些极其复杂的定制需求，可能不如其他更成熟的静态站点生成器灵活。

3.

VuePress 是一个由Vue驱动的静态网站生成器，虽然主要用于写博客和文档，但它也可以用于构建组件文档库，特别是对于Vue.js项目。

VuePress 是由 Vue.js 作者尤雨溪创建的一个静态网站生成器，早期版本的 VuePress 使用 webpack 作为构建工具，支持丰富的插件体系和高度定制化。

优点：

  • 基于Vue.js，因此如果你的组件库是Vue的，那么集成起来相当自然。
  • 支持Markdown和Vue组件混合编写文档。
  • 提供了丰富的主题和插件系统，可以轻松定制文档样式。

缺点：

  • 对于非Vue项目的组件文档支持需要更多的自定义配置。

4.

VitePress 是一个基于 Vite 构建的静态网站生成器，旨在提供快速、简单和现代的文档编写和展示体验。它结合了 Vite 的快速开发能力和 Vue 3 的特性，适合用于构建各种类型的静态网站。

VitePress 是 VuePress 的“继承者”，由尤雨溪针对 Vue 3 和 Vite 技术栈设计的新一代静态网站生成器。

相比于 VuePress，VitePress 的配置更为简洁，去除了部分较为复杂的全局配置项，更注重开箱即用和轻量级体验。

优点

  • 快速开发体验：基于 Vite 的 HMR（Hot Module Replacement）技术，实现了近乎实时的页面刷新和代码更改同步。
  • 轻量级和高性能：精简的架构带来更小的构建体积和更快的加载速度，适合现代浏览器。
  • 易于使用：对于简单的静态站点和文档站点，VitePress 提供了直观易懂的配置和内容编写流程。
  • 原生模块支持：利用浏览器原生支持的 ES 模块导入，无需预先编译，简化了工作流程。
  • 内置 Vue 支持：无缝集成 Vue.js，允许在 Markdown 文件中使用 Vue 组件，增强文档的表现力。

缺点

  • 有限的可扩展性：VitePress 不像 VuePress 那样支持广泛的插件系统，这意味着如果需要非常特定的功能或者深度定制，可能需要自行修改底层代码或等待官方支持。
  • 成熟度与生态：相较于 VuePress，VitePress 的社区资源和插件生态相对较小，因为它是相对较新的项目。
  • 兼容性问题：VitePress 针对现代浏览器进行了优化，可能无法完美兼容所有旧版浏览器，特别是那些不支持原生 ES 模块的浏览器。

小结

选择哪个库取决于你的具体需求，比如使用的前端框架、是否需要实时预览、项目规模以及团队的技术栈。上述各工具都有各自的社区和成熟的文档支持，可以根据实际情况权衡选择。

因为我们主要是实现基于 Vue 的一个无头组件库，所以咱们最好的选择是 Vuepress 和 Vitepress ，但是它俩选哪个呢？

我们知道 VitePress 是一个面向未来的、轻便高效的静态网站生成器，特别适合那些重视开发效率、喜欢简洁工具链和技术栈现代化的开发者。

而对于需要大量自定义和拓展功能的大型项目， VuePress 或其他具有丰富插件生态的静态站点生成器可能是更好的选择。

所以这里咱们以 Vitepress 来作为咱们的文档基础库。

二、安装&使用

1) 安装

在之前的文章中，我们已经详细的告诉过大家为什么要使用文档了，而且最基本的文档库是如何实现的，详细的安装&使用过程可参见《》

为避免同学们难得跑一趟，我直接简单交代一下：

pnpm i vitepress -Dw

2) 初始化的 2 种方法（可二选一或自定义）

2.1 npx vitepress init 初始化

初始化：

npx vitepress init

回答几个简单的问题：

┌  Welcome to VitePress!
│
◇  Where should VitePress initialize the config?
│  ./test
│
◇  Site title:
│  My Awesome Project
│
◇  Site description:
│  A VitePress Site
│
◆  Theme:
│  ● Default Theme (Out of the box, good-looking docs)
│  ○ Default Theme + Customization
│  ○ Custom Theme
└

结果：

image.png

运行

pnpm docs:dev

image.png

2.2 自定义

# 1.创建 docs 文档
mkdir docs

# 2.初始化
cd docs && pnpm init

# 3.安装
pnpm i vitepress tailwindcss -D

# 4.配置 package.json 
"scripts": { 
    "docs:dev": "vitepress dev",
    "docs:build": "vitepress build",
    "docs:preview": "vitepress preview"
},

# 5. 运行
pnpm docs:dev

那么我们实现完之后在根目录下就有一个 docs 目录：

image.png

小结：两种方式建议：

建议两种方式结合；

因为第一种方式，会把 vitepress 相关的安装包全部安装到根目录，会显得整个根目录的 package.json 文件显得非常臃肿；

这个当你在docs文档中所需插件较多时，更加明显；

所以最终方案如下：

  1. 先使用第一种方式创建 docs 文件；
  2. 再在 docs 目录下 pnpm init 初始化；
  3. 安装vitepress相关包在 docs 目录下安装即可；

结果如下：

image.png

根目录配置 scripts：

"docs:dev": "vitepress dev docs",
"docs:build": "vitepress build docs",

运行效果会发现和第一种方式一样

好了，到这里，我们就初步搭建好了文档的基本目录，接下来我们就要开始一步一步的来分析使用了。

三、分析开源文档库（vite）

我们先看一下 vite 官方文档的主要页面：

image.png

image.png

根据图片咱们可以看得出来，其实一个文档库，可以主要分为如下部分：

  • 首页
    • 介绍
    • 导航
    • 等等
  • 主页面
    • 左边导航
    • 右边导航
    • 顶部导航
    • 内容部分
    • 搜索部分
    • 等等

所以我们根据以上各个部分，就可以来进行各个模块的配置；

正好，在 vitepress 中有一个叫做 config.ts 就很完美的诠释了相关配置；

接下来，我们就着手准备配置了。

四、改造首页index.md

---
# https://vitepress.dev/reference/default-theme-home-page
layout: home
sidebar: false

titleTemplate: 一个用于在 Vue 中构建高质量、可访问的 Headless UI的组件库

hero:
  name: YI UI
  text: Vue 集成的无头组件库
  tagline: 一个用于在 Vue 中构建高质量、可访问的 Headless UI的组件库
  image: # 这里放你的logo图片
    src: /logo.svg
    alt: YI UI
  actions:
    - theme: fast
      text: 快速开始
      link: /guide/index
    - theme: alt
      text: API Examples
      link: /api-examples
    - theme: GitHub
      text: View on GitHub
      link: https://github.com/jeddygong/yi-ui

features:
  - title: Vue, Nuxt supported.
    details: 支持以 Vue 构建的任何框架
    icon: <svg xmlns="http://www.w3.org/2000/svg" width="32" height="32"><path fill="#41b883" d="M24.4 3.925H30l-14 24.15L2 3.925h10.71l3.29 5.6 3.22-5.6Z"/><path fill="#41b883" d="m2 3.925 14 24.15 14-24.15h-5.6L16 18.415 7.53 3.925Z"/><path fill="#35495e" d="M7.53 3.925 16 18.485l8.4-14.56h-5.18L16 9.525l-3.29-5.6Z"/></svg>
  - title: 节约时间，运行速度快
    details: 节约时间，运行速度快
    icon: 🚀
  - title: 开箱即用的辅助功能
    details: 符合 WAI-ARIA 标准。支持键盘导航和焦点管理。
    icon: ⚡
  - title: 强类型支持
    details: 使用TypeScript编写,良好类型支持
    icon: 🦾
  - title: 开发体验完美
    details: 无样式，很容易自定义，非常适合高度自定义且设计要求较高的应用程序
    icon: 🛠
  - title: 轻量级
    details: 体积小巧
    icon: ☁️
  - title: 更多插件支持
    details: （建设中...）
    icon: 🔌
  - title: 更多功能
    details: （持续充电建设中...）
    icon: 🔋
---

新建 public 文件：主要放一些静态资源

mkdir public  

touch logo.svg

注意：放置在 public 中的资源将按原样复制到输出目录的根目录中，例如可以直接访问 logo.svg，而不需要 public/logo.svg。

运行后的效果：

image.png

五、配置 guide

根据上面的 index.md 文件中，我们有配置一个 action，并且路由地址 /guide；

因为 vitepress 是基于文件的路由，这意味着生成的 HTML 页面是从源 Markdown 文件的目录结构映射而来的。例如，给定以下目录结构：

.
├─ guide
│  ├─ getting-started.md
│  └─ index.md
├─ index.md
└─ prologue.md

生成的 HTML 页面会是这样：

index.md                  -->  /index.html (可以通过 / 访问)
prologue.md               -->  /prologue.html
guide/index.md            -->  /guide/index.html (可以通过 /guide/ 访问)
guide/getting-started.md  -->  /guide/getting-started.html

所以我们先配置一个简单的 guide：

  1. 运行命令：
  2. mkdir guide
  3. touch guide/index.md

编辑 guide/index.md 文件：

---

title: 快速开始
description: 快速让你掌握 YI UI 的教程
name: popover
---

# 快速开始

<Description>

快速让你掌握 YI UI 的教程。

</Description>

## 安装

npm i @yi-ui/vue
pnpm i @yi-ui/vue
yarn add @yi-ui/vue

## 简单使用
...

但是我们运行结束后打开 guide 路由：

image.png

到这里，我们就配置好了最基本的新手指引了，内容这些就完全在于你的自定义了。

细心的同学，可能会发现，该页面的左边导航和顶部的导航，我们还没有处理，所以为了更加完善，我们需要一个一个的处理。

在完善前，我们先简单的都熟悉一下 .vitepress/config.ts 的基本配置

六、配置 config.ts

在配置 config.ts 之前，我们要先熟悉一下 vitepress config 的一些最基本的 API，这样咱们接下来配置才会事半功倍。

熟悉一下基本的常用的 API：

  1. title：站点的标题。使用默认主题时，这将显示在导航栏中。
  2. titleTemplate：允许自定义每个页面的标题后缀或整个标题。
  3. description：站点的描述。这将呈现为页面 HTML 中的 <meta> 标签。
  4. head：要在页面 HTML 的 <head> 标签中呈现的其他元素。用户添加的标签在结束 head 标签之前呈现，在 VitePress 标签之后。
  5. lang：站点的 lang 属性。这将呈现为页面 HTML 中的 <html lang="en-US"> 标签。
  6. base：站点将部署到的 base URL。如果计划在子路径例如 GitHub 页面）下部署站点，则需要设置此项。
  7. cleanUrls：当设置为 true 时，VitePress 将从 URL 中删除 .html 后缀。
  8. srcDir：相对于项目根目录的 markdown 文件所在的文件夹。
  9. outDir：项目的构建输出位置，相对于项目根目录。
  10. assetsDir：指定放置生成的静态资源的目录。
  11. appearance：是否启用深色模式
  12. lastUpdated：是否使用 Git 获取每个页面的最后更新时间戳。
  13. markdown：配置 Markdown 解析器选项。
  14. vite：将原始 Vite 配置传递给内部 Vite 开发服务器 / bundler。
  15. ：自定义主题
    • logo：导航栏上显示的 Logo
    • siteTitle：可以自定义此项以替换导航中的默认站点标题 (应用配置中的 title)
    • nav：顶部导航菜单项的配置。
    • sidebar：侧边栏菜单项的配置。
    • outline：显示标题的级别
    • socialLinks：可以定义此选项以在顶部右侧导航栏中展示带有图标的社交帐户链接，例如 github。
    • editLink：编辑链接可让显示链接以编辑 Git 管理服务 (例如 GitHub 或 GitLab) 上的页面。
    • lastUpdated：允许自定义上次更新的文本和日期格式。
    • algolia：搜索站点文档

当然还有一些其它的配置 API，但是也不常用，所以大家只需要知道即可；

如果想知道全部，可参见

基本的简单配置：

到这里我们知道了基本的一个配置 API，所以接下来我们就开始一个最基本的简单配置吧

import { defineConfig } from 'vitepress'
// https://vitepress.dev/reference/site-config
export default defineConfig({
    title: "YI UI",
    titleTemplate: ':title - headlessui.dev',
    description: '一个用于在 Vue 中构建高质量、可访问的 Headless UI的组件库',
    cleanUrls: true,
})

运行后的结果：

image.png

当然这最基本的配置很显然不满足我们的需求；

我们上面有分析一个开源库有顶部导航、有侧边导航等等，所以我们接下来就要着手配置顶部导航和侧边导航了。

七、改造顶部导航 Nav 部分

如何配置顶部导航，我们上面有讲解配置 API 的时候有一个 themeConfig 的 API，它有一个属性叫 nav，这个属性非常重要，也是配置导航的最重要的工具；

编辑config.ts：

import { defineConfig } from 'vitepress'
import { version } from '../../package.json'

// https://vitepress.dev/reference/site-config
export default defineConfig({
    title: "YI UI",
    titleTemplate: ':title - headlessui.dev',
    description: '一个用于在 Vue 中构建高质量、可访问的 Headless UI的组件库',
    cleanUrls: true,
    themeConfig: {
    // https://vitepress.dev/reference/default-theme-config
        nav: [
            { text: '指南', link: '/guide/' },
            { text: '文档', link: '/markdown-examples' },
            {
                text: `v${version}`,
                items: [
                    {
                        text: 'Release Notes ',
                        link: 'https://github.com/jeddygong/yi-ui/releases',
                    },
                ],
            },
        ],
    }
})

运行结果：

image.png

八、改造左边导航 sidebar

编辑config.ts：

themeConfig: {
    sidebar: [
        {
            text: '简介',
            collapsed: false,
            items: [
                { text: '介绍', link: '/markdown-examples' },
                { text: '快速开始', link: '/api-examples' },
                { text: '无障碍', link: '/api-examples' },
                { text: '发布', link: '/api-examples' },
            ],
        },
        {
            text: '指南',
            collapsed: false,
            items: [
                { text: '贡献指南', link: '/api-examples' },
                { text: '参考指南', link: '/api-examples' },
            ],
        },
    ],
}

运行结果：

image.png

总结

到这里，我们文档的一些基本配置就介绍完毕了；

但是我们我们还可以拓展，这取决于每个文档的功能点，例如：

  • 搜索功能
  • 页脚功能
  • 中英功能
  • md文档插件
  • 等等

这些功能和项目的耦合度都比较高，就不在这篇文章详细介绍了，大家可以自行了解；

我们只需要知道能实现我们想要的效果即可。

接下来的安排：

  • 构建版本发布
  • 支持 Nuxt 调试

Headless UI 往期相关文章：

Headless UI (1).png

如果想跟我一起讨论技术吹水摸鱼， 欢迎加入

如果想一起讨论技术：欢迎加入技术讨论群

如果想一起吹水摸鱼：欢迎加入吹水摸鱼群

如果想一起老司机吹水摸鱼：欢迎加入老司机吹水摸鱼群（懂得都懂）

如果扫码人数满了，可以扫码添加个人 vx 拉你：

感谢大家的支持，码字实在不易，其中如若有错误，望指出，如果您觉得文章不错，记得 点赞关注加收藏 哦 ~

，带您一起搞前端 ~

网站公告

今日签到

点亮在社区的每一天
去签到

热门文章

最新发布