搭建前端组件库文档最佳姿势:Docz

简介: 搭建前端组件库文档最快姿势:Docz

文章首发公众号“混沌前端”

Docz 是零配置的,基于Gatsby + MDX,如果你们部门没有使用文档工具,那么你可以轻松接入,如果已经使用了文档工具不妨了解一下Docz,做个对比。

为什么要为项目组件/组件库添加文档

组件库文档可以帮我们解决以下问题:

  1. 不知道项目中有哪些公共组件(比如组员写的组件,但是你并不知道),导致重复开发。
  2. 复用组件时需要再去翻代码,看看怎么使用,传什么参数。
  3. 以前写的代码,需要修改或者重构时,无从下手

有了组件库文档,基本就可以解决上面的问题,同时也提升了代码复用率和开发效率。

前置概念

常见的文档工具

  1. vuePress
  2. gitbook
  3. MDX  MarkDown + JSX
    支持导入React组件 JSON数据  MD或MDX文档
    支持remark 生态系统中的任何插件
    Playground 实时修改,实时预览
  4. Gatsby
    生态丰富,有各种各样的插件,支持MDX。
  5. JSDoc
    根据javascript文件中注释信息,生成JavaScript应用程序或库、模块的API文档 的工具
    参考文档:jsdoc-to-markdown
  6. TSDoc
    参考文档:https://tsdoc.org/play
  7. React Styleguidist  基于JSDOC 可以帮助react项目快速构建项目文档
  8. StoryBook
    一个强大的集组件开发,查看,测试的文档工具,支持多种框架。使用”组件驱动开发“理念。支持多种框架 React Vue Angular Ember Preact Svelte等
    参考文档:CDD
  9. docsify特点:
  • 简单轻便
  • 没有静态构建的 html 文件
  • 多个主题
  1. Dumi
  • 开箱即用
  • 为组件开发而生,支持Markdown扩展,可以渲染组件
  • 主题系统,支持自定义渲染样式
  • API自动生成,基于TypeScript类型定义自动生成组件API
  1. Docz
  2. bisheng Ant Design组件库文档就是使用bisheng构建的

为什么推荐使用Docz

  • 基于MDX进行了封装
  • 完全使用Gatsby构建,可以使用Gatsby的插件和工具生态
  • 零配置
  • 支持TypeScript、CSS预处理器
  • 内置Playground组件,编辑组件可以进行实时渲染
  • 内置Props组件,注释直接生成文档

我们来看一下Docz常用的两个内置组件吧。

Playground

你可能看过AntDesign组件库文档,代码演示 模块中提供了跳转到CodeSandBoxCodePen等网站查看和编辑示例代码的功能。详细内容可以翻阅这篇文章:Antd中示例代码是怎么直接在CodeSandBox中打开的

但是在Docz中你可以直接进行编辑并可以实时查看预览效果。

Props

只需使用Props组件,即可将参数类型和文档注释生成文档,通过表格进行展示

import { Playground, Props } from 'docz'

import { Button } from './'

# Button

<Propsof={Button}/>

## Basic usage

<Playground>

 <Button>Click me</Button>

 <Buttonkind="secondary">Click me</Button>

</Playground>

importReactfrom'react'

importtfrom'prop-types'

constButton= ({ children, kind }) => {

 // We use the kind prop to determine the button's class

 return<buttonclassName={kind}>{children}</button>

}

Button.propTypes= {

 /**

  * This is a pretty good description for this prop.

  */

 kind: t.oneOf(['primary', 'secondary', 'cancel', 'dark', 'gray']),

}

Button.defaultProps= {

 kind: 'primary',

}

exportButton

安装、配置和构建

安装

npm install docz # react react-dom

运行

"scripts": {

   "docz:dev": "docz dev",

   "docz:build": "docz build",

   "docz:serve": "docz build && docz serve"

}

开发

创建.mdx文件即可(指定name和route)。

构建

npm run build # 生成静态资源在.docz/dist目录中

npm run build ----dest docs-site-directory  # 通过--dest 指定文档生成目录

也可以在配置中指定打包输出目录

// doczrc.js

exportdefault {

 dest: '/some-folder'

}

部署

构建之后可以使用任何静态站点托管服务进行部署。

MDX支持

可以直接引入.jsx/.tsx组件,样式;

