docs: complete Introduction

docs/app-structure.md

@@ -26,12 +26,12 @@ title: 目录结构
 
 这里大部分的约定和配置文件都是可选的，唯一强约定只有 pages 目录。
 
-比如一个简单的应用，目录结构可能这样的。
+比如一个简单的应用，目录结构只要这样就好。
 
 ```bash
 .
-├── pages/              
-    ├── list.js         
-    └── index.js        
+├── pages/
+    ├── list.js
+    └── index.js
 └── package.json
 ```

docs/layout.md

@@ -3,4 +3,24 @@ id: layout
 title: 添加布局
 ---
 
-添加布局。
+umi 约定 layouts/index.js 为整体布局文件。
+
+新建 layouts/index.js 文件，内容如下：
+
+```js
+export default function(props) {
+  return (
+    <div>
+      <header>Header</header>
+      {
+        props.children
+      }
+      <footer>Footer</footer>
+    </div>
+  );
+}
+```
+
+这样就为你的页面新增了一个全局的页头和页尾。
+
+<img src="https://gw.alipayobjects.com/zos/rmsportal/hcRxkhHgEzuzwlwrMCIb.png" width="450" height="414" style="margin-left:0;" />

docs/navigate-between-pages.md

@@ -3,9 +3,13 @@ id: navigate-between-pages
 title: 在页面间跳转
 ---
 
-在 umi 里，页面之间跳转有两种方式：声明式和编程式。
+## 跳转的两种方式
 
-## 通过 umi/link 做声明式跳转
+在 umi 里，页面之间跳转有两种方式：声明式和命令式。
+
+### 声明式
+
+基于 `umi/link`。
 
 ```bash
 import Link from 'umi/link';
@@ -15,7 +19,9 @@ export default () => (
 );
 ```
 
-## 通过 umi/router 做编程式跳转
+### 命令式
+
+基于 `umi/router`。
 
 ```js
 import router from 'umi/router';
@@ -25,7 +31,45 @@ function goToListPage() {
 }
 ```
 
-## 更多
+### 更多
 
 关于 umi/link 和 umi/router 的更多用法，参考 [API 文档](./api.html)。
 
+
+## 实践
+
+继续之前的例子，我们新增一个 list 页面，新建 pages/list.js，并填入：
+
+```js
+import router from 'umi/router';
+
+export default () => {
+  return (
+    <div>
+      ListPage
+      <br />
+      <button onClick={() => { router.goBack(); }}>go back</button>
+    </div>
+  );
+}
+```
+
+然后修改 pages/index.js，编辑：
+
+```js
+import Link from 'umi/link';
+
+export default () => {
+  return (
+    <div>
+      ListPage
+      <br />
+      <button onClick={() => { router.goBack(); }}>go back</button>
+    </div>
+  );
+}
+```
+
+这样就实现了两个页面之间的跳转，效果：
+
+<img src="https://gw.alipayobjects.com/zos/rmsportal/kCxjVDAjcfbzFfaGFQsy.gif" style="margin-left:0;" />

docs/theme.md

@@ -1,6 +1,32 @@
 ---
 id: theme
-title: 主题配色
+title: 定制主题
 ---
 
