在使用中不断挑战和完善

md 写法升级


获取新功能方式*：升级 @antv/gatsby-theme-antv 1.0.0-beta. beta 版本不断迭代中….

1. 引用公共内容

支持使用特殊语法引用内容，避免重复书写。同时支持套娃。

  1. `markdown:common/style.md`

以上方式，写入项目根目录开始的路径，项目将自动把该 md 内容复制填充到指定位置

2. 配置项描述信息

对配置项的描述放在特定的 description 标签内，顺序为 参数类型、是否可选、默认值

  1. <description> _boolean_  **optional**  _default:_ `false`</description>

这样写便于项目自动提取参数放入合适的位置。
image.png

3. 支持插入 code playground

image.png

  1. <playground path='category/basic/demo/ts-demo.ts' rid='container'></playground>
name description isRequired type default
path demo 从 examples 文件开始路径 true string -
height 容器高度 false number 400
rid 如果一页有超过两个 code playground 需要加入，否则容器都为 container 会重复渲染 false string ‘container’

*注意 如果代码中有 fetch data，而 fetch 的路径又是一个相对路径，那么会在引用之后在该文档地方找不到数据而报错，推荐将数据上传 cdn。

4. 插入 tag 标签

属性和效果参考 antd - tag 组件，在 md 中写法如下：

  1. <tag color="green" text="分类图例">分类图例</tag>

API 强推荐规范

1. 每篇文档作为 h2

目的是为了作为引用在 demo 侧作为如下图 「数据样式」一节内容
image.png

2. 文章内标题从 h3 开始，且配置项放 h3

同样如上图，引入后作为「数据样式 - data」内容。且在此页面搜索框会进行联想，联想只支持联想 h2 h3 标题，所以推荐将配置项写到 h3 标题。

3. 函数类型说明&示例代码块

如下，函数类型放在 sign 代码块里，示例代码依然放常规 js / ts

  1. ```sign
  2. getSourceNode(): Node | null
  1. new Chart({
  2.   container: 'container',
  3.     height: 500,
  4. })
  2. sign 效果如下图：<br />![image.png](https://cdn.nlark.com/yuque/0/2020/png/185307/1601275901022-87a56695-a295-4470-9c6f-6d4600bba8b4.png#align=left&display=inline&height=125&margin=%5Bobject%20Object%5D&name=image.png&originHeight=125&originWidth=925&size=22181&status=done&style=none&width=925)
  4. <a name="LvZ9e"></a>
  5. #### 4. 分种类介绍
  6. 参考目前对于对于 scale 等重载方式的介绍，示例如下：
  8. 第一种 传入以字段名为 key，_ScaleOption_ 为 value 的配置，同时设置多个字段的度量。

chart.scale({ sale: { min: 0, max: 100, }, });

  2. 第二种 定义单个字段的度量，第一个参数为字段名，第二个参数为 _ScaleOption_。

chart.scale(‘sale’, { min: 0, max: 100, });

  2. 第三种 作为第一种和第二种的结合，第一个参数以字段名为 key，_ScaleOption_ 为 value，第二个参数传入 _ScaleOption_ 配置。

(field: Record, scaleOption?: ScaleOption) => View; chart.scale( { sale: { min: 0, max: 100, }, }, { nice: true, } );

  2. <a name="t5g0P"></a>
  3. #### 5. 外链规范
  5. - 教程可以链接 API，但是 API 最好不要再链接回教程
  6. - API 文档内可以互相链接（宜少）
  7. - API 和教程如需要链接 demo 示例通过上述 md 新用法 - 插入 code playground 实现
  8. - 图片和链接需保证有效性（之后 gatsby 会出检测机制）
  9. - 路径使用绝对路径 `/zh/docs/manual/middle/states/defaultBehavior` 
  11. <a name="nTn9H"></a>
  12. #### 6. 图片规范
  14. - 通过 width 把控图片宽度，避免图片过大，占据一页信息，如图片就是很关键的流程图，可以设置 `width: 100%` 
  15. - 如果是图表示例截图，最好改成 code playground
  17. <a name="ETot7"></a>
  18. #### 7. 不要出现 object 类型
  19. 对于 API 文档最好不要出现 object 否则用户无法通过阅读得知如何配置使用
  21. <a name="Kwodn"></a>
  22. ### 其他细节规范解答
  23. <a name="rDKiu"></a>
  24. #### 空格
  25. 遵循文档写作基本要求，中英文之间需要空格，链接之间需要空格
  27. <a name="ZRa6L"></a>
  28. #### 关于图片链接
  29. 没有规定图片必须加链接
  31. <a name="56AyY"></a>
  32. #### 废弃 API 规范
  33. 废弃 API 推荐在教程里加一篇文章专门描述，在 API 相关部分做说明即可。
  35. <a name="Ip5XS"></a>
  36. #### 配置项是 h3 还是表格？
  37. 如果配置项超过 5 个推荐提高到 h3 标题上，方便用户检索和定位，否则使用表格，表格推荐顺序为：
  38. ```markdown
  39. | 参数名   | 类型    | 是否必选 | 默认值 | 描述               |
  40. | -------- | ------- | -------- | ------ | ------------------ |
  41. | sortable | boolean |          | -      | 是否对数据进行排序 |
  42. | theme    | object  |          | -      | 主题配置           |
  43. | visible  | boolean |          | -      | 是否可见           |

FQA

1. 超过二级的嵌套列表解析成两级？

描述：markdown 表现良好，但是在官网上渲染成两级。
解决：参考这个 issue Third level nested unordered list items render as second level，可以通过写成四个缩进来解决。
image.png
image.png