内置组件

  • Playground
    Playground支持编辑实时渲染,支持函数组件和State
  • Props
    组件内的prop-types定义和typeScript的Interface会通过<Props>转换成表格展示

文档设置

使用YMAL自定义文档设置(也可以自定义属性,用于自定义theme)

---

name: My Document

route: /custom-route

menu: Documents

hidden: false

---

CSS预处理器

需要Gatsby提供的能力,安装插件

TypeScript支持

// doczrc.js

exportdefault {

 typescript: true

}

如果需要精确控制组件后缀,可以使用filterComponents and docgenConfig进行过滤

支持自定义主题

项目配置

基本配置

base 页面访问的basePath

src 指定组件存放目录

files 指定docz解析文件查找路径规则  默认会查找所有扩展名为.mdx的文件

ignore 需要忽略解析的文件

dest 指定docz build的目录

title  Header展示title,默认会去package.json中name字段

description HTML中meta字段

typescript typescript支持 默认false .mdx文件中需要引入TypeScript组件则需要设置

propsParser props格式化 供<Props />渲染使用,禁用可以提升性能。

config 指定docz配置文件 默认顺序 docz.json | .doczrc | doczrc.json |doczrc.js | docz.config.js | docz.config.json

public 指定公共目录,绝对资源路径会从这个目录下取数据

editBranch 点击 Github 按钮时用于编辑文档的分支

host devServer地址 默认 '127.0.0.1'

port devServer 端口

构建流程

menu 可指定菜单中文档的顺序

plugins 指定要使用的插件数组

组件和HooksAPI

ComponentsProvider 将组件传递给 MDX,它们将在您将 Markdown 转换为 html 时使用

Playground 渲染组件并在其中显示代码的可编辑版本

Props 获取组件并根据组件中属性定义生成属性表的组件

useComponents 配合ComponentsProvider使用

useDocs 获取所有已解析文档的列表, 当要创建菜单或列表之类的内容时会很有用。

useMenus 返回 Docz 构建的菜单

useConfig 获取项目配置中项目配置对象

支持自定义插件和MDX插件

使用注意:每次涉及到路由的变化都需要重启生效,遇到缓存问题可以删除.docz文件夹后重启

// 一个简单的docz配置 doczrc.js

exportdefault {

 files: './docs/mdx/*.{md,markdown,mdx}',

 dest: './docs/site',

 title: 'Flex-Ctrip-Offline',

 typescript: true

}

使用Gatsby生态

你可以直接在Docz中使用丰富的Gatsby插件,只需在根目录创建gatsby-config.js文件即可。

比如,你想在Docz页面中引入script脚本,可以使用gatsby-plugin-load-script插件:

module.exports= {

   plugins: [

     {

       resolve: 'gatsby-plugin-load-script',

       options: {

         disable: false,

         src: '//www.example.com/demo.js',

         crossorigin: 'anonymous',

         onLoad: '() => console.log("add ubt script!")',

       }

     },

     {

       resolve: 'gatsby-plugin-load-script',

       options: {

         disable: false,

         src: '//www.example.com/demo.js',

         crossorigin: 'anonymous',

         onLoad: '() => console.log("add shark script!")',

       }

     }

   ],

 }

如果你想自定义webpack打包配置,可以新建gatsby-node.js:

// 此文件是用于docz自定义webpack配置。是Gatsby提供的功能:https://www.gatsbyjs.com/docs/how-to/custom-configuration/add-custom-webpack-config/

constpath=require('path')

exports.onCreateWebpackConfig= ({

 stage,

 rules,

 loaders,

 plugins,

 actions,

}) => {

 actions.setWebpackConfig({

   resolve: {

       alias: {

           '@components': path.resolve(__dirname, '../src/components'),

           '@styles': path.resolve(__dirname, '../src/styles'),

           '@models': path.resolve(__dirname, '../src/models'),

           '@utils': path.resolve(__dirname, '../src/utils')

       }

   }

 })

}


