简介
gatsby-plugin-xillio-docs 是一个 Gatsby 插件，它可以帮助你将你的代码文档以及 Markdown 文档自动转换成一个漂亮的文档网站，并且可以自动生成导航。
使用该插件可以让你在项目中更加方便的创建并且展示文档，非常适合内部文档的管理。
使用方法
安装
在你的 Gatsby 项目中安装该插件：
npm install --save gatsby-plugin-xillio-docs
添加配置
在你的 gatsby-config.js 文件中添加如下配置：
-- -------------------- ---- -------
-------------- - -
-------- -
-
-------- ----------------------------
-------- -
--------- -------
-------------- -----------------
--------------- ------------
--
--
--
-其中参数 docsPath 代表你的 Markdown 文档的目录，参数 componentPath 代表你的包含组件代码的目录，typeScriptPath 则代表你的 TypeScript 类型定义文件的目录。
创建 Markdown 文件
在指定的 Markdown 目录中创建一个新的 Markdown 文件，例如：docs/index.md。
在 Markdown 文件中编写你的文档，在文件开头处添加多个 YAML 格式的元数据用于设置该文档的信息：
--- title: 你的文档标题 description: 你的文档描述 menuOrder: 1 ---
其中 title 代表文档的标题，description 代表文档的描述，menuOrder 代表文档显示的优先级，数值越小优先级越高。
创建组件
在指定的组件目录中创建一个新的组件文件，例如：src/components/MyComponent.tsx。
在组件文件中编写你的组件代码，同时编写你的 JSDoc 格式文档，例如：
-- -------------------- ---- -------
---
- ----------
- ----------- -- ---
-
- --------
- ------
- ------------ ------------- ------- --
- ---
--
------ ------- -------- ------------- ----- -- -
------ -------------------
-创建 TypeScript 声明文件
在指定的 TypeScript 目录中创建一个新的文件，例如：src/types/index.d.ts。
在文件中编写你的组件 TypeScript 声明，例如：
/**
* MyComponent 有一个 value 属性
*/
declare interface MyComponentProps {
value: string
}运行
在终端中切换到 Gatsby 项目的目录下，运行以下命令：
gatsby develop
你将会看到你的文档网站正在运行。
示例代码
Markdown 示例
-- -------------------- ---- ------- --- ------ ---- ------------ -------- ---------- - --- -- ---- ---- ------ ---
组件示例
-- -------------------- ---- -------
---
- ----------
- ----------- -- ---
-
- --------
- ------
- ------------ ------------- ------- --
- ---
--
------ ------- -------- ------------- ----- -- -
------ -------------------
-TypeScript 声明文件示例
/**
* MyComponent 有一个 value 属性
*/
declare interface MyComponentProps {
value: string
}总结
Gatsby 插件 gatsby-plugin-xillio-docs 可以方便地将你的代码文档和 Markdown 文档转换为漂亮的网页文档并自动生成导航，让你更加方便地创建并展示你的文档。使用该插件，你可以将你的 Gatsby 项目作为文档网站提供，非常适合于内部文档管理，同时也可以为你的项目提供更好的文档支持。
来源：JavaScript中文网 ，转载请注明来源 https://www.javascriptcn.com/post/600672eb0520b171f02e1eb6