@modern-js/main-doc 2.0.0-beta.6 → 2.0.0-canary.1

package/zh/guides/basic-features/data-fetch.md

@@ -9,10 +9,10 @@ Modern.js 中提供了开箱即用的数据获取能力，开发者可以通过
 
 ## Data Loader(推荐)
 
-Modern.js 推荐使用约定式路由做路由的管理，通过 Modern.js 的[约定式（嵌套）路由](/docs/guides/basic-features/routes#约定式路由)，每个路由组件(`layout.ts` 或 `page.ts`)可以导出一个函数`loader`，该函数可以在组件渲染之前，为路由组件提供数据。
+Modern.js 推荐使用约定式路由做路由的管理，通过 Modern.js 的[约定式（嵌套）路由](/docs/guides/basic-features/routes#约定式路由)，每个路由组件(`layout.ts` 或 `page.ts`)可以导出一个函数`loader`，该函数可以在组件渲染之前执行，为路由组件提供数据。
 
 :::info
-Modern.js 旧版支持通过 [useLoader](#useloader旧版) 获取数据，这已经不是我们推荐的用法，除迁移过程外，不推荐两者混用。
+Modern.js v1 支持通过 [useLoader](#useloader旧版) 获取数据，这已经不是我们推荐的用法，除迁移过程外，不推荐两者混用。
 :::
 
 ### 基础示例
@@ -85,7 +85,7 @@ export default function UserPage() {
 
 
 `loader` 函数有两个入参：
-##### `Params`
+#### `Params`
 
 当路由文件通过 `[]` 时，会作为[动态路由](/docs/guides/basic-features/routes#动态路由)，动态路由片段会作为参数传入 loader 函数：
 
@@ -102,9 +102,9 @@ export const loader = async({ params }: LoaderArgs) => {
 
 当访问 `/user/123` 时，`loader` 函数的参数为 `{ params: { id: '123' } }`。
 
-##### `request`
+#### `request`
 
-request 是一个 [Fetch Request](https://developer.mozilla.org/en-US/docs/Web/API/Request) 实例。
+`request` 是一个 [Fetch Request](https://developer.mozilla.org/en-US/docs/Web/API/Request) 实例。
 
 一个常见的使用场景是通过 `request` 获取查询参数：
 ```tsx
@@ -181,7 +181,7 @@ const ErrorBoundary = () => {
 export default ErrorBoundary;
 ```
 
-### 获取上层组件数据
+### 获取上层组件的数据
 
 很多场景下，子组件需要获取到祖先组件 loader 中的数据，你可以通过 `useRouteLoaderData` 方便地获取到祖先组件的数据：
 ```tsx
@@ -239,6 +239,7 @@ export default function UserLayout() {
 .
 └── routes
     ├── layout.tsx
+    ├── loading.tsx
     └── user
         ├── layout.tsx
         └── page.ts

package/zh/guides/basic-features/env-vars.md

@@ -103,7 +103,7 @@ if (process.env.NODE_ENV === 'development') {
 }
 ```
 
-执行 `pnpm run dev` 命令之后可以看到如下构建产物:
+执行 `pnpm run dev` 命令之后可以看到如下构建产物：
 
 ```js
 if (true) {
@@ -119,7 +119,7 @@ if (true) {
 
 ### 任意命名
 
-如果需要在代码中使用任意名称的环境变量，可以在 [`source.globalVars`](/docs/configure/app/source/global-vars) 配置指定, 例如:
+如果需要在代码中使用任意名称的环境变量，可以在 [`source.globalVars`](/docs/configure/app/source/global-vars) 配置指定, 例如：
 
 ```typescript title="modern.config.ts"
 export default defineConfig({

package/zh/guides/basic-features/html.md

@@ -3,86 +3,60 @@ title: HTML 模板
 sidebar_position: 9
 ---
 
-Modern.js 提供了 `jsx` 和 `ejs` 两种方式用于自定义 html 模板。推荐使用 `jsx` 语法，让写模板跟写组件一样丝滑。
+Modern.js 提供了 **JSX 语法**和**HTML(Ejs) 语法**两种方式用于自定义 HTML 模板。
 
-## jsx
+## JSX 语法
 
-### 使用说明
+Modern.js 约定，在 `src/` 目录下，或在入口目录下，可以创建 `Document.[jt]sx` 并默认导出组件。该组件的渲染结果可以作为入口的 HTML 模板。
 
-#### 引入
-```tsx
-import {
-  Html,
-  Root,
-  Head,
-  DocumentContext,
-  Body,
-} from '@modern-js/runtime/document';
+例如以下目录结构：
+
+```bash
+.
+├── src
+│   ├── Document.tsx
+│   ├── entry-a
+│   │   ├── Document.tsx
+│   │   └── routes
+│   ├── entry-b
+│   │   └── routes
+│   └── modern-app-env.d.ts
 ```
 
-#### 导出
-```tsx
-export default Document() {}
+`entry-a` 会优先使用当前入口下的 `Docoument.[jt]sx` 文件。如果当前入口没有 `Document.[jt]sx` 文件，例如 `entry-b`，则会查找根目录下的 `Document.[jt]sx` 文件。
 
-```
+如果还没有，则会兜底到传统模板的逻辑。
 
-#### 文件位置
+### HTML 组件
 
-Document 文件，默认在应用根目录下:
+Modern.js 提供了一些列渲染页面的组件，用来帮助开发者生成模板，可以从 `@modern-js/runtime/document` 中导出这些组件：
 
-```bash
-.
-├── src
-│   ├── modern-app-env.d.ts
-│   ├── myapp
-│   │   └── routes
-│   │       ├── index.css
-│   │       ├── layout.tsx
-│   │       ├── Document.tsx
-│   │       └── page.tsx
-│   ├── new-entry
-│   │   └── routes
-│   │       ├── index.css
-│   │       ├── layout.tsx
-│   │       ├── Document.tsx
-│   │       └── page.tsx
-│   └── Document.tsx
-├── modern.config.ts
-├── package.json
-├── pnpm-lock.yaml
-├── README.md
-└── tsconfig.json
+```tsx
+import { Html, Body, Root, Head, Scripts } from '@modern-js/runtime/document';
 ```
 
-多 entry 场景构建时，优先 entry 的根目录下的 Docoument.tsx 文件。如果当前 entry 没有 Document.tsx 文件，则会查找根目录下的 Document.tsx 文件。
-如果还没有，则会 fallback 到 `html 模板` 的逻辑。
-
-#### 子组件
+这些组件分别渲染：
 
-Document 模板共提供了 `Html`、`Root` `Head` `Body` 渲染页面的组件，以及 `DocumentContext` 等提供
-分别渲染：
-- `Html`: 提供 html 原生 dom。并计算出 `DocumentStructrueContext` 的值，将 `Html` 的结构传递给子组件，判断其它子组件是否默认渲染。
+- `Html`：提供原生 HTML Element 的能力，并能默认渲染开发者未添加的必须的组件。`<Head>` 和 `<Body>` 是必须要存在的，其它组件可以按需选择合适的组件进行组装。
 
-- `Body`: 渲染生成 `body` 节点。其子元素包含 `Root` 组件。支持其它元素同时作为子元素，例如页脚。
+- `Body`：提供原生 Body Element 的能力，内部需要包含 `<Root>` 组件，也支持其它元素同时作为子元素，例如添加页脚。
 
-- `Root`: 渲染的根节点 `<div id='root'></div>`。默认根节点的 `id = 'root'`。可以设置 props.rootId 来更改 id 属性。子元素，也会被渲染进 DOM 里，随着 react 渲染完成，会替换掉，一般用来实现全局 loading。
+- `Root`：渲染的根节点 `<div id='root'></div>`。默认根节点的 `id = 'root'`。可以设置 `props.rootId` 来更改 id 属性。可以添加子组件，也会被渲染到 HTML 模板中，当 React 渲染完成后会被覆盖，一般用来实现全局 Loading。
 
-- `Head`: 渲染生成 `head` 节点。会自动填充 meta 元素，以及 `Scripts` 组件。
+- `Head`：提供原生 Head Element 的能力，并会自动填充 `<meta>`，以及 `<Scripts>` 组件。
 
-- `Scripts`: 将构建产生的 script 标签渲染到该位置。用于调整构建产物的位置，默认放在 `Head` 组件里，用于
+- `Scripts`：构建产生的 script 内容，可用于调整构建产物的位置，默认放在 `<Head>` 组件中。
 
-`Html` 组件中，`Head` 和 `Body` 是必须要存在的，其它组件可以按需选择合适的组件进行组装。
+### 模板参数
 
-#### 模板参数
+因为是 JSX 形式，`Document.[jt]sx` 里，可以比较自由的在组件内使用各种变量去赋值给各种自定义组件。
 
-因为是 JSX 形式，Document.tsx 里，可以比较自由的在组件内使用各种变量去赋值给各种自定义组件。
-但同时 Document 自身也提供了 `DocumentContext` context 来提供一些配置、环境参数，方便直接获取。主要以下参数：
+Modern.js 也提供了 `DocumentContext` 来提供一些配置、环境参数，方便直接获取。主要以下参数：
 
 - `processEnv`：提供构建时的 `process.env`
-- `config`: Modern.js 项目的配置。目前只暴露出 output 相关的配置
-- `entryName`: 当前的 entry 名。
-- `templateParams`: html 模板的参数，由 builder 提供。对应 [html-webpack-plugin](https://github.com/jantimon/html-webpack-plugin) 的 `templateParameters` 配置项最终获取到的结果。不建议使用!
-
+- `config`：Modern.js 项目的配置。目前只暴露出 output 相关的配置
+- `entryName`：当前的入口名
+- `templateParams`：HTML 模板的参数（为了兼容传统模板，不推荐使用）
 
 ### 示例
 
@@ -92,12 +66,11 @@ import {
   Html,
   Root,
   Head,
-  DocumentContext,
   Body,
+  Scripts,
+  DocumentContext
 } from '@modern-js/runtime/document';
-import Script from '@/components/Script';
 
-// 默认导出
 export default function Document(): React.ReactElement {
   // DocumentContext 提供一些构建时的参数
   const {
@@ -109,34 +82,23 @@ export default function Document(): React.ReactElement {
   return (
     <Html>
       <Head>
-        // Head 组件支持自定义子元素。包括 link, script
         <link href="https://modernjs.dev">Modern.js</link>
-        <script
-          // inline script 的脚本需要如下处理
-          dangerouslySetInnerHTML={{
-            __html: `window.b = 22`,
-          }}
-        ></script>
       </Head>
       <Body>
-        // rootId 可以更改根元素的 id
         <Root rootId="root">
-          // Root 支持子元素
           <h1 style={{ color: 'red' }}>以下为构建时传过来的参数：</h1>
           <h2> entryName：{entryName}</h2>
           <h2> title：{htmlConfig.title}</h2>
           <h2> rootId: {templateParams.mountId}</h2>
         </Root>
-        // Body 组件支持 Root 以外增加不同的组件，共同组成页面
         <h1>bottom</h1>
       </Body>
     </Html>
   );
 }
-
 ```
 
-以上文件，将会生成以下 html 文件：
+以上 JSX 组件，将会生成以下 HTML 模板：
 
 ```html
 <!DOCTYPE html>
@@ -162,7 +124,6 @@ export default function Document(): React.ReactElement {
         src="/static/js/packages_runtime_plugin-router-legacy_dist_js_treeshaking_runtime_index_js-packages_runtime_p-28f4c9.js"></script>
     <script defer src="/static/js/sub.js"></script>
     <link href="https://www.baidu.com" />
-    <script>window.b = 22</script>
 </head>
 
 <body>
@@ -177,26 +138,23 @@ export default function Document(): React.ReactElement {
     <!--<?- chunksMap.js ?>-->
     <!--<?- SSRDataScript ?>-->
 </body>
-
 </html>
 ```
 
-## ejs
+## Html 语法
 
-Modern.js 同时支持了使用 `ejs` 语法编写模板，当项目中，没有编写 `Document.[j|t]sx` 文件时，将自动回退至  `ejs` HTML 模板。
+Modern.js 也支持 HTML 语法。默认情况下，Modern.js 的应用工程中会内置一份 HTML 模板，用于生成 HTML 代码。
 
-默认情况下，Modern.js 的应用工程中会内置一份 HTML 模板，用于生成 HTML 代码。
+基于 HTML 语法的模板，Modern.js 提供了 **自定义 HTML 片段**和**完全自定义 HTML 模板**两种方式来自定义模板。
 
-Modern.js 提供了**「自定义 HTML 片段」**和**「完全自定义 HTML 模板」**两种方式来自定义模板。
-
-## 自定义 HTML 片段
+### 自定义 HTML 片段
 
 在应用根目录下，创建 `config/html/` 目录，该目录下支持创建四种 HTML 片段。
 
-- `top.(html|ejs)`
-- `head.(html|ejs)`
-- `body.(html|ejs)`
-- `bottom.(html|ejs)`
+- `top.html`
+- `head.html`
+- `body.html`
+- `bottom.html`
 
 **这些片段将按位置注入到默认的 HTML 模板中。**
 
@@ -226,54 +184,19 @@ Modern.js 提供了**「自定义 HTML 片段」**和**「完全自定义 HTML
 </html>
 ```
 
-代码片段支持 [EJS](https://ejs.co/) 语法（默认使用 [Lodash template](https://lodash.com/docs/4.17.15#template) 语法）。
+代码片段支持使用 [Lodash template](https://lodash.com/docs/4.17.15#template) 语法。
 
-例如，新增 `head.ejs` 文件，并添加一个自定义标签：
-
-```html title="config/html/head.ejs"
-<% if (process.env.NODE_ENV === 'production') { %>
-  <meta name='env' content="production">
-<% } else { %>
-  <meta name='env' content="development">
-<% } %>
-```
-
-或在 `body.html` 里插入一个外链脚本：
+例如在 `body.html` 里插入一个外链脚本：
 
 ```html title="config/html/body.html"
 <script src="//example.com/assets/a.js"></script>
 ```
 
-:::info 自定义 HTML 片段不支持修改 title 标签
-自定义 HTML 片段的实现方式是将片段与框架内置的模板进行合并，由于框架的默认模板中已经存在 title 标签，因此自定义 HTML 模板中的 title 标签无法生效，请通过 [html.title](/docs/configure/app/html/title) 来修改页面标题。
+:::info
+自定义 HTML 片段的实现方式是将片段与框架内置的模板进行合并，由于框架的默认模板中已经存在 `<title>`，因此自定义 HTML 模板中的 title 标签无法生效，请通过 [html.title](/docs/configure/app/html/title) 来修改页面标题。
 :::
 
-### 模板参数
-
-模板中使用的参数可以通过 [html.templateParameters](/docs/configure/app/html/template-parameters) 配置项来定义。
-
-
-### 按入口设置
-
-`config/html/` 目录中的 HTML 片段对应用中的所有入口都生效。如果希望按入口自定义 HTML 片段，可以在 `config/html/` 目录下新建一个以**入口名**命名的目录，然后在这个目录中自定义 HTML 片段。
-
-例如，如下设置的 HTML 片段仅对入口 `entry1` 生效：
-
-```html
-.
-├── config/
-│   └── html/
-│       └── entry1
-│           ├── head.html
-│           └── body.html
-└── src/
-    ├── entry1/
-    │   └── App.jsx
-    └── entry2/
-        └── App.jsx
-```
-
-## 完全自定义 HTML 模板
+### 完全自定义 HTML 模板
 
 某些情况下，HTML 片段无法满足自定义需求，Modern.js 提供了完全自定义方式。
 
@@ -281,30 +204,32 @@ Modern.js 提供了**「自定义 HTML 片段」**和**「完全自定义 HTML
 通常不建议直接覆盖默认的 HTML 模板，可能会失去一部分功能选项。即使需要替换，建议以内置模板为基础，按需修改。
 :::
 
-
-### 配置方式
-
-在 `config/html/` 目录下，创建 `index.(html|ejs)` 文件。
-
-该文件将替代默认的 HTML 模板。
+在 `config/html/` 目录下，创建 `index.html` 文件,该文件将替代默认的 HTML 模板。
 
 :::info 注
 内部默认 HTML 模板可以在 `node_modules/.modern-js/${entryName}/index.html` 中查看。
 :::
 
-如果仅需要为单一入口设置 HTML 模板，需要将 `index.(html|ejs)` 文件，放置到 `config/html/` 目录下以**入口名**命名的目录中。
+### 模板参数
 
-例如，如下设置的 HTML 模板 `index.html` 仅对入口 `entry1` 生效：
+模板中使用的参数可以通过 [html.templateParameters](/docs/configure/app/html/template-parameters) 配置项来定义。
+
+### 按入口设置
+
+`config/html/` 目录中的 HTML 片段对应用中的所有入口都生效。如果希望按入口自定义 HTML 片段，可以在 `config/html/` 目录下新建一个以**入口名**命名的目录，然后在这个目录中自定义 HTML 片段。
+
+例如，如下设置的 HTML 片段仅对入口 `entry1` 生效：
 
 ```html
 .
 ├── config/
 │   └── html/
 │       └── entry1
-│           └── index.html
+│           ├── head.html
+│           └── body.html
 └── src/
     ├── entry1/
-    │   └── App.jsx
+    │   └── routes
     └── entry2/
-        └── App.jsx
+        └── routes
 ```

package/zh/guides/basic-features/mock.md

@@ -7,26 +7,25 @@ Modern.js 提供了快速生成 Mock 数据的功能，能够让前端独立自
 
 ## Mock 文件
 
-约定当 `config/mock` 目录下存在 `index.[jt]s` 时，会自动开启 Mock 功能，如下:
+约定当 `config/mock` 目录下存在 `index.[jt]s` 时，会自动开启 Mock 功能，如下：
 
 ```bash
 .
 ├── config
 │   └── mock
-│       ├── a.json
-│       └── index.js
+│       └── index.ts
 ├── src
-│   └── App.jsx
-└── modern.config.js
+│   └── App.tsx
+└── modern.config.ts
 ```
 
-## Mock 文件编写
+## 编写 Mock 文件
 
-`./config/mock/index.js` 文件只需要导出一个包含所有 Mock API 的对象，对象的属性由请求配置 `method` 和 `url` 组成，对应的属性值可以为 `Object`、`Array`、`Function`:
+`config/mock/index.ts` 文件只需要导出一个包含所有 Mock API 的对象，对象的属性由请求配置 `method` 和 `url` 组成，对应的属性值可以为 `Object`、`Array`、`Function`：
 
 ```js
 module.exports = {
-  /* 属性为具体的 method 和 请求 url，值为 object 或 array作为请求的结果 */
+  /* 属性为具体的 method 和 请求 url，值为 object 或 array 作为请求的结果 */
   'GET /api/getInfo': { data: [1, 2, 3, 4] },
 
   /* method 默认为 GET */
@@ -44,7 +43,7 @@ module.exports = {
 
 ## 返回随机数据
 
-可以在 `./config/mock/index.js` 中自主引入 [Mock.js](https://github.com/nuysoft/Mock/wiki/Getting-Started) 等库生成随机数据，例如：
+可以在 `config/mock/index.js` 中自主引入 [Mock.js](https://github.com/nuysoft/Mock/wiki/Getting-Started) 等库生成随机数据，例如：
 
 ```js
 const Mock = require('mockjs');

package/zh/guides/basic-features/proxy.md

@@ -27,7 +27,7 @@ export default defineConfig({
 请求 `http://localhost:8080/go/api` 时，会从 [http://www.example.com/](http://www.example.com/) 返回响应内容。
 
 :::info 补充信息
-配置格式可参考:【[http-proxy-middleware](https://github.com/chimurai/http-proxy-middleware)】。
+配置格式可参考：[http-proxy-middleware](https://github.com/chimurai/http-proxy-middleware)。
 :::
 
 ## 全局代理
@@ -38,7 +38,7 @@ import GlobalProxy from '@site-docs/components/global-proxy.md'
 
 ## BFF 代理
 
-通过配置 [`bff.proxy`](/docs/configure/app/bff/proxy) 可以代理 BFF API 请求到指定的服务上，和[开发环境代理](/docs/configure/app/dev/proxy)不同的是，它同样可以用在生产环境：
+通过配置 [`bff.proxy`](/docs/configure/app/bff/proxy) 可以代理 BFF API 请求到指定的服务上，上述两种代理不同，它同样可以用在生产环境：
 
 ```typescript title="modern.config.ts"
 export default defineConfig({

package/zh/guides/basic-features/routes.md

@@ -13,7 +13,7 @@ Modern.js 内置了对 [React Router 6](https://reactrouter.com/en/main) 的**
 
 以 `routes/` 为约定的入口，Modern.js 会自动基于文件系统，生成对应的路由结构。
 
-Modern.js 支持了业界流行的约定路由模式：**嵌套路由**，使用嵌套路由时，页面的路由 与 UI 结构是相呼应的，我们将会详细介绍这种路由模式。
+Modern.js 支持了业界流行的约定式路由模式：**嵌套路由**，使用嵌套路由时，页面的路由 与 UI 结构是相呼应的，我们将会详细介绍这种路由模式。
 
 ```
 /user/johnny/profile                  /user/johnny/posts
@@ -26,11 +26,30 @@ Modern.js 支持了业界流行的约定路由模式：**嵌套路由**，使用
 +------------------+                  +-----------------+
 ```
 
+
 ### 路由文件约定
 
-`routes/` 目录下有两个文件约定 `layout.[jt]sx` 和 `page.[jt]sx`（后面简写为 `.tsx`）。这两个文件决定了应用的布局层次，其中 `layout.tsx` 中作为布局组件，`page.tsx` 作为内容组件，是整个路由表的叶子节点。
+在`routes/` 目录下，目录名会作为路由 url 的映射，Modern.js 有两个文件约定 `layout.[jt]sx` 和 `page.[jt]sx`（后面简写为 `.tsx`）。这两个文件决定了应用的布局层次，其中 `layout.tsx` 中作为布局组件，`page.tsx` 作为内容组件，是整条路由的叶子节点（一条路由有且仅有一个叶子节点，且必须以叶子节点结尾）。
+
+例如以下目录结构：
+
+```bash
+.
+└── routes
+    ├── page.tsx
+    └── user
+        └── page.tsx
+```
+
+会产出下面两条路由：
+- `/`
+- `/user`
 
-例如，这里 `routes/layout.tsx` 会作为 `/` 路由下所有组件的布局组件使用：
+当添加 `layout.tsx` 后， 假设有以下目录
+
+:::info
+这里 `routes/layout.tsx` 会作为 `/` 路由下所有组件的布局组件使用， `routes/user/layout.tsx` 会作为 `/user` 路由下所有路由组件的布局组件使用。
+:::
 
 ```bash
 .
@@ -64,6 +83,18 @@ Modern.js 支持了业界流行的约定路由模式：**嵌套路由**，使用
 
 `<Layout>` 组件是指 `routes/` 目录下所有 `layout.tsx` 文件，它们表示对应路由片段的布局，使用 `<Outlet>` 表示子组件。
 
+```tsx title=routes/layout.tsx
+import { Link, Outlet, useLoaderData } from '@modern-js/runtime/router';
+
+export default () => {
+  return (
+    <>
+      <Outlet></Outlet>
+    </>
+  )
+}
+```
+
 :::note
 `<Outlet>` 是 React Router 6 中新的 API，详情可以查看 [Outlet](https://reactrouter.com/en/main/components/outlet#outlet).
 :::
@@ -130,6 +161,8 @@ Modern.js 支持了业界流行的约定路由模式：**嵌套路由**，使用
 
 在组件中，可以通过 [useParams](/docs/apis/app/runtime/router/#useparams) 获取对应命名的参数。
 
+在 loader 中，params 会作为 [loader](/docs/guides/basic-features/data-fetch#loader-函数) 的入参，通过 `params.xxx` 可以获取。
+
 ### 无路径布局
 
 当目录名以 __ 开头时，对应的目录名不会转换为实际的路由路径，例如以下文件目录：
@@ -217,6 +250,7 @@ Modern.js 会生成 `/login` 和 `/sign` 两条路由，`__auth/layout.tsx` 组
 ```
 :::info
 当目录的 layout 组件不存在时，该目录下的 loading 组件也不会生效。
+Modern.js 建议必须有根 layout 和根 loading。
 :::
 
 当路由从 `/` 跳转到 `/blog` 时，如果 `blog/page` 组件的 JS Chunk 还未加载，则会先展示 `loading.tsx` 中导出的组件 UI。

package/zh/guides/get-started/quick-start.md

@@ -120,8 +120,7 @@ Starting the modern server...
 info    App running at:
 
   > Local:    http://localhost:8080/
-  > Network:  http://10.94.58.87:8080/
-  > Network:  http://10.254.68.105:8080/
+  > Network:  http://192.168.0.1:8080/
 ```
 
 在浏览器中打开 `http://localhost:8000/`，内容应该和 `pnpm run dev` 时一致。

package/zh/guides/topic-detail/framework-plugin/implement.md

@@ -30,11 +30,23 @@ const MyPlugin = {
 };
 ```
 
-另外，在插件中，允许配置与其他插件的执行顺序，详情可以参考[插件关系](/docs/guides/topic-detail/framework-plugin/relationship)。
+另外，在插件中，允许配置与其他插件的执行顺序。详情可以参考[插件关系](/docs/guides/topic-detail/framework-plugin/relationship)。
 
 ### 插件类型
 
-使用 TypeScript 时，可以引入内置的 `CliPlugin` 类型，为插件提供正确的类型推导：
+Modern-js 支持多种工程开发，如应用工程(app-tools), 模块工程(module-tools)等。
+
+为了兼顾不同工程开发的差异和通性，Modern-js 将插件如下图进行组织:
+
+![plugin-relationship](https://lf3-static.bytednsdoc.com/obj/eden-cn/eeeh7uhbepxlpe/modern-website/plugin-relationship.jpg)
+
+从图可以看出，Modern-js 将插件大致分为两类:
+
+1. 通用插件: 插件只会包含一些基础的 Hooks
+
+2. 工程插件: 不同的工程开发会在通用插件的基础上扩展出自己的 Hooks, Config 等类型。
+
+使用 TypeScript 时，可以引入内置的 `CliPlugin` 等类型，为插件提供正确的类型推导。
 
 ```ts
 import type { CliPlugin } from '@modern-js/core';
@@ -54,19 +66,55 @@ const MyPlugin: CliPlugin = {
 };
 ```
 
-Modern.js 导出的 `Plugin` 类型支持泛型扩展。
+上述代码为通用插件，只包含一些基础的 Hooks。 Modern.js 支持通过泛型对插件的定义进行扩展：
+
+```ts
+import type { CliPlugin, AppTools } from '@modern-js/app-tools';
 
-在 Modern.js 中，任意插件可以注册自己的 Hook，如果想拥有其他插件注册的 Hook 的类型，可以添加泛型：
+const MyPlugin: CliPlugin<AppTools> = {
+  name: 'my-plugin',
+
+  setup() {
+    const foo = '1';
+
+    return {
+      afterBuild: () => {
+        // 在构建完成后执行逻辑
+      },
+    };
+  },
+};
+```
+
+如果仔细观察 `AppTools` 这个类型，可以发现 `AppTools` 由 3 种类型构成.
+
+```ts
+type AppTools = {
+  hooks: AppToolsHooks;
+  userConfig: AppToolsUserConfig;
+  normalizedConfig: AppToolsNormalizedConfig;
+};
+```
+
+当编写插件时，插件通过泛型扩展在不同的基础上扩展自己的 Hooks 等类型:
 
 ```ts
+// 通用插件上扩展
 import type { CliPlugin } from '@modern-js/core';
 import type { MyPluginHook } from 'xxx';
 
-const MyPlugin: CliPlugin<MyPluginHook> = {};
+const MyPlugin: CliPlugin<{ hooks: MyPluginHook }> = {};
 ```
 
-详细说明，请参考 [扩展 Hook](/docs/guides/topic-detail/framework-plugin/extend)。
+```ts
+// 在 @modern-js/app-tools 基础上扩展
+import type { CliPlugin, AppTools } from '@modern-js/app-tools';
+import type { MyPluginHook } from 'xxx';
+
+const MyPlugin: CliPlugin<AppTools & { hooks: MyPluginHook }> = {};
+```
 
+详细说明，请参考 [扩展 Hook](/docs/guides/topic-detail/framework-plugin/extend)。
 
 ### 插件配置项
 

package/zh/guides/topic-detail/micro-frontend/c02-development.md

@@ -179,7 +179,7 @@ export default () => <div>Table Page</div>;
 
 访问主应用地址 `http://localhost:8080`，效果如下：
 
-![demo](https://tosv.byted.org/obj/eden-internal/ozpmyhn_lm_hymuPild/ljhwZthlaukjlkulzlp/modernjs/micro-demo.gif)
+![demo](https://lf3-static.bytednsdoc.com/obj/eden-cn/zq-uylkvT/ljhwZthlaukjlkulzlp/micro-demo.gif)
 
 在完成了微前端整体开发流程的体验后，你可以进一步了解如何 [开发主应用](./c03-main-app.md)