搭建前端组件库文档最佳姿势: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天前
|
前端开发 容器
前端框架与库 - Angular模块与依赖注入
【7月更文挑战第17天】探索Angular的模块化和依赖注入:模块用于组织组件、服务等,通过`@NgModule`声明。依赖注入简化类间依赖管理,但面临模块重复导入、服务作用域不当和依赖循环等问题。解决策略包括规划模块结构、正确设置服务作用域和使用工厂函数打破循环依赖。遵循最佳实践,构建高效、可维护的Angular应用。
|
1天前
|
编解码 前端开发 JavaScript
前端框架与库 - Bootstrap响应式设计
【7月更文挑战第19天】Bootstrap是流行的前端框架,以其响应式设计和组件库闻名。响应式设计确保网站在不同设备上显示良好。关键包括:**网格系统**,基于12列布局,适应屏幕尺寸;和**媒体查询**,用于根据设备特性应用样式。开发者常遇到的问题有:网格列超过12、忽视断点和自定义样式冲突。解决方法涉及正确使用断点类、测试多设备及清晰注释代码。借助官方文档和实践,可有效掌握响应式设计。
|
8天前
|
存储 前端开发 JavaScript
前端框架与库 - React基础:组件、Props、State
【7月更文挑战第12天】React是JavaScript库,专注UI构建,基于组件化。组件是UI模块,可函数式或类定义。Props是组件间安全传递数据的只读参数,用defaultProps和propTypes保证正确性。State则是组件内部可变数据,用于驱动更新。使用setState()确保正确变更和渲染。了解并妥善处理这些概念是高效React开发的基础。
|
6天前
|
缓存 JavaScript 前端开发
前端框架与库 - Vue.js基础:模板语法、数据绑定
【7月更文挑战第14天】Vue.js 是渐进式框架,以简洁API和高效数据绑定知名。本文聚焦模板语法与数据绑定,解释常见问题和易错点,助力初学者避坑。模板语法中,{{ expression }} 用于渲染值,v-bind/: 用于动态绑定属性。数据绑定涉及文本、属性和事件,注意v-model适用于表单元素,计算属性有缓存。理解正确用法,借助文档和IDE,可提升开发质量和效率。善用Vue.js,打造响应式UI。
|
4天前
|
前端开发 JavaScript
前端框架与库 - Angular基础:组件、模板、服务
【7月更文挑战第16天】Angular,谷歌维护的前端框架,专注构建动态Web应用。组件是核心,包含行为逻辑的类、定义视图的模板和样式。模板语法含插值、属性和事件绑定。服务提供业务逻辑,依赖注入实现共享。常见问题涉及组件通信、性能和服务注入。优化通信、性能并正确管理服务范围,能提升应用效率和质量。学习组件、模板和服务基础,打造高效Angular应用。
|
5天前
|
JavaScript 前端开发 API
前端框架与库 - Vue.js 组件与路由
【7月更文挑战第15天】Vue.js 框架以简洁API和高效DOM更新著名,组件和路由是构建应用的关键。组件是自包含的实例,常见问题包括命名冲突、作用域混淆和状态管理。要避免这些问题,可使用命名空间、明确数据绑定和事件,以及采用Vuex管理状态。Vue Router提供声明式路由,常见挑战包括路由守卫、动态路由参数和懒加载配置。正确使用路由守卫、处理动态参数和实现代码分割能优化路由管理。提供的代码示例展示了基本组件和路由配置。
|
7天前
|
前端开发 JavaScript 开发者
前端框架与库 - React生命周期与Hooks
【7月更文挑战第13天】React 框架革新UI构建,引入Hooks简化组件状态管理和副作用处理。组件生命周期涉及挂载、更新、卸载,对应不同方法,如`componentDidMount`、`shouldComponentUpdate`等,但现在推荐使用`useState`和`useEffect` Hooks。`useEffect`处理副作用,需注意清理和依赖数组。避免问题的关键在于正确使用Hooks和理解其工作模式,以构建高效应用。
|
2天前
|
JavaScript 前端开发 API
前端框架与库 - jQuery基础与DOM操作
【7月更文挑战第18天】jQuery 是一个简化JavaScript任务的库,以其“write less, do more”理念著称。核心功能包括DOM操作、事件处理和Ajax。DOM操作如选择元素(`$(&quot;p&quot;)`、`$(&quot;#myDiv&quot;)`、`$(&quot;.myClass&quot;)`)、创建及添加元素、修改属性和内容。事件处理如绑定(`click`)和触发(`trigger`)。常见问题涉及`$`符号冲突(使用`jQuery`代替)、异步加载管理和选择器性能优化。了解并规避这些问题能提升jQuery使用效率。
|
5天前
|
前端开发 JavaScript CDN
前端实现打字机的效果 -- typed库的使用
typed.js是一款轻量级JavaScript插件,模拟打字机效果,用于网页文本的动画输入。特点是易用、高度可配置,支持多种动画模式且无依赖。配置包括字符串、速度、显示延迟、循环选项等。安装可通过NPM或CDN。使用时在HTML中添加`&lt;span&gt;`标签,然后在JS中实例化Typed对象。丰富的回调函数可用于自定义行为。适用于展示性和个人博客网站,增加互动性。尝试不同配置,创建独特动态文本效果。
15 0
|
15天前
|
存储 前端开发 容器
前端开发的设计思路【精炼】(含数据结构设计、组件设计)
前端开发的设计思路【精炼】(含数据结构设计、组件设计)
13 0