docz使用

1. 新建

（1）新建项目

npx create-docz-app my-docz-app
# or
yarn create docz-app my-docz-app --example typescript
//确保react及react-dom版本为16.8.0及以上

（2）安装docz依赖

npm install docz # react react-dom
在项目中安装Docz之后，在package.json中添加脚本语句运行、构建Docz网站。
注意，这是一个可选步骤:

{
  "name": "next-gen-documentation",
  "scripts": {
    "docz:dev": "docz dev",
    "docz:build": "docz build",
    "docz:serve": "docz build && docz serve"
  },
  "dependencies": {
    "docz": "latest",
    "react": "16.8.0",
    "react-dom": "16.8.0"
  }
}

（3）运行语句， 开启服务。 yarn docz: dev/npm run docz: dev

2. Writing MDX

（1）本地运行后， 可开始编写文档。

Docz使用MDX格式，允许我们在markdown文件中无缝地编写JSX。
不一定要遵循任何文件架构或约定，我们可在项目任何地方创建.mdx文件。
创建文件后， 给该文件 name 和 route

---
name: Hello world
route: /
---

# Hello world

Hello, I'm a mdx file!

可打开浏览器查看运行效果。

（2）Working with components

我们可导入一些组件，如交互式图表，并将它们嵌入到内容中。
举个例子：
假设工程在与该.mdx文件相同的文件夹下，已创建好button.jsx/button.tsx文件并导出的Button 组件。
在.mdx中导入Button 能有以下效果：

---
name: Hello world
---

import { Button } from './Button'

# Hello world

Hello, I'm still a mdx file, but now I have a button component !

<Button onClick={() => { alert("You clicked me"); }}>Click me</Button>

使用MDX，我们可以将React组件或html元素与常规markdown混合使用，允许我们为自己的组件编制文档，或创建辅助组件（helper components），使文档编制变得更容易。
Docz附带了一些组件，可以帮助我们更快地记录组件，这些都包含在内置组件中。

3. Built-in components

Docz有内置的组件，可以帮助我们编写代码
利用组件及其解析的ASTs(抽象语法树)，我们可以做很多事情，比如渲染组件、创建描述组件内容的表格、从代码生成文档、遍历文件定义自定义的getters等等。

（1）Playground Component

使用<Playground>，我们可以在一个实时编辑的区域中展现组件，并能直接看到所使用的示例代码。

---
name: Button
route: /
---

import { Playground } from 'docz'
import { Button } from './Button'

# Button

## Basic usage

<Playground>
  <Button>Click me</Button>
  <Button kind="secondary">Click me</Button>
</Playground>

在<Playground>组件中还支持编写有状态和功能的组件:

import { Playground } from 'docz'

# Counter

<Playground>
  {() => {
    const [counter, setCounter] = React.useState(0)
    return (
      <>
        <button onClick={() => setCounter(counter => counter+1)}>
          Increase
        </button>
        <p>{counter}</p>
      </>
    )
  }}
</Playground>

或者把计数功能单独写在Counter组件，我们便可这样写：

import { Playground } from 'docz'
import { Counter } from './Counter'

# Counter

<Playground>
  {() => {
    const [counter, setCounter] = React.useState(0)
    return (
      <Counter
        value={counter}
        onChange={() => setCounter(counter => counter+1)}
      />
    )
  }}
</Playground>

Component Props

编写组件文档时最重要的是要知道该组件有哪些属性。

为编写好属性文档，我们需要定义好该组件的属性并编写该属性的规范，自己写很难同步实现并容易出现错误。而docz提供<Props>自动获取组件定义的属性，并在一个表格中显示它们以及它们的默认值和可选的描述。
除了支持在JS代码中解析prop-type之外，还支持Flow和Typescript。

---
name: Button
route: /
---

import { Playground, Props } from 'docz'
import { Button } from './'

# Button

<Props of={Button} />

## Basic usage

<Playground>
  <Button>Click me</Button>
  <Button kind="secondary">Click me</Button>
</Playground>

若Button 组件有一些描述其props的注释， 在flow和typeScript中，可通过props-types展示注释。

import React from 'react'
import t from 'prop-types'

const Button = ({ children, kind }) => {
  // We use the kind prop to determine the button's class
  return <button className={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',
}
export Button

如果使用了上面描述的props-types，我们可在表格中看到属性列表:

通过在组件的props接口中添加注释，可以在typescript中实现相同的功能:
可以通过在props上方的行上添加注释来添加对props的描述。
注意:描述注释的格式必须是/** Description */

import React from 'react'

interface ButtonProps {
  /**
   * This is a pretty good description for this prop.
   */
  kind: 'primary' | 'secondary' | 'cancel' | 'dark' | 'gray'
}

typescript解析器有时会有点麻烦(官方正在解决)，所以如果typescript文件找不到，可能需要写完整的路径和文件结尾， 或者检查是否使用default导出或named导出是问题所在。

import { Props } from 'docz'
import Button from './Button.tsx'

### Button Props
<Props of={Button} />

4. Document settings

文档设置用生成文档站点的metadata来丰富文档。
这些数据使用YAML定义在.mdx文件的顶部，并可以通过将这些数据传递给主题来定制页面。

（1）每个文档有三个重要的属性：

---
name: My Document
route: /custom-route
menu: Documents
---

name: 文档的名称，用作页面的标题
route(可选): 指向文档生成页面的路由或路径。例如:/docs/my-component
menu：包含文档的菜单，可更改这个属性将文档分组到单个菜单中。

（2）Custom properties

内建的属性是针对docz的，但是docz是可扩展的，我们可以创建自己的主题，这些主题可能需要不同的属性。
可以在文档设置中设置自定义属性，它们将自动被解析。
例如，可以定义一个名为fullpage的属性来定义文档是否是一个100%宽度的页面:

---
name: My Document
fullpage: true
---

。。。

5. Powered by Gatsby

Gatsby是一个快速反应的现代站点生成器，也是新前沿时代最伟大的现代工具之一。它有一个庞大的生态系统和社区，背后有一个非常有才能的团队。
从v2开始，docz的核心完全围绕Gatsby构建，这是项目自创建以来最大的变化。

• 专注于创建特性，而不是担心bundler管理
• 默认情况下是静态和优化的构建
• 快速的开发经验和更好的工作流程
• 巨大的工具、插件和社区生态系统
• 更好的和容易的方法来定制的东西里面的Docz

待续。。。