Merge branch 'master' of github.com:mipengine/mip2

mipengine · Jul 20, 2018 · 998014b · 998014b
2 parents fd1087c + e7f11af
commit 998014b
Show file tree

Hide file tree

Showing 12 changed files with 424 additions and 45 deletions.
diff --git a/docs/new-doc/meta.json b/docs/new-doc/meta.json
@@ -3,6 +3,32 @@
     {
       "name": "简介",
       "key": "basic"
+    },
+    {
+      "name": "开发规范",
+      "key": "mip-standard",
+      "children": [
+          {
+              "name": "MIP-HTML 规范",
+              "key": "01-mip-html-spec"
+          },
+          {
+              "name": "MIP-Cache 规范",
+              "key": "02-mip-cache-spec"
+          },
+          {
+              "name": "MIP 校验规则",
+              "key": "03-mip-validate"
+          },
+          {
+              "name": "Canonical 使用规范",
+              "key": "04-mip-canonical"
+          },
+          {
+              "name": "组件开发规范",
+              "key": "05-mip-components-spec"
+          }
+      ]
     }
   ]
 }
diff --git a/docs/new-doc/mip-cli/meta.json b/docs/new-doc/mip-cli/meta.json
@@ -0,0 +1,26 @@
+
+{
+    "menu": [
+        {
+            "key": "01-cli-usage"
+        },
+        {
+            "key": "03-start-writing-first-mip"
+        },
+        {
+            "key": "04-component-development"
+        },
+        {
+            "key": "05-component-testing"
+        },
+        {
+            "key": "06-component-deploy"
+        },
+        {
+            "key": "07-contribute-to-official-repo"
+        },
+        {
+            "key": "08-contribute-to-site-extensions-repo"
+        }
+    ]
+}
diff --git a/docs/new-doc/mip-standard/01-mip-html-spec.md b/docs/new-doc/mip-standard/01-mip-html-spec.md
@@ -9,7 +9,7 @@ MIP 规范是高性能 MIP 页面的保证，其中最重要的规范是：MIP H
 由于规范长期更新，更多最新规范可查阅 MIP 官方网站 MIP HTML规范章节。
 
 <a name="1"></a>
-### 1．头部使用规范
+### 1. 头部使用规范
 下面简要列出MIP页头部的使用规范。头部是MIP页的声明、配置信息、资源引入的主要区域。
   - 页面起始标签使用 <!DOCTYPE html>
   - `<html>` 标签必写且唯一，同时必须存在 mip 属性，即：`<html mip>` 。
@@ -24,7 +24,7 @@ MIP 规范是高性能 MIP 页面的保证，其中最重要的规范是：MIP H
 
 
 <a name="2"></a>
-### 2．页面元素
+### 2. 页面元素
 
 MIP-HTML 禁止使用对页面性能以及安全有较大影响的标签，同时也规定了元素的使用方式。
 
@@ -137,13 +137,13 @@ MIP-HTML 禁止使用对页面性能以及安全有较大影响的标签，同
 
 
 <a name="3"></a>
-### HTML 属性
+### 3. HTML 属性
 - MIP-HTML 中所有 `on` 开头的属性都不允许使用，如：`onclick`，`onmouseover` 。
 - MIP-HTML 中允许使用 `on` 属性。
 - MIP-HTML 中不允许使用 `style` 属性。
 
 <a name="4"></a>
-### 3．自定义样式使用规范
+### 4. 自定义样式使用规范
 出于性能考虑，HTML 中不允许使用内联 `style`，所有样式只能放到 `<head>` 的 `<style>` 标签里。
 
 正确方式：

diff --git a/docs/new-doc/mip-standard/04-mip-canonical.md b/docs/new-doc/mip-standard/04-mip-canonical.md
@@ -0,0 +1,48 @@
+title: Canonical 使用规范
+layout: doc
+---
+
+在某些情况下，站点对于同一个 HTML 页面，可能存在两种，一个是 MIP 页，一个是原页面。搜索引擎会抓取这两个页面，并利用 Canonical 标签将它们联系起来。
+
+## 关联标签
+
+你必须在 MIP 添加`<link rel="canonical">`指向原始页面，以保证 MIP 更好的继承原始页面的权重。
+
+使用规则：
+
+- `<link rel="miphtml">`在移动端页面（H5）使用，指向对应内容的 MIP 页，方便搜索引擎发现对应的 MIP 页。
+- `<link rel="canonical">`在 MIP 页中使用, 指向内容对应的移动端页面（H5）。
+- 若没有移动端页面（H5），则指向内容对应的 PC 页。
+- 若直接在原链接修改 MIP ，则 Canonical 指向当前 URL 。
+
+## 在 head 中添加关联标签让搜索引擎发现你的页面
+
+### MIP 和 非 MIP 页面同时存在
+
+在 MIP 页中添加：
+
+```html
+<link rel="canonical" href="https://www.example.com/your/path.html">
+```
+
+### 如果只有 MIP 页
+
+同样需要添加，指向自己（当前页面）：
+
+```html
+<link rel="canonical" href="https://www.example.com/mip/path.html">
+```
+
+## 新建 MIP 页的文件 path 建议
+
+[info] 原网页与 MIP 页的 URL 的对应关系尽量简单、直接。
+
+原网页出现的文档名或文档 ID ，在 MIP 页命名时也要出现。如：原页面 url 为 `https://www.example.com/123.html` 。
+
+例子|是否可用
+--|--
+`https://mip.example.com/123.html` | <span class="mipengine-doc-green">可用，推荐</span>
+`https://www.example.com/mip/123.html` | <span class="mipengine-doc-green">可用，推荐</span>
+`https://www.example.com/mip_123.html` | <span class="mipengine-doc-green">可用</span>
+`https://mip.example.com/mip_123.html` | <span class="mipengine-doc-green">可用</span>
+`https://www.example.com/mip_001.html` | <span class="mipengine-doc-orange">不建议（链接 ID 不对应）</span>
diff --git a/docs/new-doc/mip-standard/05-mip-components-spec.md b/docs/new-doc/mip-standard/05-mip-components-spec.md
@@ -2,12 +2,33 @@
 
 在本文档中，使用的关键字会以英文表示：`"MUST"`, `"MUST NOT"`, `"REQUIRED"`, `"SHALL"`, `"SHALL NOT"`, `"SHOULD"`, `"SHOULD NOT"`, `"RECOMMENDED"`, `"MAY"`, 和 `"OPTIONAL"`被定义在 rfc2119 中。
 
