整理部分 cli 文档

mipengine · Jul 19, 2018 · 65f5708 · 65f5708
1 parent eb17d88
commit 65f5708
Show file tree

Hide file tree

Showing 10 changed files with 1,180 additions and 1 deletion.
diff --git a/docs/basic/01-quick-start.md b/docs/basic/01-quick-start.md
@@ -0,0 +1,176 @@
+MIP（Mobile Instant Pages - 移动网页加速器）主要用于移动端页面加速。
+
+这篇文档将带你快速创建一个 MIP 页面。
+
+## 1. 创建 HTML 文件
+首先创建一个标准的 HTML 文件，注意：
+
+- 在 `<html>` 标签中增加 `mip` 属性标识。
+- 编码为 `utf-8` 。
+- 添加 `meta-viewport`，用于移动端展现。
+
+```html
+<!DOCTYPE html>
+<html mip>
+    <head>
+        <meta charset="UTF-8">
+        <meta name="viewport" content="width=device-width,minimum-scale=1,initial-scale=1">
+        <title>Hello World</title>
+    </head>
+    <body>
+        <h1>Hello World!</h1>
+    </body>
+</html>
+```
+
+## 2. 添加 MIP 运行环境
+在 HTML 代码中，添加 MIP 依赖的 `mip.js` 和 `mip.css` 。
+
+```html
+<!DOCTYPE html>
+<html mip>
+    <head>
+        <meta charset="UTF-8">
+        <meta name="viewport" content="width=device-width,minimum-scale=1,initial-scale=1">
+        <link rel="stylesheet" type="text/css" href="https://c.mipcdn.com/static/v2/mip.css">
+        <title>Hello World</title>
+    </head>
+    <body>
+        <h1>Hello World!</h1>
+        <script src="https://c.mipcdn.com/static/v2/mip.js"></script>
+    </body>
+</html>
+```
+
+## 3. 添加 MIP 关联标签
+`<link rel="miphtml">` 和 `<link rel="canonical">` 主要用于告知搜索引擎页面间的关系。添加关联标签后，MIP 页的会继承 **原页面**(移动端) 的点击权重，同时 **MIP 页** 将作为搜索引擎的首选导流页面。
+
+使用规则：
+
+- `<link rel="miphtml">` 在移动端页面（H5）使用，指向对应内容的 MIP 页，方便搜索引擎发现对应的 MIP 页。
+- `<link rel="canonical">` 在 MIP 页中使用，指向内容对应的移动端页面（H5）。
+- 若没有移动端页面（H5），则指向内容对应的 PC 页。
+- 若直接在原链接修改 MIP，则 Canonical 指向当前 URL 。
+
+```html
+<!DOCTYPE html>
+<html mip>
+    <head>
+        <meta charset="UTF-8">
+        <meta name="viewport" content="width=device-width,minimum-scale=1,initial-scale=1">
+        <link rel="stylesheet" type="text/css" href="https://c.mipcdn.com/static/v2/mip.css">
+        <!-- canonical 中的链接优先填写对应内容的移动端页面（H5）地址 -->
+        <link rel="canonical" href="https://www.example.com/your/path.html">
+        <title>Hello World</title>
+    </head>
+    <body>
+        <h1>Hello World!</h1>
+        <script src="https://c.mipcdn.com/static/v2/mip.js"></script>
+    </body>
+</html>
+```
+
+## 4. 添加样式
+出于速度考虑，建议內联使用 CSS 样式。所有样式写在 `<style mip-custom></style>` 中，注意：`style` 标签仅允许出现一次。
+
+```html
+<!DOCTYPE html>
+<html mip>
+    <head>
+        <meta charset="UTF-8">
+        <meta name="viewport" content="width=device-width,minimum-scale=1,initial-scale=1">
+        <link rel="stylesheet" type="text/css" href="https://c.mipcdn.com/static/v2/mip.css">
+        <!-- canonical 中的链接优先填写对应内容的移动端页面（H5）地址 -->
+        <link rel="canonical" href="https://www.example.com/your/path.html">
+        <title>Hello World</title>
+        <style mip-custom>
+            h1 { color: red;}
+        </style>
+    </head>
+    <body>
+        <h1>Hello World!</h1>
+        <script src="https://c.mipcdn.com/static/v2/mip.js"></script>
+    </body>
+</html>
+```
+
+## 5. 替换禁用 HTML 标签
+MIP 十分关注页面速度，也因此禁用了一些引起拖慢速度的 HTML 标签（[禁用列表](../specs/mip-html-spec.md)）。例如，`<img>` 标签会引起浏览器的 repaint 和 reflow，为了避免这些，MIP 提供了替代标签 `<mip-img>` ，详见 [`<mip-img>`使用文档](../components/builtin/mip-img.md) 。
+
+```html
+<!DOCTYPE html>
+<html mip>
+    <head>
+        <meta charset="UTF-8">
+        <meta name="viewport" content="width=device-width,minimum-scale=1,initial-scale=1">
+        <link rel="stylesheet" type="text/css" href="https://c.mipcdn.com/static/v2/mip.css">
+        <!-- canonical 中的链接优先填写对应内容的移动端页面（H5）地址 -->
+        <link rel="canonical" href="https://www.example.com/your/path.html">
+        <title>Hello World</title>
+        <style mip-custom>
+            h1 { color: red;}
+        </style>
+    </head>
+    <body>
+        <h1>Hello World!</h1>
+        <mip-img layout="responsive" width="350" height="263" src="https://www.mipengine.org/static/img/mip_logo_3b722d7.png" alt="MIP LOGO"></mip-img>
+        <script src="https://c.mipcdn.com/static/v2/mip.js"></script>
+    </body>
+</html>
+```
+
+## 6. 使用 MIP 组件
+出于对代码质量和性能的考虑，MIP 页中不允许自定义 JavaScript 代码。
+
+在一个合法的 MIP 页面中，所有的交互通过引入 MIP 组件实现。MIP 组件可以理解为封装了 JS 的自定义 HTML 标签。上一步中的 `<mip-img>` 也是一个 MIP 组件，[点击这里](../components/components-list.md) 查看更多组件。
+
+我们以分享组件为例，根据[分享组件文档](../components/extensions/mip-share.md)，组件对应的 HTML 标签为 `<mip-share>` ，需要依赖 <https://c.mipcdn.com/static/v2/mip-share/mip-share.js> 脚本，用在页面里就是这样：
+
+```html
+<!DOCTYPE html>
+<html mip>
+    <head>
+        <meta charset="UTF-8">
+        <meta name="viewport" content="width=device-width,minimum-scale=1,initial-scale=1">
+        <link rel="stylesheet" type="text/css" href="https://c.mipcdn.com/static/v2/mip.css">
+        <!-- canonical 中的链接优先填写对应内容的移动端页面（H5）地址 -->
+        <link rel="canonical" href="https://www.example.com/your/path.html">
+        <title>Hello World</title>
+        <style mip-custom>
+            h1 { color: red;}
+        </style>
+    </head>
+    <body>
+        <h1>Hello World!</h1>
+        <mip-img layout="responsive" width="350" height="263" src="https://www.mipengine.org/static/img/mip_logo_3b722d7.png" alt="MIP LOGO"></mip-img>
+        <mip-share title="分享：我的第一个 MIP 页面 "></mip-share>
+        <script src="https://c.mipcdn.com/static/v2/mip.js"></script>
+        <script src="https://c.mipcdn.com/static/v2/mip-share/mip-share.js"></script>
+    </body>
+</html>
+```
+
+在使用组件时，请注意阅读组件文档，查看组件是否依赖所需脚本。如果依赖，请在 `mip.js` 之后引入脚本。
+
+## 7. 预览
+开发完成后，可以使用 [MIP 校验工具](//www.mipengine.org/validator/validate) 保证代码规范。
+
+[info] 校验代码，使用 [MIP 校验工具](//www.mipengine.org/validator/validate)。<br> 预览线上 URL 异步打开效果，使用 [MIP 预览工具](//www.mipengine.org/validator/preview)。
+
+MIP 页文件可以直接运行，你可以选择如下方式，像预览普通 HTML 站点一样预览 MIP-HTML 页面：
+
+- 直接在浏览器中打开（由于 XML HTTP Requests 失败可能会导致某些元素预览失败）。
+- 在本地部署一个服务，如 Apache，Nginx 等。
+- 使用 MIP-CLI 辅助预览，使用方法见[mip-cli 用法](../cli/cli-usage.md)。
+
+
+## 8. 起飞
+到目前为止，你已经创建好了一个 MIP 页面。这个页面有图、有文、能分享，可以在浏览器中运行。
+
+进阶的内容，请参考：
+
+- [MIP-HTML 规范](../specs/mip-html-spec.md)
+- [组件布局](../components/layout.md)
+- [MIP 加速原理](./principle-of-mip.md)
+- [扩展组件开发规范](../specs/mip-components-spec.md)
+
diff --git a/docs/cli/start-writing-first-mip.md b/docs/cli/start-writing-first-mip.md
@@ -1,4 +1,4 @@
-# 快速开始
+# 使用 mip-cli 快速开始
 
 - [编写第一个 MIP 页面](#编写-mip-页面)
 - [编写第一个 MIP 组件](#编写-mip-组件)

diff --git a/docs/new-doc/mip-cli/01-cli-usage.md b/docs/new-doc/mip-cli/01-cli-usage.md
@@ -0,0 +1,139 @@
+# mip2 命令行工具
+
+mip2 CLI 是官方提供的命令行工具，它提供了脚手架、调试、预览、校验、构建等功能，方便开发者快速开发 MIP 页面及自定义组件。
+
+## 1. 依赖环境
+
+mip2 CLI 使用 NPM 安装，依赖 Node 环境，推荐
+
+- [Node.js](https://nodejs.org/) (>=8.x)
+
+- [Git](https://git-scm.com/)
+
+## 2. 安装 mip2 CLI
+
+打开命令行工具，输入：
+
+``` bash
+$ npm install -g mip2
+```
+
+输入 `mip2 -V`，若能正常显示版本号，说明已经安装成功。
+
+## 3. mip2 CLI 使用
+
+### 创建项目脚手架
+
+``` bash
+$ mip2 init
+```
+
+根据提示输入项目名 `myproject`，生成项目结构如下
+
+```bash
+myproject
+    ├── common                          // 组件公用代码，如 utils 等
+    ├── components                      // 组件目录，编写组件代码
+    │   └── mip-example
+    │       ├── mip-example.md          // 组件功能、属性说明
+    │       ├── mip-example.vue         // 组件本身
+    │       └── example
+    │           └── mip-example.html    // 单个组件测试、预览
+    ├── mip.config.js                   // 调试服务器配置
+    ├── package.json
+    ├── static                          // 静态资源，如图片、字体
+    └── example
+        └── index.html                  // 页面测试预览
+```
+
+我们可以在项目的 `components` 目录中开发站点所需的自定义组件，然后依据 `example/index.html` 页面模板，引用官方或自定义组件来实现 MIP 页面。
+
+通常情况下，官方提供的[通用组件库](https://github.com/mipengine/mip2-extensions)已经能满足站点的基本需求。如果站点有使用复杂组件的场景，我们可以[编写站长自定义组件](./08-contribute-to-site-extensions-repo.md)，并通过[站长组件仓库](https://github.com/mipengine/mip2-extensions-platform)进行提交，通过审核上线后，即能使用。
+
+同时，我们也欢迎开发者向官方通用组件库[贡献优秀的组件](./07-contribute-to-official-repo.md)。
+
+### 新增一个组件
+
+在项目根目录运行 `mip2 add` 命令，即可快速添加一个新组件
+
+```bash
+# 快速添加名为 mip-new 的组件
+$ mip2 add mip-new
+
+# 使用 -f 或 --force 参数强制覆盖同名组件
+$ mip2 add mip-new -f
+```
+
+### 启动调试服务器
+
+命令行工具内置了简单的调试服务器，方便开发者调试组件和页面。在项目根目录运行
+
+``` bash
+$ mip2 dev
+```
+
+默认会在 `8111` 端口启动服务器，并自动调起浏览器打开 `example/index.html` ，实现预览和调试。在修改组件和页面的代码时，无需手动重启和刷新，服务器内部已经帮我们实现了这一功能。
+
+了解详细用法：[调试组件](./05-component-testing.md)
+
+### 组件和页面校验
+
+MIP 组件和页面都需要遵循特定的[开发规范](../components/rules.md)，开发者提交站点 url 和组件代码时，系统会进行审核和校验。命令行工具提供了校验功能，方便我们在开发阶段就能按照相关规范进行开发和调整。
+
+``` bash
+# 校验 mip 组件，输入组件目录
+$ mip2 validate -c ./components
+
+# 校验 mip 页面，输入页面路径
+$ mip2 validate -p page.html
+```
+
+我们可以根据校验结果，对不符合规范的组件/页面进行相应的改进，校验通过后再进行提交。
+
+### 构建组件
+
+自定义组件开发完成后，可以使用 `mip2 build` 命令将组件代码打包成为对应的 `mip-组件名.js` 文件，供发布使用。
+
+在项目根目录运行
+
+``` bash
+$ mip2 build
+```
+
+默认将在 /dist 目录产出打包压缩后的组件资源。了解详细用法：[组件构建](./04-component-development.md)
+
+### 生成 Service Worker
+
+mip2 CLI 提供了 `sw` 命令，帮助开发者更简单快速地生成 Service Worker，支持离线可用等特性。
+
+``` bash
+# 在项目根目录运行
+$ mip2 sw
+```
+
+默认情况下，将导出 Service Worker 文件到 `dist/sw.js`，并对静态资源(如 js,css)及 html 文档进行缓存，实现页面的离线可用。
+
+`mip2 sw` 命令提供了选项：
+
+``` javascript
+-o, --output // 指定 sw 导出路径，如 mip2 -o output/service-worker.js
+-c, --config // 指定配置文件路径，默认使用项目根目录 mip.config.js
+```
+
+除此之外，我们可以在 `mip.config.js` 中增加 `serviceWorker` 配置项，对 Service Worker 进行进一步的配置，如预缓存列表、动态缓存策略、`skipWaiting`、`clientsClaim` 等。
+
+``` javascript
+module.exports = {
+  dev: {/*...*/},
+  serviceWorker: {
+    cacheId: 'mipuser',
+    skipWaiting: true,
+    clientsClaim: true,
+    runtimeCaching: [],
+    globPatterns: [],
+    globIgnores: []
+  }
+}
+```
+
+更多的配置选项可以参考 [Workbox 配置项](https://developers.google.com/web/tools/workbox/modules/workbox-build#generateswstring_mode)