MIP 官网贡献指南

非常感谢您关注 mipengine/www.mipengine.org 项目，在提交您的贡献之前，请务必认真阅读以下准则。

问题反馈

  • 请避免提交重复的 Issue，在提交之前搜索现有的 Issue 。
  • 请确定 Issue 的类型，并在 Issue 内容描述清晰，我们将根据内容对 Issue 打上对应的 label 。
  • 组件列表 内所有组件文档请参考文档页面标题右侧编辑按钮提交。

开发设置

需要安装 nodejs 版本4+ ，下载项目到本地后安装依赖 npm install ，安装完成后将自动更新 核心内置组件 和 官方扩展组件文档 到本地。

常用脚本命令（npm scripts）

  1. # 启动本地 http 服务器用来本地预览
  2. $ npm run dev
  4. # 编译 markdown 文档为 html 文件
  5. $ npm run build
  7. # 同步最新的核心内置组件文档和官方扩展组件文档
  8. $ npm run sync-components
  10. # 验证编译生成的 html 文件是否符合 MIP 规范
  11. $ npm run validator
  13. # 使用 fecs 验证代码风格
  14. $ npm run lint

代码风格

基于 https://github.com/ecomfe/spec 风格编写代码，基于 https://github.com/ecomfe/fecs/ 验证代码风格。

项目结构

  1. .
  2. ├── _config.yml             - 站点常用配置项
  3. ├── dist                    - `npm run build` 生成 html 文件目录
  4. ├── scripts                 - 基于 Hexo 的扩展插件
  5. ├── source                  - 文档数据源
  6. │   ├── _data
  7. │   │   ├── menu.yml        - 顶部导航配置
  8. │   │   └── sidebar.yml     - 文档左面导航配置
  9. │   ├── doc                 - 文档 Markdown 源文件目录
  10. │   └── examples            - 组件预览源目录，该目录不在本仓库维护
  11. ├── test                    - 验证 MIP 规范、死链接检测脚本
  12. ├── themes                  - MIP 官网定制化主题
  13. │   └── mip
  14. │       ├── layout
  15. │       │   ├── doc.swig                - 文档模板
  16. │       │   ├── examples.swig           - 组件预览模板
  17. │       │   ├── index.swig              - 主页模板
  18. │       │   ├── mip.layout.swig         - mip基础模板
  19. │       │   ├── mippath.swig            - MIP PATH 路径转换模板
  20. │       │   ├── nomip.layout.swig       - 非 MIP 页基础模板
  21. │       │   ├── post.swig               - 文章模板
  22. │       │   └── timeline.swig           - 项目进展模板
  23. └── tools
  24.     ├── changelog.json      - MIP 项目进展配置
  25.     ├── components.json     - MIP 组件文档配置

提交请求（pull request）

  1. fork mipengine/www.mipengine.org
  2. 把个人仓库（repository）克隆到电脑上，并安装所依赖的插件。
  3. 开始编辑文件，可以通过命令 npm run dev 预览编辑的效果，编辑完成后，需要检查：
    1. 运行 npm run validator 确保 MIP 规范验证通过。
    2. 运行 npm run lint 确保代码风格验证通过。
  4. 推送（push）分支。
  5. 建立一个新的合并申请（pull request）并描述变动。

提交信息规范

git commit 信息和 pull request 标题必须遵循 MIP 项目的 提交信息规范 ，否则不予合入。

文档说明

  • 文档基于 Markdown 格式编写。
  • 文档编辑地址可通过访问文档右上角编辑按钮获得。
  • 文档内链接使用绝对路径，如： [新的起点](/doc/00-mip-101.html) 。
  • 使用中文半角标点符号。

文档提醒语法

在段落前插入 特殊标记 用于重点强调信息，如：

  1. [notice] MIP 十分关注页面速度，也因此禁用了一些引起拖慢速度的 HTML 标签。
  3. [info] MIP-HTML 基于 HTML 基础规范进行了扩展。
  5. [warning] 出于对代码质量和性能的考虑， MIP 页中不允许自定义 JavaScript 代码。

显示的样式如下：

image

新增文档

文档目录

在 source/ 对应目录下新增 .md 文件，如：

  • source/demos.md 对应链接路径 /demos.html
  • source/test/index.md 对应链接路径 /test
  • source/test/ok.md 对应链接路径 /test/ok.html
  • source/doc/mip-cdn.md 对应链接路径 /doc/mip-cdn.html

文档配置

  1. title: MIP
  2. layout: post
  3. keywords: 关键词
  4. description: 描述
  5. ---
  7. 我是内容

注意：

  • title - 配置页面标题内容。
  • layout: post - 配置继承 themes/mip/layout/post.swig 模板，为文章类型，也可以继承 doc 模板。
  • keywords - 配置页面关键词信息，默认为 _config.yml 配置内容，如果为 false 表示不输出。
  • description - 配置页面描述信息，默认为 _config.yml 配置内容，如果为 false 表示不输出。