-## 代码结构规范
+## 源文件仓库
+
+MIP 扩展组件的中央仓库是 https://github.com/mipengine/mip2-extensions 。中央仓库 master 分支下的代码永远是稳定的。根目录下，每个 mip- 前缀的目录为一个扩展组件。
+
+## 开发方式
+
+MIP 扩展组件开发采用 [Forking工作流](https://github.com/oldratlee/translations/blob/master/git-workflows-and-tutorials/workflow-forking.md) 的方式。
+
+  - 开发者需要 fork MIP 扩展组件仓库
+  - 开发者在自己的仓库下开发
+  - 开发完成后通过 pull request 提交修改，由 MIP 开发小组审核与合并
+  - 不允许在主仓库 https://github.com/mipengine/mip2-extensions 下开发。
+
+
+## 审核标准
+
+  - <a href="#1">结构规范</a>
+  - <a href="#2">JavaScript 规范</a>
+  - <a href="#3">CSS 规范</a>
+
+<a name="1"></a>
+### 结构规范
 
 - [MUST] 所有组件目录必须是组件名称
 - [MUST] 目录名称（组件名称）必须是 `mip-` 为前缀的全小写字符串
 - [MUST] 所有组件必须是 `.vue` 后缀的 [单文件组件](https://cn.vuejs.org/v2/guide/single-file-components.html) 形式
-- [MUST] 必须包含说明组件用途的 `mip-xxx.md` 文件
+- [MUST] 必须包含说明组件用途的 `mip-xxx.md` 文件，具体规范可参照自动生成的 `README.md` 模板文件结构进行填充。
 
 示例：
 
@@ -17,25 +38,23 @@ mip-example
   ├── mip-example.vue
 ```
 
-## 代码风格规范
+<a name="2"></a>
+### JavaScript 规范
 
 - [MUST] 组件的脚本开发必须遵守 JavaScript Standard Style [[CN](https://standardjs.com/rules-zhcn.html)/[EN](https://standardjs.com/rules-en.html)] 代码规范
 - [MUST] 组件的模版开发应该遵循 [Vue Style Guide](https://cn.vuejs.org/v2/style-guide/index.html)
-
-开发过程中可以通过 [ESLint](https://eslint.org/) 工具检查，在组件校验和审核环节要求所有代码必须通过 ESLint，一般不允许使用 `eslint-disable` 来豁免检测。
-
-
-## JavaScript 规范
-
 - [SHOULD] 使用 ES6 和 ES Module 模块化组织代码
 - [MUST] 仅允许引入白名单（TODO: 白名单列表）中的第三方 javaScript
 
+开发过程中可以通过 [ESLint](https://eslint.org/) 工具检查，在组件校验和审核环节要求所有代码必须通过 ESLint，一般不允许使用 `eslint-disable` 来豁免检测。
 
-## CSS 规范
 
+<a name="3"></a>
+### CSS 规范
+
+- [MUST] 组件的样式必须遵循 Stylelint 中 [`stylelint-config-standard`](https://github.com/stylelint/stylelint-config-standard) 中包含的规范，且必须通过 Stylelint 工具审核之后才能提交。
 - [MUST] 组件所有样式必须 scoped
 - [MUST NOT] 组件样式禁止使用 `position: fixed`
-- [MUST] 组件的样式开发必须遵循 Stylelint 中 `stylelint-config-standard` 中的规范，且必须通过 Stylelint 工具审核之后才能提交。
 - [MUST] 所有样式文件必须使用 UTF-8 编码
 - [MUST] 选择器的第一层如果是标签选择器，只允许使用组件自身标签，组件的样式定义应只对组件本身以及组件内部生效。
 
@@ -66,3 +85,6 @@ span {
 ```
 
 - [SHOULD NOT] 不允许使用 ID 选择器：组件的设计，需要考虑一个页面上同时存在多个组件的场景。所以组件及内部元素都不应该拥有 hard code 的 ID 属性。
+
+
+