前端组件库文档解决方案

本文主要分享的内容：常用的文档/静态站生成工具有哪些？每种工具有什么特点？工具适应场景。AndD组件库文档是如何制作的，使用了哪些工具。以AntDButton组件为例，看一下antd组件库的文档页面结构和文档生成：拼接MarkDown并渲染到最终的文档展示页面。静态站生成工具解决方案vuePressgitbookMDXMarkDown+JSX支持导入React组件支持remark生态中的任何插件Playground实时修改，实时预览支持MarkDown语法完全支持JSX以<字符开头的行JSX代码块支持导入和exportimportcomponentsjsondatamdormdxdocumentMDXProvider提供MarkDown渲染HTML使用组件映射组件列表GatsbyDemo初始化npminitgatsbynpminstall-ggatsby-cligatsbynewrunningnpmrundevelop特点：生态好，功能丰富，插件多样，支持MDX。Gatsby有一个称为数据层的强大功能，通过Gatsby的数据层，您可以组合来自多个来源的数据，这使您可以为每种类型的数据选择最佳平台。http://localhost:8000/___graphql可以看到GraphQL数据的数据源Gatsby-source-*数据拉取：使用页面查询拉入页面数据，在页面中导出查询，可以使用graphql查询将数据拉入组件页面可以使用useStaticQuery挂钩拉入以动态创建页面。Gatsby的文件系统路由API定义了一种特殊的语法来命名src/pages目录中的文件，它允许您根据数据层中的节点集合为您的站点动态创建新页面。JSDoc是一个根据javascript文件中的注解信息生成JavaScript应用程序、库、模块的API文档的工具。安装npminstall-Djsdoc默认使用jsdocxxx.js输出文档到out文件夹。可以通过--destination-to-markdown指定输出路径jsdocTSDochttps://tsdoc.org/playReactStyleguidistStoryBook强大的组件开发、查看和测试文档工具，支持多种框架。使用“组件驱动开发”的概念。-支持多种框架ReactVueAngularEmberPreactSvelte等教程CDDdocsify特点：简单轻量级无静态构建html文件多主题安装npmidocsify-cli-g初始化docsifyinit./docspreviewdocsifyservedocs目录结构index.html文件条目README.mdhomepage.nojekyll防止GitHubPages忽略以下划线开头的文件。侧边栏创建_sidebar.md（支持目录层级嵌套）。_sidebar.md中的页面会自动生成标题和副标题自定义导航栏html标签_navbar.md（也支持目录级嵌套，显示形式为弹窗）Cover_coverpage.md#/首页全屏显示即可指定背景图片和背景颜色可以指定只显示封面配置窗口。$docsify={el:'#app',//根元素repo:'docsifyjs/docsify/',//Git仓库地址maxLevel:6,//最大目录层级loadNavbar:false,//加载_navbar.md作为导航栏（或者直接指定md路径）loadSidebar:false,//加载_sidebar.md作为侧边栏hideSidebar:true,//隐藏侧边栏subMaxLevel:0,//在自定义侧边栏中添加一个目录（最大级别）auto2top:true,//当页面路径改变时滚动到屏幕顶部homepage:'README.md',//#/HomepagebasePath:'/path/',//基本路径，可设置为其他目录或其他域名相对Path:false,//如果为true，则链接是相对于当前上下文的。coverpage:false,//封面默认加载_coverpage.md，md路径也可以指定logo,name,nameLink,markdown,//自定义渲染MarkDown为HTML文档themeColor,executeScript:true,mergeNavbar:true,//小屏导航栏会合并侧边栏'路由模式onlyCover:false,//#/只显示封面requestHeaders:{'x-token':'xxx',},//设置请求资源头notFoundPage:true,//加载_404.md或指定对应mdvueComponents,//注册vue组件，可以直接在mdvueGlobalOptions,vueMounts}主题中使用，在github上编辑，预览jsfiddlerDemo，复制到剪贴板，Gitalk，分页和标签等PWASSR嵌入文件：支持视频，audio,iframe或者代码块，甚至MarkDownDocz都是基于MDX封装的完全用Gatsby构建，可以使用Gatsby的插件和工具生态零配置TypeScript支持安装npminstalldocz#reactreact-domrun"scripts":{"docz:dev":"doczdev","docz:build":"doczbuild","docz:serve":"doczbuild&&doczserve"}开发创建.mdx文件（指定名称和路由）构建npmrunbuild#在.docz/dist目录下生成静态资源npmrunbuild----destdocs-site-directory#Specifiedby--dest文档生成目录也可以在配置中指定打包输出目录//doczrc.jsexportdefault{dest:'/some-folder'}Deployment构建后可以使用任何静态站点托管服务进行部署，MDX支持可以直接导入.jsx/.tsx组件，样式；内置组件PlaygroundPlayground支持编辑实时渲染，支持函数组件，StateProps组件中的prop-types定义，typeScript的界面会通过转换成表格显示Documentsettings使用YMAL自定义文档设置（也可以自定义Define属性来自定义主题）---name:MyDocumentroute:/custom-routemenu:Documentshidden:false---CSS预处理器需要Gatsby提供的能力，安装插件TypeScript支持//doczrc.jsexportdefault{typescript:true}如果需要精确控制组件后缀，可以使用filterComponents和docgenConfig进行过滤。支持自定义主题项目配置。mdxfileignore需要忽略解析后的文件dest指定docz构建的目录标题Header显示标题，默认会去package.json中的name字段descriptionmeta字段typescripttypescriptsupportinHTML默认为false如果.mdx文件中需要引入TypeScript组件，需要设置propsParserprops格式用于渲染，禁用可以提高性能。config指定docz配置文件的默认顺序docz.json|.doczrc|doczrc.json|doczrc.js|文档.config.js|当按钮用于编辑文件分支主机devServer地址默认'127.0.0.1'端口devServer端口构建过程菜单可以指定菜单中文件的顺序plugins指定插件数组使用Components和HooksAPIComponentsProvider将组件传递给MDX，它们将在你将Markdown转换为html时，使用Playground渲染组件并显示其中代码的可编辑版本。Props获取组件并根据组件中的属性定义生成属性表的组件useMenus返回Docz构建的菜单。useConfig获取项目配置中的项目配置对象。支持自定义插件和MDX插件。注意：每个涉及路由的更改都需要重新启动才能生效。如果遇到缓存问题，可以删除.docz文件夹重启//一个简单的docz配置doczrc.jsexportdefault{files:'./docs/mdx/*.{md,markdown,mdx}',dest:'./docs/site',title:'Flex-Ctrip-Offline',typescript:true}Dumi为开箱即用的组件开发而构建，支持Markdown扩展，可以渲染组件主题系统，支持自定义渲染样式API自动生成，以及自动生成基于TypeScript类型定义的组件API组件开发脚手架npx@umijs/create-dumi-lib#以文档方式初始化一个组件库开发脚手架npx@umijs/create-dumi-lib--site#初始化一个组件库开发脚手架在站点模式下（首页比文档模式多一个，首页使用docs/index.md）#也可以手动切换文档模式=>站点模式：修改.umirc.ts，添加模式：'site'静态站点脚手架npx@umijs/create-dumi-apprunnpminstallnpmstartbuildanddeploynpmrunbuilddirectoryStructure├──README.md├──docs#组件库文档目录│├──index.md#组件库文档主页（readme.md不存在）│└──otherDir#组件文档otherroutes│├──index.md│├──sample.md│└──help.md├──src#组件库源代码目录（纯文档站点可以忽略）│├──Foo│└──index.ts├──.umirc.ts#dumi配置文件└──.fatherrc.ts#father-build的配置文件，用于封装组件库的代码块。jsx和tsx的代码块会被dumi解析成React组件并渲染。度米介绍组件原则：像用户一样使用组件：直接导入组件库进行文档demo演示。不仅可以用来调试组件和编写文档，还可以供用户直接复制到项目中使用。dumi会自动为我们创建组件库npmpackage->组件库源代码的映射。外部demo可以导入外部文件作为demo渲染，可以支持查看demo源码直接嵌入渲染```jsx/***inline:true*/importReactfrom'react';exportdefault()=>'我就直接嵌入';```embedMarkdow嵌套组件API自动生成JSDoc注释+TypeScript类型定义如何在非umi-projects中使用-dumiDEMO的概念实现组件API的自动生成。欢迎继续关注，微信公众号“乱前端”