[Doc] update contribution guide (#1250)

.github/MARKDOWN.md

@@ -1,42 +0,0 @@
-## 组件文档如何编写
-
-#### 文件格式
-
-组件文档采用 markdown 格式编写
-
-#### 文档内的标题规范
-
-文档标题从 `h2`（即 `##` 标题 ）开始，每往下一级多加一个 `#` 号；一般到 `h3` (两级标题) 或`h4` (三级标题)即可，不要出现过多的标题层级。
-
-#### 组件描述
-
-大标题下面是对组件的一句话简要描述。
-
-#### 使用指南（可选）
-
-如果组件需要使用指南，放在组件描述下方，另起一个二级标题。
-
-#### 代码演示
-
-另起一个二级标题，示例的结构如下:
-
-  ```javascript
-    export default {
-      data() {
-        return {
-          size: 'large'
-        };
-      }
-    };
-  ```
-
-  ```html
-    <van-button :size="size">
-      Large
-    </van-button>
-  ```
-    
-代码演示的几个书写原则：
-
-- 从简单用法开始介绍，不要上来就同时使用一大堆 API，会让人觉得难以上手
-- 正交性原则，一个示例只演示一个（或者一类）API 的使用方法，如无特殊需求不要在一个示例中同时演示多个 API 混合使用

docs/markdown/contribution.zh-CN.md

@@ -0,0 +1,144 @@
+## 开发指南
+
+首先感谢你使用 Vant。
+
+以下是关于向 Vant 提交代码的指南。在向 Vant 提交 Issue 或者 PR 之前，请先花几分钟时间阅读以下文字。
+
+### Issue 规范
+
+- 遇到问题时，请先确认这个问题已经在 issue 中有记录或者已被修复
+- 提 Issue 时，请用简短的语言描述遇到的问题，并添加出现问题时的环境和复现步骤
+
+### Pull Request 规范
+
+- 如果遇到问题，建议保持你的 PR 足够小。保证一个 PR 只解决一个问题或只添加一个功能
+- 当新增组件或者修改原有组件时，记得增加或者修改测试代码，保证代码的稳定
+- 在 PR 中请添加合适的描述，并关联相关的 Issue
+
+### 初始化项目
+
+```bash
+git clone git@github.com:youzan/vant.git
+
+cd vant
+
+# 安装依赖
+npm run bootstrap
+
+# 本地开发模式
+npm run dev
+```
+
+浏览器访问 [http://localhost:8080](http://localhost:8080) 就可以看到所有组件的示例了。
+
+### 目录结构
+
+- 仓库的组件代码位于 packages 下，每个组件一个文件夹
+- 组件样式代码位于 packages/vant-css/src 下，vant-css 也会在发布时单独发包
+- docs 目录下是文档网站的代码，本地开发时可以在目录下运行 npm run dev 开启文档网站
+
+项目目录大致如下：
+
+```
+vant
+├─ build            # 构建脚本
+├─ docs             # 文档网站
+├─ packages         # 组件文件
+├─ test             # 单元测试
+└─ types            # 类型定义
+```
+
+### 添加新组件
+
+添加新组件时，请按照下面的目录结构组织文件，并在 `docs/src/doc.config.js` 中配置组件名称
+
+```
+packages
+|- button
+|  ├─ demo        # 示例代码
+|  ├─ test        # 单元测试
+|  ├─ zh-CN.md    # 中文文档
+|  ├─ en-US.md    # 英文文档
+|  └─ index.vue   # 组件入口
+└─ vant-css
+   ├─ index.css   # 样式入口
+   └─ button.css  # 组件样式
+```
+
+### 组件文档
+
+组件文档采用 markdown 格式，内容包括使用示例以及 `API` 等。
+
+##### 1. 标题规范
+
+文档标题从 `h2`（即 `##` 标题 ）开始，每往下一级多加一个 `#` 号。
+
+##### 2. 组件描述
+
+大标题下面是对组件的一句话简要描述。
+
+##### 3. 使用指南
+
+如果组件需要使用指南，放在组件描述下方，另起一个二级标题。
+
+##### 4. 代码演示
+
+书写代码演示时，建议从简单用法开始介绍，不要上来就同时使用一大堆 API，会让人觉得难以上手。并且一个示例只演示一个 API 的使用方法，如无特殊需求不要在一个示例中同时演示多个 API 混合使用。
+
+```html
+<van-button :size="size">
+  Large
+</van-button>
+```
+
+```javascript
+export default {
+  data() {
+    return {
+      size: 'large'
+    };
+  }
+};
+```
+
+#### 5. API 说明
+
+组件的 API 说明，请以表格的形式书写，表格包含以下列：
+
+| 参数 | 说明 | 类型 | 默认值 |
+| ------------ | ------------- | -------- | ---------- |
+| visible | 是否可见 | bool | `false` |
+
+#### 6. Event 说明
+
+组件的 Event 说明，请以表格的形式书写，表格包含以下列：
+
+| 事件名 | 说明 | 参数 |
+|-----------|-----------|-----------|
+| click | 点击按钮时触发 | event：事件对象 |
+
+### 实用技巧
+
+#### 组件互相引用
+
+比如说 `Dialog` 里面引用了 `Button` 组件，直接写相对路径引用即可。
+
+```js
+import Button from '../button';
+```
+
+#### 组件创建
+
+Vant 中的组件会通过 `create` 方法统一创建，`create` 方法会在选项文件中注入基本的依赖和方法。
+
+```js
+import create from '../utils/create';
+
+export default create({
+  name: 'button'
+});
+```
+
+#### 样式
+
+组件样式使用 `precss 2.0` 作为预处理器，具体语法请参考 [precss 文档](https://github.com/jonathantneal/precss).

docs/markdown/style-guide.zh-CN.md

@@ -1,4 +1,4 @@
-# 风格指南
+## 风格指南
 
 在参与 Vant 开发时，请遵守约定的单文件组件风格指南，指南内容节选自 [Vue 官方风格指南](https://cn.vuejs.org/v2/style-guide)
 
@@ -47,13 +47,13 @@ MyComponent.vue
 components/
 |- TodoList.vue
 |- TodoItem.vue
-|- TodoButton.vue
+└─ TodoButton.vue
 
 // good
 components/
 |- TodoList.vue
 |- TodoListItem.vue
-|- TodoListItemButton.vue
+└─ TodoListItemButton.vue
 ```
 
 ### 自闭合组件

docs/src/doc.config.js

@@ -45,6 +45,14 @@ module.exports = {
                 path: '/theme',
                 title: '定制主题'
               },
+              {
+                path: '/contribution',
+                title: '开发指南'
+              },
+              {
+                path: '/style-guide',
+                title: '风格指南'
+              },
               {
                 path: '/demo',
                 title: '示例页面'

docs/src/docs-entry.js

@@ -3,10 +3,12 @@ export default {
   'changelog.en-US': () => import('../markdown/changelog.en-US.md'),
   'changelog.generated': () => import('../markdown/changelog.generated.md'),
   'changelog.zh-CN': () => import('../markdown/changelog.zh-CN.md'),
+  'contribution.zh-CN': () => import('../markdown/contribution.zh-CN.md'),
   'intro.en-US': () => import('../markdown/intro.en-US.md'),
   'intro.zh-CN': () => import('../markdown/intro.zh-CN.md'),
   'quickstart.en-US': () => import('../markdown/quickstart.en-US.md'),
   'quickstart.zh-CN': () => import('../markdown/quickstart.zh-CN.md'),
+  'style-guide.zh-CN': () => import('../markdown/style-guide.zh-CN.md'),
   'theme.en-US': () => import('../markdown/theme.en-US.md'),
   'theme.zh-CN': () => import('../markdown/theme.zh-CN.md'),
   'actionsheet.en-US': () => import('../../packages/actionsheet/en-US.md'),