-主题配色。
+我们支持通过 [modifyVars](http://lesscss.org/usage/#using-less-in-the-browser-modify-variables) 的方式来覆盖变量。
+
+## 通过 theme 属性定制主题
+
+新建 .webpackrc，.webpackrc 文件用于配置 webpack，内容如下：
+
+```json
+{
+  "theme": {
+    "primary-color": "#7546c9"
+  }
+}
+``` 
+
+本地开发服务器会自动重启，
+
+<img src="https://gw.alipayobjects.com/zos/rmsportal/YMdGEpszmHZcUfcYBRWO.png" width="450" height="414" style="margin-left:0;" />
+
+然后，效果如下：
+
+<img src="https://gw.alipayobjects.com/zos/rmsportal/qGncpVZOUmhbcxbvihRW.png" width="450" height="414" style="margin-left:0;" />
+
+## 参考
+
+* https://ant.design/docs/react/customize-theme-cn
+* [antd 的默认样式变量](https://github.com/ant-design/ant-design/blob/master/components/style/themes/default.less)
+* [antd-mobile 的默认样式变量](https://github.com/ant-design/ant-design-mobile/blob/master/components/style/themes/default.less)

docs/using-antd-or-antd-mobile.md

@@ -3,18 +3,48 @@ id: using-antd-or-antd-mobile
 title: 使用 antd 或 antd-mobile
 ---
 
-umi 内置了 antd 和 antd-mobile，以及 babel-plugin-import 插件，可无需安装依赖而直接使用。
+umi 内置了 [antd](https://ant.design/) 和 [antd-mobile](https://mobile.ant.design/)，并且配置了 babel-plugin-import 插件做按需引用，所以你无需关心依赖和配置，直接用即可。
 
-## 引入组件
+先引用，
 
 ```js
 import { Button } from 'antd';
+```
+
+或者
+
+```js
+import { Button } from 'antd-mobile';
+```
+
+然后直接使用，
+
+```js
+<Button type="primary">Hi umi</Button>
+```
 
-export default function() {
-  return (
-    <div>
-      <Button type="primary">Hello umi</Button>
-    </div>
-  );
-}
+## 使用 antd 组件
+
+继续我们之前的例子，修改 pages/index.js，替换为：
+
+```js
+import Link from 'umi/link';
+import { Button } from 'antd';
+import styles from './index.css';
+import '../global.less';
+
+export default () => <div className={styles.normal}>
+  Index Page
+  <br />
+  <Link to="/list"><Button type="primary">go to /list</Button></Link>
+</div>
 ```
+
+效果：
+
+<img src="https://gw.alipayobjects.com/zos/rmsportal/RmXJNQcKLGTgHGLmZrVs.png" width="450" height="414" style="margin-left:0;" />
+
+## 参考
+
+* https://ant.design/
+* https://mobile.ant.design/

docs/write-css.md

@@ -3,30 +3,76 @@ id: write-css
 title: 写 CSS
 ---
 
-umi 的样式是通过 css modules 的方式组织的。
+写 CSS 的方案有很多选择，比如：
+
+* css modules
+* css in js
+* ...
+
+但如果是 SPA 应用，需确保多个页面之间的样式不会冲突，因为目前所有样式会被打包到一起。
+
+umi 内置支持 css modules 以及 less，项目目录下的所有 `.css` 和 `.less` 文件会被处理为 css modules，下面介绍的是 css modules 的方式。
 
 ## 为组件添加样式
 
-推荐的方式是新建一个和组件同名的 css 文件，比如组件是 index.js，我们可以新建 index.css 。
+组件样式通常和组件 JS 同名，比如组件是 index.js，我们可以新建 index.css。
 
-在 CSS 文件中定义 class，可以不考虑和其他文件的冲突问题。
+新建 `pages/index.css`，内容如下：
 
 ```css
 .normal {
   color: red;
+  margin: 20px 0;
 }
 ```
 
-然后在 index.js 里引入，并通过变量的方式声明样式。
+然后编辑 `pages/index.js`，
+
+```js
+import Link from 'umi/link';
+import styles from './index.css';
+
+export default () => <div className={styles.normal}>
+  Index Page
+  <br />
+  <Link to="/list"><button>go to /list</button></Link>
+</div>
+```
+
+## 添加全局样式
+
+有些样式我们希望全局生效，比如针对 antd 的样式覆盖，全局配置字体、行高、链接等。
+
+新增 `global.less` 为页头页尾添加样式，内容如下：
+
+```
+:global {
+  header {
+    background: #aaa;
+    font-size: 20px;
+  }
+  footer {
+    border-top: 1px solid #ccc;
+    padding-top: 8px;
+    color: #aaa;
+  }
+}
+```
+
+之所以用 less，是因为可以运用 less 的嵌套规则，少写一些 `:global` 伪类。
+
+然后在 pages/index.js 里增加对他的引用。
 
 ```diff
-+ import styles from './index.css';
-...
-- <div>
-+ <div className={styles.normal}>
++ import '../global.less';
 ```
 
-## 参考
+最终效果如下：
+
+<img src="https://gw.alipayobjects.com/zos/rmsportal/PEzsPNTSsztxKWoyApTa.png" width="450" height="414" style="margin-left:0;" />
 
-* [http://www.ruanyifeng.com/blog/2016/06/css_modules.html](http://www.ruanyifeng.com/blog/2016/06/css_modules.html)
 
+## 参考
+
+* http://www.ruanyifeng.com/blog/2016/06/css_modules.html
+* https://github.com/css-modules/css-modules

website/i18n/en.json

@@ -20,7 +20,7 @@
     "pwa": "PWA",
     "router": "路由",
     "test": "单元测试",
-    "theme": "主题配色",
+    "theme": "定制主题",
     "using-antd-or-antd-mobile": "使用 antd 或 antd-mobile",
     "write-css": "写 CSS",
     "write-sass": "Write SASS",