Skip to content

Commit 65f5708

Browse files
chenqiushichenqiushi
committed
整理部分 cli 文档
1 parent eb17d88 commit 65f5708

10 files changed

+1180
-1
lines changed

‎docs/basic/01-quick-start.md

Lines changed: 176 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,176 @@
1+
MIP（Mobile Instant Pages - 移动网页加速器）主要用于移动端页面加速。
2+
3+
这篇文档将带你快速创建一个 MIP 页面。
4+
5+
## 1. 创建 HTML 文件
6+
首先创建一个标准的 HTML 文件，注意：
7+
8+
- 在 `<html>` 标签中增加 `mip` 属性标识。
9+
- 编码为 `utf-8` 。
10+
- 添加 `meta-viewport`，用于移动端展现。
11+
12+
```html
13+
<!DOCTYPE html>
14+
<html mip>
15+
<head>
16+
<meta charset="UTF-8">
17+
<meta name="viewport" content="width=device-width,minimum-scale=1,initial-scale=1">
18+
<title>Hello World</title>
19+
</head>
20+
<body>
21+
<h1>Hello World!</h1>
22+
</body>
23+
</html>
24+
```
25+
26+
## 2. 添加 MIP 运行环境
27+
在 HTML 代码中，添加 MIP 依赖的 `mip.js` 和 `mip.css` 。
28+
29+
```html
30+
<!DOCTYPE html>
31+
<html mip>
32+
<head>
33+
<meta charset="UTF-8">
34+
<meta name="viewport" content="width=device-width,minimum-scale=1,initial-scale=1">
35+
<link rel="stylesheet" type="text/css" href="https://c.mipcdn.com/static/v2/mip.css">
36+
<title>Hello World</title>
37+
</head>
38+
<body>
39+
<h1>Hello World!</h1>
40+
<script src="https://c.mipcdn.com/static/v2/mip.js"></script>
41+
</body>
42+
</html>
43+
```
44+
45+
## 3. 添加 MIP 关联标签
46+
`<link rel="miphtml">` 和 `<link rel="canonical">` 主要用于告知搜索引擎页面间的关系。添加关联标签后，MIP 页的会继承 **原页面**(移动端) 的点击权重，同时 **MIP 页** 将作为搜索引擎的首选导流页面。
47+
48+
使用规则：
49+
50+
- `<link rel="miphtml">` 在移动端页面（H5）使用，指向对应内容的 MIP 页，方便搜索引擎发现对应的 MIP 页。
51+
- `<link rel="canonical">` 在 MIP 页中使用，指向内容对应的移动端页面（H5）。
52+
- 若没有移动端页面（H5），则指向内容对应的 PC 页。
53+
- 若直接在原链接修改 MIP，则 Canonical 指向当前 URL 。
54+
55+
```html
56+
<!DOCTYPE html>
57+
<html mip>
58+
<head>
59+
<meta charset="UTF-8">
60+
<meta name="viewport" content="width=device-width,minimum-scale=1,initial-scale=1">
61+
<link rel="stylesheet" type="text/css" href="https://c.mipcdn.com/static/v2/mip.css">
62+
<!-- canonical 中的链接优先填写对应内容的移动端页面（H5）地址 -->
63+
<link rel="canonical" href="https://www.example.com/your/path.html">
64+
<title>Hello World</title>
65+
</head>
66+
<body>
67+
<h1>Hello World!</h1>
68+
<script src="https://c.mipcdn.com/static/v2/mip.js"></script>
69+
</body>
70+
</html>
71+
```
72+
73+
## 4. 添加样式
74+
出于速度考虑，建议內联使用 CSS 样式。所有样式写在 `<style mip-custom></style>` 中，注意：`style` 标签仅允许出现一次。
75+
76+
```html
77+
<!DOCTYPE html>
78+
<html mip>
79+
<head>
80+
<meta charset="UTF-8">
81+
<meta name="viewport" content="width=device-width,minimum-scale=1,initial-scale=1">
82+
<link rel="stylesheet" type="text/css" href="https://c.mipcdn.com/static/v2/mip.css">
83+
<!-- canonical 中的链接优先填写对应内容的移动端页面（H5）地址 -->
84+
<link rel="canonical" href="https://www.example.com/your/path.html">
85+
<title>Hello World</title>
86+
<style mip-custom>
87+
h1 { color: red;}
88+
</style>
89+
</head>
90+
<body>
91+
<h1>Hello World!</h1>
92+
<script src="https://c.mipcdn.com/static/v2/mip.js"></script>
93+
</body>
94+
</html>
95+
```
96+
97+
## 5. 替换禁用 HTML 标签
98+
MIP 十分关注页面速度，也因此禁用了一些引起拖慢速度的 HTML 标签（[禁用列表](../specs/mip-html-spec.md)）。例如，`<img>` 标签会引起浏览器的 repaint 和 reflow，为了避免这些，MIP 提供了替代标签 `<mip-img>` ，详见 [`<mip-img>`使用文档](../components/builtin/mip-img.md) 。
99+
100+
```html
101+
<!DOCTYPE html>
102+
<html mip>
103+
<head>
104+
<meta charset="UTF-8">
105+
<meta name="viewport" content="width=device-width,minimum-scale=1,initial-scale=1">
106+
<link rel="stylesheet" type="text/css" href="https://c.mipcdn.com/static/v2/mip.css">
107+
<!-- canonical 中的链接优先填写对应内容的移动端页面（H5）地址 -->
108+
<link rel="canonical" href="https://www.example.com/your/path.html">
109+
<title>Hello World</title>
110+
<style mip-custom>
111+
h1 { color: red;}
112+
</style>
113+
</head>
114+
<body>
115+
<h1>Hello World!</h1>
116+
<mip-img layout="responsive" width="350" height="263" src="https://www.mipengine.org/static/img/mip_logo_3b722d7.png" alt="MIP LOGO"></mip-img>
117+
<script src="https://c.mipcdn.com/static/v2/mip.js"></script>
118+
</body>
119+
</html>
120+
```
121+
122+
## 6. 使用 MIP 组件
123+
出于对代码质量和性能的考虑，MIP 页中不允许自定义 JavaScript 代码。
124+
125+
在一个合法的 MIP 页面中，所有的交互通过引入 MIP 组件实现。MIP 组件可以理解为封装了 JS 的自定义 HTML 标签。上一步中的 `<mip-img>` 也是一个 MIP 组件，[点击这里](../components/components-list.md) 查看更多组件。
126+
127+
我们以分享组件为例，根据[分享组件文档](../components/extensions/mip-share.md)，组件对应的 HTML 标签为 `<mip-share>` ，需要依赖 <https://c.mipcdn.com/static/v2/mip-share/mip-share.js> 脚本，用在页面里就是这样：
128+
129+
```html
130+
<!DOCTYPE html>
131+
<html mip>
132+
<head>
133+
<meta charset="UTF-8">
134+
<meta name="viewport" content="width=device-width,minimum-scale=1,initial-scale=1">
135+
<link rel="stylesheet" type="text/css" href="https://c.mipcdn.com/static/v2/mip.css">
136+
<!-- canonical 中的链接优先填写对应内容的移动端页面（H5）地址 -->
137+
<link rel="canonical" href="https://www.example.com/your/path.html">
138+
<title>Hello World</title>
139+
<style mip-custom>
140+
h1 { color: red;}
141+
</style>
142+
</head>
143+
<body>
144+
<h1>Hello World!</h1>
145+
<mip-img layout="responsive" width="350" height="263" src="https://www.mipengine.org/static/img/mip_logo_3b722d7.png" alt="MIP LOGO"></mip-img>
146+
<mip-share title="分享：我的第一个 MIP 页面 "></mip-share>
147+
<script src="https://c.mipcdn.com/static/v2/mip.js"></script>
148+
<script src="https://c.mipcdn.com/static/v2/mip-share/mip-share.js"></script>
149+
</body>
150+
</html>
151+
```
152+
153+
在使用组件时，请注意阅读组件文档，查看组件是否依赖所需脚本。如果依赖，请在 `mip.js` 之后引入脚本。
154+
155+
## 7. 预览
156+
开发完成后，可以使用 [MIP 校验工具](//www.mipengine.org/validator/validate) 保证代码规范。
157+
158+
[info] 校验代码，使用 [MIP 校验工具](//www.mipengine.org/validator/validate)。<br> 预览线上 URL 异步打开效果，使用 [MIP 预览工具](//www.mipengine.org/validator/preview)。
159+
160+
MIP 页文件可以直接运行，你可以选择如下方式，像预览普通 HTML 站点一样预览 MIP-HTML 页面：
161+
162+
- 直接在浏览器中打开（由于 XML HTTP Requests 失败可能会导致某些元素预览失败）。
163+
- 在本地部署一个服务，如 Apache，Nginx 等。
164+
- 使用 MIP-CLI 辅助预览，使用方法见[mip-cli 用法](../cli/cli-usage.md)。
165+
166+
167+
## 8. 起飞
168+
到目前为止，你已经创建好了一个 MIP 页面。这个页面有图、有文、能分享，可以在浏览器中运行。
169+
170+
进阶的内容，请参考：
171+
172+
- [MIP-HTML 规范](../specs/mip-html-spec.md)
173+
- [组件布局](../components/layout.md)
174+
- [MIP 加速原理](./principle-of-mip.md)
175+
- [扩展组件开发规范](../specs/mip-components-spec.md)
176+

‎docs/cli/start-writing-first-mip.md

Lines changed: 1 addition & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -1,4 +1,4 @@
1-
# 快速开始
1+
# 使用 mip-cli 快速开始
22

33
- [编写第一个 MIP 页面](#编写-mip-页面)
44
- [编写第一个 MIP 组件](#编写-mip-组件)

‎docs/new-doc/mip-cli/01-cli-usage.md

Lines changed: 139 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,139 @@
1+
# mip2 命令行工具
2+
3+
mip2 CLI 是官方提供的命令行工具，它提供了脚手架、调试、预览、校验、构建等功能，方便开发者快速开发 MIP 页面及自定义组件。
4+
5+
## 1. 依赖环境
6+
7+
mip2 CLI 使用 NPM 安装，依赖 Node 环境，推荐
8+
9+
- [Node.js](https://nodejs.org/) (>=8.x)
10+
11+
- [Git](https://git-scm.com/)
12+
13+
## 2. 安装 mip2 CLI
14+
15+
打开命令行工具，输入：
16+
17+
``` bash
18+
$ npm install -g mip2
19+
```
20+
21+
输入 `mip2 -V`，若能正常显示版本号，说明已经安装成功。
22+
23+
## 3. mip2 CLI 使用
24+
25+
### 创建项目脚手架
26+
27+
``` bash
28+
$ mip2 init
29+
```
30+
31+
根据提示输入项目名 `myproject`，生成项目结构如下
32+
33+
```bash
34+
myproject
35+
├── common // 组件公用代码，如 utils 等
36+
├── components // 组件目录，编写组件代码
37+
│   └── mip-example
38+
│   ├── mip-example.md // 组件功能、属性说明
39+
│   ├── mip-example.vue // 组件本身
40+
│   └── example
41+
│   └── mip-example.html // 单个组件测试、预览
42+
├── mip.config.js // 调试服务器配置
43+
├── package.json
44+
├── static // 静态资源，如图片、字体
45+
└── example
46+
└── index.html // 页面测试预览
47+
```
48+
49+
我们可以在项目的 `components` 目录中开发站点所需的自定义组件，然后依据 `example/index.html` 页面模板，引用官方或自定义组件来实现 MIP 页面。
50+
51+
通常情况下，官方提供的[通用组件库](https://github.com/mipengine/mip2-extensions)已经能满足站点的基本需求。如果站点有使用复杂组件的场景，我们可以[编写站长自定义组件](./08-contribute-to-site-extensions-repo.md)，并通过[站长组件仓库](https://github.com/mipengine/mip2-extensions-platform)进行提交，通过审核上线后，即能使用。
52+
53+
同时，我们也欢迎开发者向官方通用组件库[贡献优秀的组件](./07-contribute-to-official-repo.md)。
54+
55+
### 新增一个组件
56+
57+
在项目根目录运行 `mip2 add` 命令，即可快速添加一个新组件
58+
59+
```bash
60+
# 快速添加名为 mip-new 的组件
61+
$ mip2 add mip-new
62+
63+
# 使用 -f 或 --force 参数强制覆盖同名组件
64+
$ mip2 add mip-new -f
65+
```
66+
67+
### 启动调试服务器
68+
69+
命令行工具内置了简单的调试服务器，方便开发者调试组件和页面。在项目根目录运行
70+
71+
``` bash
72+
$ mip2 dev
73+
```
74+
75+
默认会在 `8111` 端口启动服务器，并自动调起浏览器打开 `example/index.html` ，实现预览和调试。在修改组件和页面的代码时，无需手动重启和刷新，服务器内部已经帮我们实现了这一功能。
76+
77+
了解详细用法：[调试组件](./05-component-testing.md)
78+
79+
### 组件和页面校验
80+
81+
MIP 组件和页面都需要遵循特定的[开发规范](../components/rules.md)，开发者提交站点 url 和组件代码时，系统会进行审核和校验。命令行工具提供了校验功能，方便我们在开发阶段就能按照相关规范进行开发和调整。
82+
83+
``` bash
84+
# 校验 mip 组件，输入组件目录
85+
$ mip2 validate -c ./components
86+
87+
# 校验 mip 页面，输入页面路径
88+
$ mip2 validate -p page.html
89+
```
90+
91+
我们可以根据校验结果，对不符合规范的组件/页面进行相应的改进，校验通过后再进行提交。
92+
93+
### 构建组件
94+
95+
自定义组件开发完成后，可以使用 `mip2 build` 命令将组件代码打包成为对应的 `mip-组件名.js` 文件，供发布使用。
96+
97+
在项目根目录运行
98+
99+
``` bash
100+
$ mip2 build
101+
```
102+
103+
默认将在 /dist 目录产出打包压缩后的组件资源。了解详细用法：[组件构建](./04-component-development.md)
104+
105+
### 生成 Service Worker
106+
107+
mip2 CLI 提供了 `sw` 命令，帮助开发者更简单快速地生成 Service Worker，支持离线可用等特性。
108+
109+
``` bash
110+
# 在项目根目录运行
111+
$ mip2 sw
112+
```
113+
114+
默认情况下，将导出 Service Worker 文件到 `dist/sw.js`，并对静态资源(如 js,css)及 html 文档进行缓存，实现页面的离线可用。
115+
116+
`mip2 sw` 命令提供了选项：
117+
118+
``` javascript
119+
-o, --output // 指定 sw 导出路径，如 mip2 -o output/service-worker.js
120+
-c, --config // 指定配置文件路径，默认使用项目根目录 mip.config.js
121+
```
122+
123+
除此之外，我们可以在 `mip.config.js` 中增加 `serviceWorker` 配置项，对 Service Worker 进行进一步的配置，如预缓存列表、动态缓存策略、`skipWaiting`、`clientsClaim` 等。
124+
125+
``` javascript
126+
module.exports = {
127+
dev: {/*...*/},
128+
serviceWorker: {
129+
cacheId: 'mipuser',
130+
skipWaiting: true,
131+
clientsClaim: true,
132+
runtimeCaching: [],
133+
globPatterns: [],
134+
globIgnores: []
135+
}
136+
}
137+
```
138+
139+
更多的配置选项可以参考 [Workbox 配置项](https://developers.google.com/web/tools/workbox/modules/workbox-build#generateswstring_mode)

0 commit comments

Comments
 (0)