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

package/zh/guides/advanced-features/ssg.md

@@ -5,10 +5,6 @@ sidebar_position: 4
 
 SSG（Static Site Generation）是一种基于数据与模板，在构建时渲染完整静态网页的技术解决方案。
 
-:::info 注
-SSG 是构建阶段的解决方案，因此仅对生产环境有效。通过 `dev` 命令运行时，表现效果与 SSR 相同。
-:::
-
 我们首先需要执行 `pnpm run new` 启用 SSG 功能：
 
 ```bash
@@ -16,13 +12,17 @@ SSG 是构建阶段的解决方案，因此仅对生产环境有效。通过 `de
 ? 启用可选功能 启用「SSG」功能
 ```
 
-执行命令后，在 `modern.config.ts` 中注册 SSG 插件:
+执行命令后，在 `modern.config.ts` 中注册 SSG 插件：
 
 ```ts title="modern.config.ts"
 import SSGPlugin from '@modern-js/plugin-ssg';
 // https://modernjs.dev/docs/apis/app/config
 export default defineConfig({
   ...,
+  output: {
+    ...,
+    ssg: true,
+  },
   plugins: [..., SSGPlugin()],
 });
 ```
@@ -129,45 +129,3 @@ export default defineConfig({
 :::info
 以上仅介绍了单入口的情况，更多相关内容可以查看 [API 文档](/docs/configure/app/output/ssg)。
 :::
-
-### 获取数据
-
-在 SSR 中，组件可以通过 `useLoader` 同构的获取数据。在 SSG 中，Modern.js 也提供了相同的能力。
-
-调用 `useLoader` 时，在第二个参数中设置 `{ static: true }`，可以在 SSG 阶段执行数据的请求。
-
-:::info 注
-- Modern.js 目前还不支持 SSG 与 SSR 混合渲染，敬请期待。
-- 在开发阶段，不管 `useLoader` 是否配置 `{ static: true }`，函数都会在 SSR 时获取数据。
-:::
-
-修改上述 `src/App.ts` 的代码为：
-
-```tsx title="App.ts"
-import { useRuntimeContext, useLoader } from '@modern-js/runtime';
-import { Routes, Route, BrowserRouter } from '@modern-js/runtime/router';
-import { StaticRouter } from '@modern-js/runtime/router/server';
-
-const Router = typeof window === 'undefined' ? StaticRouter : BrowserRouter;
-
-export default () => {
-  const { context } = useRuntimeContext();
-
-  const { data } = useLoader(async () => ({
-    message: Math.random(),
-  }), { static: true });
-
-  return (
-    <Router location={context.request.pathname}>
-      <Routes>
-        <Route index element={<div>index</div>} />
-        <Route path="about" element={<div>about, {data?.message}</div>} />
-      </Routes>
-    </Router>
-  );
-};
-```
-
-执行 `pnpm run dev`，重复刷新页面，可以看到 `/foo` 页面的渲染结果不断发生变化，说明数据是在请求时获取的。
-
-重新执行 `pnpm run build` 后，执行 `pnpm run serve`，重复刷新页面，发现页面渲染结果始终保持同样的内容，数据在请求时不会再次获取，说明页面在编译时已经完成渲染。

package/zh/guides/advanced-features/ssr.md

@@ -125,7 +125,7 @@ CSR 中这类问题不易被发觉，因此从 CSR 切换到 SSR 时，如果不
 
 ## 收敛服务端数据
 
-为了保持 SSR 阶段请求的数据，可以在浏览器端直接使用， Modern.js 会将渲染过程中收集的数据与状态注入到 HTML 内。但是，CSR 应用常常存在接口数据量大、组件状态未收敛的情况，这时如果直接使用 SSR，渲染得到的 HTML 体积可能会存在过大的问题。此时，SSR 不仅无法为应用带来用户体验上的提升，反而可能起到相反的作用。
+为了保持 SSR 阶段请求的数据，可以在浏览器端直接使用，Modern.js 会将渲染过程中收集的数据与状态注入到 HTML 内。但是，CSR 应用常常存在接口数据量大、组件状态未收敛的情况，这时如果直接使用 SSR，渲染得到的 HTML 体积可能会存在过大的问题。此时，SSR 不仅无法为应用带来用户体验上的提升，反而可能起到相反的作用。
 
 因此，使用 SSR 时，**开发者需要为应用做合理的瘦身**：
 

package/zh/guides/advanced-features/testing.md

@@ -15,7 +15,7 @@ Modern.js 默认继承了 [Jest](https://jestjs.io/) 的测试能力。
 
 执行上述命令后，`package.json` 中将会自动生成 `"test": "modern test"` 命令。
 
-在 `modern.config.ts` 中注册 Test 插件:
+在 `modern.config.ts` 中注册 Test 插件：
 
 ```ts title="modern.config.ts"
 import TestPlugin from '@modern-js/plugin-testing';
