@modern-js/main-doc 0.0.0-nightly-20240828170710 → 0.0.0-nightly-20240830170740

package/docs/en/guides/concept/entries.mdx

@@ -116,6 +116,8 @@ For more information, please refer to [Conventional Routing](/guides/basic-featu
 
 #### Self-controlled Routing
 
+## Manual Routing
+
 If there is an `App.[jt]sx?` file within the entry, we refer to this entry as a self-controlled route. For example:
 
 ```bash
@@ -124,7 +126,9 @@ If there is an `App.[jt]sx?` file within the entry, we refer to this entry as a
 │   └── App.tsx
 ```
 
-In this file, you can define client-side routes or  not to set any client-side routes.
+For entry points defined as `src/App.tsx`, Modern.js does not perform any additional routing operations. Developers can use the [React Router 6](https://reactrouter.com/en/main) API for development, define client-side routes or not to set any client-side routes.
+
+for example, define client-side routes in application:
 
 ```tsx
 import { BrowserRouter, Route, Routes } from '@modern-js/runtime/router';
@@ -141,7 +145,10 @@ export default () => {
 };
 ```
 
-For more information, please refer to [Self-controlled Routing](/guides/basic-features/routes.html#self-controlled-routing).
+:::note
+We recommend that developers use conventional routing. Modern.js provides a series of optimizations in resource loading and rendering for conventional routing by default and offers built-in SSR capabilities. When using manual routing, these capabilities need to be encapsulated by developers themselves.
+:::
+
 
 #### Custom Entry
 

package/docs/zh/apis/app/runtime/core/use-loader.mdx

@@ -52,7 +52,7 @@ function useLoader(loaderFn: LoaderFn, options: Options): ReturnData;
   - `initialData`：首次执行前的初始数据，对应返回值中的 `data` 字段。
   - `skip`：当值为 `true` 时，函数不执行。
   - `params`：当 `params` 序列化结果发生改变时，函数会重新执行。同时，`params` 也会作为函数的第二个参数被传入。
-  - `static`：当值为 `true` 时，`useLoader` 用于 [SSG](/guides/advanced-features/ssg) 编译阶段数据的获取。
+  - `static`：当值为 `true` 时，`useLoader` 用于 [SSG](/guides/basic-features/render/ssg) 编译阶段数据的获取。
 
 ### 返回值
 

package/docs/zh/components/ssr-monitor.mdx

@@ -0,0 +1,3 @@
+:::note
+敬请期待
+:::

package/docs/zh/configure/app/output/ssg.mdx

@@ -4,44 +4,22 @@ title: ssg
 
 # output.ssg
 
-- **类型：** `boolean` | `object` | `function`
+- **类型：** `boolean` | `object`
 - **默认值：** `undefined`
 
-开启**自控式路由**或**约定式路由** SSG 功能的配置。
+开启应用 SSG 功能的配置
 
-:::info 开启 SSG 功能
-此配置需要在开启 SSG 功能情况下才会生效。请阅读 [静态站点生成](/guides/advanced-features/ssg) 文档了解如何开启 SSG 功能。
+:::tip 开启 SSG 功能
+此配置需要在开启 SSG 功能情况下才会生效。请阅读 [静态站点生成](/guides/basic-features/render/ssg) 文档了解如何开启 SSG 功能及使用场景。
 :::
 
-:::info 客户端路由
-相关内容可以查看[路由方案](/guides/basic-features/routes)。
-
+:::info 前置阅读
+SSG 功能使用与路由关联性较大，建议使用前先了解[路由方案](/guides/basic-features/routes)。
 :::
 
-## 示例
-
-### 单入口
-
-当该配置设置为 `true` 时，将会默认开启所有入口的 SSG 功能。
-
-对**自控式路由**而言，将会渲染入口的根路由。对**约定式路由**而言，将会渲染入口中每一条路由。
-
-例如 `src/` 目录下有以下满足**约定式路由**的文件结构：
-
-```bash
-.
-├── src
-│   └── routes
-│       ├── layout.tsx
-│       ├── page.tsx
-│       └── user
-│           ├── layout.tsx
-│           ├── page.tsx
-│           └── profile
-│               └── page.tsx
-```
+## Boolean 类型
 
-在 `modern.config.js` 中做以下设置：
+当该配置设置为 `true` 时，将会默认开启所有入口的 SSG 功能。对**自控式路由**而言，将会渲染入口的根路由。对**约定式路由**而言，将会渲染入口中每一条路由。
 
 ```js
 export default defineConfig({
@@ -51,39 +29,20 @@ export default defineConfig({
 });
 ```
 
-执行 `pnpm build` 构建应用后。`dist/` 目录将会生成三张 HTML 分别对应三条路由（不开启 SSG 时只有一张 HTML），并且所有 HTML 都已经渲染。
-
-而例如下面的**自控式路由**：
-
-import SelfRouteExample from "@site-docs/components/self-route-example";
-
-<SelfRouteExample />
-
-同样使用上面的配置，在执行 `pnpm run build` 后，只有入口路由 `/` 会生成渲染后的 HTML。
-
-### 多入口
-
 `output.ssg` 也可以按照入口配置，配置生效的规则同样由入口路由方式决定。
 
-例如以下目录结构：
+例如以下目录结构，分别存在约定式路由入口 `entryA` 和自控式路由入口 `entryB`：
 
 ```bash
-。
-├── src
-│   ├── entryA
-│   │   └── routes
-│   │       ├── layout.tsx
-│   │       ├── page.tsx
-│   │       └── user
-│   │           ├── layout.tsx
-│   │           ├── page.tsx
-│   │           └── profile
-│   │               └── page.tsx
-│   └── entryB
-│       └── App.tsx
+.
+└── src
+    ├── entryA
+    │   └── routes
+    └── entryB
+        └── App.tsx
 ```
 
-默认情况下，所有约定式路由的入口，在设置 `output.ssg` 配置为 `true` 后都会在构建阶段渲染。可以配置 `false` 来取消指定入口的的默认行为，例如取消上述 entryA 入口在构建时的渲染：
+你可以指定 `entryA` 和 `entryB` 的不同 SSG 配置：
 
 ```js
 export default defineConfig({
@@ -96,107 +55,58 @@ export default defineConfig({
 });
 ```
 
-### 配置路由
-
-上述内容中提到，**自控式路由**默认只会开启入口路由的 SSG 配置。
-
-可以在 `output.ssg` 中设置具体的路由，告知 Modern.js 开启这些客户端路由的 SSG 功能。例如上述 `src/App.tsx` 的文件内容为：
-
-
-<SelfRouteExample />
-
-在 `modern.config.js` 中这样设置后，`/about` 路由也会开启 SSG 功能：
-
-```js
-export default defineConfig({
-  output: {
-    ssg: {
-      routes: ['/', '/about'],
-    },
-  },
-});
-```
-
-Modern.js 将会自动根据入口拼接完整的 URL 并交给 SSG 插件完成渲染。
-
-也可以为具体入口或路由配置请求头，例如：
-
-```js
-export default defineConfig({
-  output: {
-    ssg: {
-      headers: {},
-      routes: [
-        '/',
-        {
-          url: '/about',
-          headers: {},
-        },
-      ],
-    },
-  },
-});
-```
-
 :::info
-路由中设置的 `headers` 会覆盖入口中设置的 `headers`。
-
+更多关于**约定式路由**和**自控式路由**在开启 SSG 后的默认行为，请阅读 [静态站点生成](/guides/basic-features/render/ssg) 。
 :::
 
-### 阻止默认行为
+## Object 类型
 
-默认情况下，**约定式路由**的路由会全部开启 SSG。Modern.js 提供了另一个字段，用来阻止默认的 SSG 行为。
+当值类型为 `Object` 时，可以配置如下属性。
 
-例如以下目录结构，`/`、`/user`、`/user/profle` 三条路由都开启 SSG：
+### 配置类型
 
-```bash
-.
-├── src
-│   └── routes
-│       ├── layout.tsx
-│       ├── page.tsx
-│       └── user
-│           ├── layout.tsx
-│           ├── page.tsx
-│           └── profile
-│               └── page.tsx
-```
-
-可以这样设置，禁用某一条客户端路由的默认行为：
+```ts
+type SSGRouteOptions = string | {
+  url: string;
+  params?: Record<string, any>[];
+  headers?: Record<string, any>;
+};
 
-```js
-export default defineConfig({
-  output: {
-    ssg: {
-      preventDefault: ['/user'],
-    },
-  },
-});
+type SSGOptions = {
+  preventDefault?: string[];
+  headers?: Record<string, any>;
+  routes?: SSGRouteOptions[];
+};
 ```
 
-### 添加动态路由参数
+### 示例
 
-部分路由可能是动态的，例如自控式路由中的 `/user/:id` 或是约定式路由中 `user/[id]/page.tsx` 文件生成的路由。
+下面的示例配置中，SSG 会渲染 `/`、`/about` 和 `/user/:id` 三条路由对应的页面。
 
-可以在 `output.ssg` 中配置具体的参数，渲染指定参数的路由，例如：
+对于 `/user/:id` 路由，`cookies` 添加到请求头中，同时会将 `params` 中的 `id` 替换为 `modernjs`。
 
-```js
+```ts title="modern.config.ts"
 export default defineConfig({
   output: {
     ssg: {
       routes: [
+        '/', 
+        '/about',         
         {
           url: '/user/:id',
-          params: [
-            {
-              id: 'modernjs',
-            },
-          ],
-        },
+          headers: {
+            cookies: "name=modernjs"
+          },
+          params: [{
+            id: 'modernjs',
+          }],
+        }
       ],
-    },
-  },
+    }
+  }
 });
 ```
 
-动态路由和 SSG 的组合，在根据 CMS 系统数据变更，实时生成静态页面时非常有用。
+:::note
+多入口的情况和单入口的配置方式一致，这里不再额外介绍。
+:::

package/docs/zh/guides/advanced-features/_meta.json

@@ -7,13 +7,6 @@
     "collapsed": true
   },
   "code-split",
-  {
-    "type": "dir",
-    "name": "ssr",
-    "label": "use-ssr",
-    "collapsed": true
-  },
-  "ssg",
   "compatibility",
   "eslint",
   "low-level",

package/docs/zh/guides/basic-features/_meta.json

@@ -1,5 +1,4 @@
 [
-  "css",
   "routes",
   {
     "type": "dir",
@@ -7,6 +6,13 @@
     "label": "data-solution",
     "collapsed": true
   },
+  {
+    "type": "dir",
+    "name": "render",
+    "label": "rendering",
+    "collapsed": true
+  },
+  "css",
   "alias",
   "mock",
   "proxy",