[new feature] Docs: contribute.md 移动至 .github 下 (#212)
* move contribute to .github * fix wrong name * move markdown.md to .github
This commit is contained in:
@@ -0,0 +1,47 @@
|
||||
## 组件文档如何编写
|
||||
|
||||
#### 文件格式
|
||||
|
||||
组件文档采用 markdown 格式,和普通 markdown 最大的区别是示例代码是直接写在 markdown 文件里面,所以请确保你写的示例代码是可以正确运行的。
|
||||
|
||||
#### 文档内的标题规范
|
||||
|
||||
文档标题从 `h2`(即 `##` 标题 )开始,每往下一级多加一个 `#` 号;一般到 `h3` (两级标题) 或`h4` (三级标题)即可,不要出现过多的标题层级。
|
||||
|
||||
#### 组件描述
|
||||
|
||||
大标题下面是对组件的一句话简要描述。
|
||||
|
||||
#### 使用指南(可选)
|
||||
|
||||
如果组件需要使用指南,放在组件描述下方,另起一个二级标题。
|
||||
|
||||
#### 代码演示
|
||||
|
||||
另起一个二级标题,正文可以是 markdown 和示例的混合。示例的结构如下:
|
||||
|
||||
// 在 demo 端之外放置的 script 会直接运行
|
||||
// 在 script 中声明的 vue 变量,在 demo 中都可以直接使用
|
||||
<script>
|
||||
export default {
|
||||
data() {
|
||||
return {
|
||||
size: 'large'
|
||||
};
|
||||
}
|
||||
};
|
||||
</script>
|
||||
|
||||
:::demo 基础用法(必须以:::demo开头,后面的描述可选,如果有的话控制在一两句话,不要过长)
|
||||
```html // :::demo后面必须接代码段,否则不会识别为示例
|
||||
<van-button :size="size"> // 在内容区直接写 vue 中 template 段代码即可
|
||||
Large
|
||||
</van-button>
|
||||
```
|
||||
::: // 示例结束的标记,必须接在代码段之后,否则不会识别为示例
|
||||
|
||||
代码演示的几个书写原则:
|
||||
|
||||
- 从简单用法开始介绍,不要上来就同时使用一大堆 API,会让人觉得难以上手
|
||||
- 正交性原则,一个示例只演示一个(或者一类)API 的使用方法,如无特殊需求不要在一个示例中同时演示多个 API 混合使用
|
||||
- 如果示例的一句话描述无法完整描述整个场景,可以在 `:::demo` 之前写一段详细的说明性文字
|
||||
Reference in New Issue
Block a user