相关文章
|
3月前
|
数据采集 前端开发 JavaScript
《花100块做个摸鱼小网站! 》第四篇—前端应用搭建和完成第一个热搜组件
本文档详细介绍了从零开始搭建一个包含前后端交互的热搜展示项目的全过程。通过本教程,读者不仅能学习到完整的项目开发流程,还能掌握爬虫技术和前后端交互的具体实践。适合有一定编程基础并对项目实战感兴趣的开发者参考。
84 1
|
3月前
|
JavaScript 前端开发 开发者
哇塞!Vue.js 与 Web Components 携手,掀起前端组件复用风暴,震撼你的开发世界!
【8月更文挑战第30天】这段内容介绍了Vue.js和Web Components在前端开发中的优势及二者结合的可能性。Vue.js提供高效简洁的组件化开发,单个组件包含模板、脚本和样式,方便构建复杂用户界面。Web Components作为新兴技术标准,利用自定义元素、Shadow DOM等技术创建封装性强的自定义HTML元素,实现跨框架复用。结合二者,不仅增强了Web Components的逻辑和交互功能,还实现了Vue.js组件在不同框架中的复用,提高了开发效率和可维护性。未来前端开发中,这种结合将大有可为。
142 0
|
4天前
|
前端开发 JavaScript
除了 jsPDF,还有哪些前端库可以用于生成 PDF?
【10月更文挑战第21天】这些前端库都有各自的特点和优势,你可以根据具体的项目需求、技术栈以及对功能的要求来选择合适的库。不同的库在使用方法、性能表现以及功能支持上可能会有所差异,需要根据实际情况进行评估和选择。
|
3天前
|
前端开发 JavaScript 开发者
揭秘前端高手的秘密武器:深度解析递归组件与动态组件的奥妙,让你代码效率翻倍!
【10月更文挑战第23天】在Web开发中,组件化已成为主流。本文深入探讨了递归组件与动态组件的概念、应用及实现方式。递归组件通过在组件内部调用自身,适用于处理层级结构数据,如菜单和树形控件。动态组件则根据数据变化动态切换组件显示,适用于不同业务逻辑下的组件展示。通过示例,展示了这两种组件的实现方法及其在实际开发中的应用价值。
8 1
|
6天前
|
缓存 前端开发 JavaScript
前端serverless探索之组件单独部署时,利用rxjs实现业务状态与vue-react-angular等框架的响应式状态映射
本文深入探讨了如何将RxJS与Vue、React、Angular三大前端框架进行集成,通过抽象出辅助方法`useRx`和`pushPipe`,实现跨框架的状态管理。具体介绍了各框架的响应式机制,展示了如何将RxJS的Observable对象转化为框架的响应式数据,并通过示例代码演示了使用方法。此外,还讨论了全局状态源与WebComponent的部署优化,以及一些实践中的改进点。这些方法不仅简化了异步编程,还提升了代码的可读性和可维护性。
|
14天前
|
存储 弹性计算 算法
前端大模型应用笔记(四):如何在资源受限例如1核和1G内存的端侧或ECS上运行一个合适的向量存储库及如何优化
本文探讨了在资源受限的嵌入式设备(如1核处理器和1GB内存)上实现高效向量存储和检索的方法,旨在支持端侧大模型应用。文章分析了Annoy、HNSWLib、NMSLib、FLANN、VP-Trees和Lshbox等向量存储库的特点与适用场景,推荐Annoy作为多数情况下的首选方案,并提出了数据预处理、索引优化、查询优化等策略以提升性能。通过这些方法,即使在资源受限的环境中也能实现高效的向量检索。
|
14天前
|
前端开发 JavaScript
CSS样式穿透技巧:利用scoped与deep实现前端组件样式隔离与穿透
CSS样式穿透技巧:利用scoped与deep实现前端组件样式隔离与穿透
90 1
|
14天前
|
存储 前端开发 JavaScript
🚀 10 个 GitHub 存储库,助你成为前端巨匠✨
本文介绍了10个极具价值的GitHub存储库,旨在帮助各级JavaScript开发人员提升技能。这些资源涵盖了从基本概念到高级算法、编码风格指南、面试准备等各个方面,包括经典书籍、实用工具和面试手册。无论您是刚入门的新手还是有经验的开发者,这些存储库都能为您提供丰富的学习资源,助您在JavaScript领域更进一步。探索这些资源,开启您的学习之旅吧!
44 0
🚀 10 个 GitHub 存储库,助你成为前端巨匠✨
|
17天前
|
前端开发 JavaScript 开发者
Web组件:一种新的前端开发范式
【10月更文挑战第9天】Web组件:一种新的前端开发范式
17 2
|
25天前
|
前端开发 JavaScript Go
前端开发趋势:从响应式设计到Web组件的探索
【10月更文挑战第1天】前端开发趋势:从响应式设计到Web组件的探索
29 3