@@ -28,7 +28,7 @@ export default defineConfig({
 
 ## 测试文件
 
-Modern.js 默认识别的测试文件路径为： `<rootDir>/src/**/*.test.[jt]s?(x)` 和 `<rootDir>/tests/**/*.test.[jt]s?(x)`。
+Modern.js 默认识别的测试文件路径为：`<rootDir>/src/**/*.test.[jt]s?(x)` 和 `<rootDir>/tests/**/*.test.[jt]s?(x)`。
 
 如果你需要自定义 test 目录，可通过 [tools.jest](/docs/configure/app/tools/jest) 进行配置。
 

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

@@ -13,10 +13,10 @@ Modern.js 允许在 JS 和 CSS 中使用别名导入自定义目录下的模块
 ```
 
 :::info 注
-在开启可选功能时，生成器也会动态的添加内置别名，例如启用 BFF 时默认会添加 `@api` 别名：
+在开启可选功能时，生成器也会动态的添加内置别名，例如启用 BFF 时默认会添加 `@api` 别名。
 :::
 
-`src/` 目录结构如下时，从 `src/App.tsx` 文件中导入 `src/common` 目录下的模块:
+例如从 `src/App.tsx` 文件中导入 `src/common` 目录下的模块：
 
 ```bash
 .
@@ -28,14 +28,14 @@ Modern.js 允许在 JS 和 CSS 中使用别名导入自定义目录下的模块
 ├── App.tsx
 ```
 
-`src/App.tsx` 中写法如下:
+`src/App.tsx` 中写法如下：
 
 ```ts
 import utils from '@/src/common/utils';
 import '@/src/common/styles/base.css';
 ```
 
-Modern.js 也提供了自定义别名的方式，以添加 `@common` 别名为例，对于 TypeScript 项目，只需要在项目根目录 `tsconfig.json` 下配置 `compilerOptions.paths` 如下:
+Modern.js 也提供了自定义别名的方式，以添加 `@common` 别名为例，对于 TypeScript 项目，只需要在项目根目录 `tsconfig.json` 下配置 `compilerOptions.paths` 如下：
 
 ```json
 {
@@ -52,7 +52,7 @@ Modern.js 也提供了自定义别名的方式，以添加 `@common` 别名为
 }
 ```
 
-JavaScript 项目可以在 `modern.config.js` 中配置 [`source.alias`](/docs/configure/app/source/alias):
+JavaScript 项目可以在 `modern.config.js` 中配置 [`source.alias`](/docs/configure/app/source/alias)：
 
 ```typescript title="modern.config.ts"
 export default defineConfig({

package/zh/guides/basic-features/css/tailwindcss.md

@@ -32,12 +32,40 @@ import 'tailwindcss/components.css';
 import 'tailwindcss/utilities.css';
 ```
 
-然后即可在各个组件中使用 Tailwind CSS 提供的 Utility Class 了。
+然后即可在各个组件中使用 Tailwind CSS 提供的 Utility Class 了：
+
+```tsx
+const App = () => (
+  <div className="h-12 w-48">
+    <p className="text-xl font-medium text-black">hello world</p>
+  </div>
+);
+```
 
 :::info 补充信息
-根据不同需求，可以选择性的导入 Tailwind CSS 提供的 CSS 文件。由于使用 `@taiwind` 与直接导入 CSS 文件的作用等价，因此关于 Tailwind CSS 提供的 CSS 文件的用途，可以参考 [`@tailwind` 的使用](https://tailwindcss.com/docs/functions-and-directives#tailwind) 文档中注释里的内容。
+根据需求不同，你可以选择性的导入 Tailwind CSS 提供的 CSS 文件。由于使用 `@tailwind` 与直接导入 CSS 文件的作用等价，因此关于 Tailwind CSS 提供的 CSS 文件的用途，可以参考 [`@tailwind` 的使用](https://tailwindcss.com/docs/functions-and-directives#tailwind) 文档中注释里的内容。
 :::
 
+## Tailwind CSS 版本
+
+Modern.js 同时支持 Tailwind CSS v2 和 v3 版本，框架会识别项目 `package.json` 中的 `tailwindcss` 依赖版本，并启用相应的配置。默认情况下，我们会为你安装 Tailwind CSS v3 版本。
+
+如果你的项目仍在使用 Tailwind CSS v2，我们推荐你升级到 v3 以支持 JIT 等能力。关于 Tailwind CSS v2 与 v3 版本之间的差异，请参考以下文章：
+
+- [Tailwind CSS v3.0](https://tailwindcss.com/blog/tailwindcss-v3)
+- [Upgrade Guide](https://tailwindcss.com/docs/upgrade-guide)
+
+### 浏览器兼容性
+
+Tailwind CSS v2 和 v3 均不支持 IE 11 浏览器，相关背景请参考：
+
+- [Tailwind CSS v3 - Browser Support](https://tailwindcss.com/docs/browser-support)。
+- [Tailwind CSS v2 - Browser Support](https://v2.tailwindcss.com/docs/browser-support)
+
+如果你在 IE 11 浏览器上使用 Tailwind CSS，可能会出现部分样式不可用的现象，请谨慎使用。
+
+## Theme 配置
+
 当需要自定义 Tailwind CSS 的 [theme](https://tailwindcss.com/docs/theme) 配置的时候，可以在配置 [`source.designSystem`](/docs/configure/app/source/design-system) 中修改，例如，颜色主题中增加一个 `primary`：
 
 ```typescript title="modern.config.ts"
@@ -70,36 +98,4 @@ export default defineConfig({
 });
 ```
 
-## 使用 [`Twin`](https://github.com/ben-rogerson/twin.macro) 库
-
-在上一章中介绍了什么是 CSS-in-JS 以及社区常用的 CSS-in-JS 库 [styled-components](https://styled-components.com/)。这一部分将要介绍如何通过 [`Twin`](https://github.com/ben-rogerson/twin.macro) 在 CSS-in-JS 中使用 [Tailwind CSS](https://tailwindcss.com/)。使用 [`Twin`](https://github.com/ben-rogerson/twin.macro) 可以更容易在 CSS-in-JS 的代码中使用 Tailwind CSS。[`Twin`](https://github.com/ben-rogerson/twin.macro) 对于自己的描述是：
-
-> *Twin blends the magic of Tailwind with the flexibility of css-in-js*
-
-在开启「Tailwind CSS 支持」的功能后，首先需要安装 [`Twin`](https://github.com/ben-rogerson/twin.macro) 依赖:
-
-``` bash
-pnpm add twin.macro -D
-```
-
-当项目安装 `twin.macro` 依赖后，Modern.js 会检测到该依赖并对内置的 `babel-plugin-macro` 增加 `twin.macro` 相关的配置。因此在安装完依赖后，无需手动配置。下面是一个简单使用 `twin.macro` 的示例：
-
-``` js
-import tw from 'twin.macro'
-
-const Input = tw.input`border hover:border-black`
-```
-
-:::tip 提示
-如果在运行过程中出现了 `MacroError: /project/App.tsx` 错误的时候，有可能是缺少 `twin.macro` 依赖导致的。
-:::
-
-更多的使用方式可以参考 `twin.macro` 的 [文档](https://github.com/ben-rogerson/twin.macro/blob/master/docs/index.md)。
-
-`twin.macro` 默认会读取项目目录下的 `tailwindcss.config.js` 文件，或者通过 `babel-plugin-macro` 上的 [`twin.config`](https://github.com/ben-rogerson/twin.macro/blob/master/docs/options.md#options) 指定的文件路径读取 Tailwind CSS 配置。不过在 Modern.js 中不需要进行这些额外配置。
-
-当在 `modern.config.ts` 文件中通过 [`source.designSystem`](/docs/configure/app/source/design-system) 和  [`tools.tailwindcss`](/docs/configure/app/tools/tailwindcss) 对 Tailwind CSS 进行配置的时候，这些配置也会对 `twin.macro` 生效。
-> 当为项目配置 Tailwind CSS 的时候，[`source.designSystem`](/docs/configure/app/source/design-system) 和  [`tools.tailwindcss`](/docs/configure/app/tools/tailwindcss) 这两个配置的组合等价于单独配置了一个 `tailwindcss.config.js` 文件。
-> 其中[`source.designSystem`](/docs/configure/app/source/design-system)等效于 Tailwind CSS 的 [`theme`](https://v2.tailwindcss.com/docs/configuration#theme) 配置。
-
-
+> 当你为项目配置 Tailwind CSS 的时候，[source.designSystem](/docs/configure/app/source/design-system) 和 [tools.tailwindcss](/docs/configure/app/tools/tailwindcss) 这两个配置的组合等价于单独配置了一个 `tailwindcss.config.js` 文件。其中 [source.designSystem](/docs/configure/app/source/design-system) 等效于 Tailwind CSS 的 [theme](https://v2.tailwindcss.com/docs/configuration#theme) 配置。

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');