@bleedingdev/modern-js-app-tools 3.5.0-ultramodern.99 → 3.8.1-ultramodern.1

package/docs/guides/advanced-features/international/configuration.md

@@ -0,0 +1,228 @@
+# Configuration
+
+Plugin configuration is split between two files, each with a different responsibility:
+
+| File                    | Purpose                                          |
+| ----------------------- | ------------------------------------------------ |
+| `modern.config.ts`      | Basic plugin settings, read during build/startup |
+| `src/modern.runtime.ts` | i18next initialization options, read at runtime  |
+
+:::warning Function values can only be configured at runtime
+`modern.config.ts` runs at build time and cannot serialize functions. SDK loaders, custom detection functions, and similar function values must be placed in `modern.runtime.ts`.
+:::
+
+## Configuration Ownership
+
+| Configuration                                                  | Where to configure  |
+| -------------------------------------------------------------- | ------------------- |
+| `localeDetection` (language detection, path redirects, etc.)   | `modern.config.ts`  |
+| `backend` (resource paths, SDK declaration, etc.)              | `modern.config.ts`  |
+| `i18nInstance`                                                 | `modern.runtime.ts` |
+| `initOptions` (`fallbackLng`, `ns`, and other i18next options) | `modern.runtime.ts` |
+| The actual `backend.sdk` loader function                       | `modern.runtime.ts` |
+
+## CLI Configuration
+
+```ts title="modern.config.ts"
+import { appTools, defineConfig } from '@modern-js/app-tools';
+import { i18nPlugin } from '@modern-js/plugin-i18n';
+
+export default defineConfig({
+  plugins: [
+    appTools(),
+    i18nPlugin({
+      localeDetection: { ... },
+      backend: { ... },
+    }),
+  ],
+});
+```
+
+### localeDetection Options
+
+| Field                    | Type                                                | Default              | Description                                                                                                                                                                 |
+| ------------------------ | --------------------------------------------------- | -------------------- | --------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
+| `languages`              | `string[]`                                          | `[]`                 | Supported language list                                                                                                                                                     |
+| `fallbackLanguage`       | `string`                                            | `''`                 | Fallback language when detection fails                                                                                                                                      |
+| `localePathRedirect`     | `boolean`                                           | `false`              | Handles URL locale prefix recognition, redirects, and switching. See [Routing Integration](/guides/advanced-features/international/routing.md#enable-locale-path-prefixes)  |
+| `localisedUrls`          | `boolean \| Record<string, Record<string, string>>` | Prefix-only behavior | Localised route path map. Only a non-empty map enables translated path segments; omitted, `true`, `false`, and `{}` keep locale prefixes without translating path segments. |
+| `i18nextDetector`        | `boolean`                                           | `false`              | Enables the i18next detector (Cookie / Header, etc.)                                                                                                                        |
+| `detection`              | `LanguageDetectorOptions`                           | -                    | Detailed i18next detector configuration. See [Locale Detection](/guides/advanced-features/international/locale-detection.md)                                                |
+| `ignoreRedirectRoutes`   | `string[] \| Function`                              | -                    | Routes that skip redirects. See [Locale Detection](/guides/advanced-features/international/locale-detection.md#ignoreredirectroutes)                                        |
+| `localeDetectionByEntry` | `Record<string, ...>`                               | -                    | Per-entry overrides for multiple entries                                                                                                                                    |
+
+**Example:**
+
+```ts
+i18nPlugin({
+  localeDetection: {
+    localePathRedirect: true,
+    i18nextDetector: true,
+    languages: ['zh', 'en', 'ja'],
+    fallbackLanguage: 'en',
+    detection: {
+      order: ['path', 'cookie', 'header'],
+      lookupCookie: 'i18next',
+      caches: ['cookie'],
+    },
+  },
+});
+```
+
+### backend Options
+
+```ts
+interface BackendOptions {
+  // Whether to enable backend resource loading.
+  // Automatically enabled when loadPath/addPath is configured, or when a locales directory exists.
+  enabled?: boolean;
+
+  // Decides which URL or local file to request for translations. Supports {{lng}} and {{ns}}.
+  // Default: '/locales/{{lng}}/{{ns}}.json'
+  loadPath?: string;
+
+  // Path for reporting missing translations (optional).
+  addPath?: string;
+
+  // Enables the custom backend SDK. The actual loader is provided in runtime config.
+  sdk?: boolean | string;
+
+  // Cache strategy for chained backend mode, effective when both loadPath and sdk are configured.
+  // 'none'                  - use local files and do not request the custom backend after a hit
+  // 'refresh'               - continue requesting the custom backend and update cache, but not the page
+  // 'refreshAndUpdateStore' - continue requesting and update page text as well (default)
+  cacheHitMode?: 'none' | 'refresh' | 'refreshAndUpdateStore';
+
+  // Per-entry overrides for multiple-entry scenarios.
+  backendOptionsByEntry?: Record<string, BaseBackendOptions>;
+}
+```
+
+**About the `sdk` field:** In `modern.config.ts`, set it to `true` to declare that the SDK backend is enabled. Provide the actual loader in `initOptions.backend.sdk` in `modern.runtime.ts`. See [Resource Loading -> Custom Backend](/guides/advanced-features/international/resource-loading.md#custom-backend).
+
+**backend auto-enable rules:**
+
+| Situation                                                                          | Result                                                  |
+| ---------------------------------------------------------------------------------- | ------------------------------------------------------- |
+| `loadPath` or `addPath` is configured                                              | Automatically enabled. No need to write `enabled: true` |
+| No backend is configured, but a `locales` directory exists and contains JSON files | Automatically enabled with the default `loadPath`       |
+| `enabled: false` is set explicitly                                                 | Disabled, and auto-detection is skipped                 |
+
+Auto-detected directory locations, in priority order:
+
+1. `{project root}/config/public/locales`
+2. The `locales` subdirectory under the directory configured by `server.publicDir`
+
+**Which backend should you choose?**
+
+| Scenario                                                    | Recommended approach                                                     |
+| ----------------------------------------------------------- | ------------------------------------------------------------------------ |
+| Translation files are local to the project                  | Static file backend (configure `loadPath`; CSR/SSR switch automatically) |
+| Translations come from a remote API or translation platform | Custom backend (configure `sdk: true`)                                   |
+| Local fallback + remote real-time updates                   | Chained backend (configure both `loadPath` and `sdk`)                    |
+
+See [Resource Loading](/guides/advanced-features/international/resource-loading.md) for detailed usage.
+
+## Runtime Configuration
+
+```ts title="src/modern.runtime.ts"
+import { defineRuntimeConfig } from '@modern-js/runtime';
+import i18next from 'i18next';
+
+const i18nInstance = i18next.createInstance();
+
+export default defineRuntimeConfig({
+  i18n: {
+    i18nInstance,   // Optional. An isolated instance is recommended.
+    initOptions: {
+      fallbackLng: 'en',
+      supportedLngs: ['zh', 'en'],
+      ns: ['translation'],
+      defaultNS: 'translation',
+      interpolation: {
+        escapeValue: false, // React already escapes text; disable this to avoid double escaping.
+      },
+    },
+  },
+});
+```
+
+### i18nInstance Configuration
+
+If you need to use a custom i18n instance, provide it in the runtime configuration:
+
+```ts
+import { defineRuntimeConfig } from '@modern-js/runtime';
+import i18next from 'i18next';
+
+// 创建自定义实例
+const customI18n = i18next.createInstance({
+  // 自定义配置
+});
+
+export default defineRuntimeConfig({
+  i18n: {
+    i18nInstance: customI18n,
+  },
+});
+```
+
+### initOptions
+
+支持所有 [i18next 初始化选项](https://www.i18next.com/overview/configuration-options)，常用选项说明如下：
+
+| Field           | Description                                                                                                                            |
+| --------------- | -------------------------------------------------------------------------------------------------------------------------------------- |
+| `fallbackLng`   | Which language resources i18next falls back to when a translation key is missing. Supports strings, arrays, and maps (fallback chains) |
+| `supportedLngs` | Language list supported by i18next                                                                                                     |
+| `ns`            | Namespace list. Default is `['translation']`                                                                                           |
+| `defaultNS`     | Default namespace. Default is `'translation'`                                                                                          |
+| `lng`           | Forces the initial language. Usually not needed because the detector decides it                                                        |
+
+`fallbackLng` supports fallback chains, which are useful for regional language degradation:
+
+```ts
+initOptions: {
+  lng: 'zh-CN',
+  fallbackLng: {
+    'zh-CN': ['zh', 'en'], // If zh-CN is missing, try zh first, then en.
+    default: ['en'],
+  },
+},
+```
+
+### Custom Backend Function Configuration
+
+The actual loader function for a custom backend must be provided in runtime configuration:
+
+```ts
+// modern.config.ts: only declare that it is enabled.
+i18nPlugin({
+  backend: { sdk: true },
+});
+
+// modern.runtime.ts: provide the actual function.
+import type { I18nSdkLoader } from '@modern-js/plugin-i18n/runtime';
+
+const myLoader: I18nSdkLoader = async options => {
+  if (options.lng && options.ns) {
+    const res = await fetch(`/api/i18n/${options.lng}/${options.ns}`);
+    return res.json();
+  }
+  return {};
+};
+
+export default defineRuntimeConfig({
+  i18n: {
+    initOptions: {
+      backend: { sdk: myLoader },
+    },
+  },
+});
+```
+
+For complete usage, see [Resource Loading -> Custom Backend](/guides/advanced-features/international/resource-loading.md#custom-backend).
+
+## Multiple Entries
+
+Multiple-entry projects can override configuration per entry. See [Advanced Usage -> Multiple Entries](/guides/advanced-features/international/advanced.md#multiple-entries).

package/docs/guides/advanced-features/international/{locale-detection.mdx → locale-detection.md}

@@ -1,7 +1,3 @@
----
-title: Locale Detection
----
-
 # Locale Detection
 
 Locale detection means automatically inferring which language to use when the user has not manually selected one. The plugin can detect language from URL path, Cookie, request headers, browser settings, and other sources, and these methods can be combined.
@@ -38,7 +34,7 @@ i18nPlugin({
 });
 ```
 
-After enabling path detection, you also need to configure a `[lang]` dynamic parameter in your routes. See [Routing Integration](./routing.md).
+After enabling path detection, you also need to configure a `[lang]` dynamic parameter in your routes. See [Routing Integration](/guides/advanced-features/international/routing.md).
 
 ### i18next Detector
 
@@ -77,19 +73,19 @@ i18nPlugin({
 
 ## Detection Options (`detection`)
 
-| Option | Type | Default | Description |
-| --- | --- | --- | --- |
-| `order` | `string[]` | See below | Detection order inside the i18next detector |
-| `lookupQuerystring` | `string` | `'lng'` | Query parameter key, such as `?lng=en` |
-| `lookupCookie` | `string` | `'i18next'` | Cookie key |
-| `lookupLocalStorage` | `string` | `'i18nextLng'` | LocalStorage key (browser only) |
-| `lookupSession` | `string` | - | SessionStorage key (browser only) |
-| `lookupHeader` | `string` | `'accept-language'` | HTTP request header key |
-| `lookupFromPathIndex` | `number` | `0` | Which URL path segment to start recognizing language from |
-| `caches` | `false \| string[]` | - | Where to cache the detected language, such as `['cookie']` |
-| `cookieMinutes` | `number` | `525600` (1 year) | Cookie expiration time in minutes |
-| `cookieExpirationDate` | `Date` | - | Cookie expiration date. Takes precedence over `cookieMinutes` |
-| `cookieDomain` | `string` | - | Cookie domain |
+| Option                 | Type                | Default             | Description                                                   |
+| ---------------------- | ------------------- | ------------------- | ------------------------------------------------------------- |
+| `order`                | `string[]`          | See below           | Detection order inside the i18next detector                   |
+| `lookupQuerystring`    | `string`            | `'lng'`             | Query parameter key, such as `?lng=en`                        |
+| `lookupCookie`         | `string`            | `'i18next'`         | Cookie key                                                    |
+| `lookupLocalStorage`   | `string`            | `'i18nextLng'`      | LocalStorage key (browser only)                               |
+| `lookupSession`        | `string`            | -                   | SessionStorage key (browser only)                             |
+| `lookupHeader`         | `string`            | `'accept-language'` | HTTP request header key                                       |
+| `lookupFromPathIndex`  | `number`            | `0`                 | Which URL path segment to start recognizing language from     |
+| `caches`               | `false \| string[]` | -                   | Where to cache the detected language, such as `['cookie']`    |
+| `cookieMinutes`        | `number`            | `525600` (1 year)   | Cookie expiration time in minutes                             |
+| `cookieExpirationDate` | `Date`              | -                   | Cookie expiration date. Takes precedence over `cookieMinutes` |
+| `cookieDomain`         | `string`            | -                   | Cookie domain                                                 |
 
 **Default detection order when `order` is not configured:**
 
@@ -99,17 +95,17 @@ i18nPlugin({
 
 **Available `order` values:**
 
-| Value | Source | Limitation |
-| --- | --- | --- |
-| `querystring` | URL query parameter (`?lng=en`) | - |
-| `cookie` | Cookie | - |
-| `localStorage` | LocalStorage | Browser only |
-| `sessionStorage` | SessionStorage | Browser only |
-| `navigator` | Browser language settings | Browser only |
-| `htmlTag` | `<html lang="...">` | Browser only |
-| `header` | `Accept-Language` request header | - |
-| `path` | URL path (requires `localePathRedirect`) | - |
-| `subdomain` | Subdomain (`en.example.com`) | - |
+| Value            | Source                                   | Limitation   |
+| ---------------- | ---------------------------------------- | ------------ |
+| `querystring`    | URL query parameter (`?lng=en`)          | -            |
+| `cookie`         | Cookie                                   | -            |
+| `localStorage`   | LocalStorage                             | Browser only |
+| `sessionStorage` | SessionStorage                           | Browser only |
+| `navigator`      | Browser language settings                | Browser only |
+| `htmlTag`        | `<html lang="...">`                      | Browser only |
+| `header`         | `Accept-Language` request header         | -            |
+| `path`           | URL path (requires `localePathRedirect`) | -            |
+| `subdomain`      | Subdomain (`en.example.com`)             | -            |
 
 ## ignoreRedirectRoutes
 

package/docs/guides/advanced-features/international/{quick-start.mdx → quick-start.md}

@@ -1,16 +1,19 @@
----
-title: Quick Start
----
-
 # Quick Start
 
 This guide helps you quickly integrate internationalization into a Modern.js project.
 
 ## Install the Plugin
 
-import InstallCommand from '@site-docs/components/international/install-command';
+`i18next` 和 `react-i18next` 是 **Peer Dependency**，需要手动安装。
 
-<InstallCommand />
+:::note 版本一致性
+`@modern-js/plugin-i18n` 需要与项目中 `@modern-js/app-tools` 版本保持一致。
+:::
+
+```bash
+pnpm list @modern-js/app-tools
+pnpm add @modern-js/plugin-i18n@<version> i18next react-i18next
+```
 
 ## Basic Configuration
 
@@ -67,9 +70,22 @@ config/public/locales/
 
 ### Step 3: Configure Runtime Options
 
-import InstanceCode from '@site-docs/components/international/instance-code';
+创建 `src/modern.runtime.ts`：
 
-<InstanceCode />
+```ts
+import { defineRuntimeConfig } from '@modern-js/runtime';
+import i18next from 'i18next';
+
+// i18next 默认导出一个全局单例，多个应用共用会互相影响。
+// createInstance() 创建独立实例，确保每个应用有独立的语言状态。
+const i18nInstance = i18next.createInstance();
+
+export default defineRuntimeConfig({
+  i18n: {
+    i18nInstance,
+  },
+});
+```
 
 ### Step 4: Use It in Components
 
@@ -105,8 +121,8 @@ function App() {
 
 Choose what to read next based on your needs:
 
-- **Want a URL structure like `/en/about`** -> [Routing Integration](./routing.md)
-- **Need automatic language switching based on Cookie / Header** -> [Locale Detection](./locale-detection.md)
-- **Translation resources come from a remote service** -> [Resource Loading -> Custom Backend](./resource-loading.md#custom-backend)
-- **SSR scenarios** -> [Advanced Usage](./advanced.md)
-- **View all configuration options** -> [Configuration](./configuration.md)
+- **Want a URL structure like `/en/about`** -> [Routing Integration](/guides/advanced-features/international/routing.md)
+- **Need automatic language switching based on Cookie / Header** -> [Locale Detection](/guides/advanced-features/international/locale-detection.md)
+- **Translation resources come from a remote service** -> [Resource Loading -> Custom Backend](/guides/advanced-features/international/resource-loading.md#custom-backend)
+- **SSR scenarios** -> [Advanced Usage](/guides/advanced-features/international/advanced.md)
+- **View all configuration options** -> [Configuration](/guides/advanced-features/international/configuration.md)

package/docs/guides/advanced-features/international/{resource-loading.mdx → resource-loading.md}

@@ -1,16 +1,12 @@
----
-title: Resource Loading
----
-
 # Resource Loading
 
 How translation files are loaded depends on where your translation resources are stored:
 
-| Scenario | Loading method |
-| --- | --- |
-| Translation files are local to the project | Static file backend (the default method in this guide) |
-| Translations come from a remote API or translation platform | Custom backend |
-| Both: local fallback + remote real-time updates | Chained backend |
+| Scenario                                                    | Loading method                                         |
+| ----------------------------------------------------------- | ------------------------------------------------------ |
+| Translation files are local to the project                  | Static file backend (the default method in this guide) |
+| Translations come from a remote API or translation platform | Custom backend                                         |
+| Both: local fallback + remote real-time updates             | Chained backend                                        |
 
 ## Static File Backend
 
@@ -111,7 +107,7 @@ interface I18nSdkLoadOptions {
 }
 ```
 
-When using a custom backend, translation resources are loaded asynchronously. You can use `isResourcesReady` to show a loading state before loading is complete. See [Best Practices -> Loading State Handling](./best-practices.md#loading-state-handling).
+When using a custom backend, translation resources are loaded asynchronously. You can use `isResourcesReady` to show a loading state before loading is complete. See [Best Practices -> Loading State Handling](/guides/advanced-features/international/best-practices.md#loading-state-handling).
 
 ## Chained Backend
 
@@ -151,8 +147,8 @@ export default defineRuntimeConfig({
 
 **`cacheHitMode` option** (controls how the two backends cooperate):
 
-| Value | Behavior |
-| --- | --- |
-| `'none'` | Use local files after a successful local hit and do not request the custom backend |
-| `'refresh'` | Continue requesting the custom backend and update cache, but do not update the current page |
-| `'refreshAndUpdateStore'` | Continue requesting the custom backend, update cache, and refresh page text (default) |
+| Value                     | Behavior                                                                                    |
+| ------------------------- | ------------------------------------------------------------------------------------------- |
+| `'none'`                  | Use local files after a successful local hit and do not request the custom backend          |
+| `'refresh'`               | Continue requesting the custom backend and update cache, but do not update the current page |
+| `'refreshAndUpdateStore'` | Continue requesting the custom backend, update cache, and refresh page text (default)       |

package/docs/guides/advanced-features/international/{routing.mdx → routing.md}

@@ -1,7 +1,3 @@
----
-title: Routing Integration
----
-
 # Routing Integration
 
 ## Enable Locale Path Prefixes
@@ -26,13 +22,13 @@ i18nPlugin({
 
 **Result:**
 
-| Visited path | Result |
-| --- | --- |
-| `/about` | Redirects to `/en/about` |
-| `/en/about` | Visits normally, language is `en` |
-| `/zh/about` | Visits normally, language is `zh` |
+| Visited path | Result                            |
+| ------------ | --------------------------------- |
+| `/about`     | Redirects to `/en/about`          |
+| `/en/about`  | Visits normally, language is `en` |
+| `/zh/about`  | Visits normally, language is `zh` |
 
-API and BFF prefixes are skipped automatically, including server API routes, the default `/api` BFF prefix when BFF is configured, and custom `bff.prefix` values. Those routes do not need locale prefixes or `localisedUrls` entries. For additional application paths that should not redirect, use `ignoreRedirectRoutes`. See [Locale Detection -> ignoreRedirectRoutes](./locale-detection.md#ignoreredirectroutes).
+API and BFF prefixes are skipped automatically, including server API routes, the default `/api` BFF prefix when BFF is configured, and custom `bff.prefix` values. Those routes do not need locale prefixes or `localisedUrls` entries. For additional application paths that should not redirect, use `ignoreRedirectRoutes`. See [Locale Detection -> ignoreRedirectRoutes](/guides/advanced-features/international/locale-detection.md#ignoreredirectroutes).
 
 ## Localised URL Paths
 
@@ -69,11 +65,11 @@ i18nPlugin({
 
 **Result:**
 
-| Visited path | Result |
-| --- | --- |
-| `/terms-of-service` | Redirects to `/en/terms-of-service` |
-| `/cs/terms-of-service` | Redirects to `/cs/podminky-pouzivani` |
-| `/cs/podminky-pouzivani` | Visits normally, language is `cs` |
+| Visited path             | Result                                |
+| ------------------------ | ------------------------------------- |
+| `/terms-of-service`      | Redirects to `/en/terms-of-service`   |
+| `/cs/terms-of-service`   | Redirects to `/cs/podminky-pouzivani` |
+| `/cs/podminky-pouzivani` | Visits normally, language is `cs`     |
 
 Set `localisedUrls: false` as the escape hatch when a preset, shared config, or generated metadata would otherwise provide a map but this entry should keep locale prefixes without translated path segments.
 
@@ -174,4 +170,4 @@ function Navigation() {
 <I18nLink to="/en/about">About</I18nLink>
 ```
 
-`I18nLink` uses the active Modern.js router. In React Router projects it renders the React Router `Link`; in TanStack Router projects it navigates through TanStack Router. For the full Props type, see [API Reference](./api.md#i18nlink-component).
+`I18nLink` uses the active Modern.js router. In React Router projects it renders the React Router `Link`; in TanStack Router projects it navigates through TanStack Router. For the full Props type, see [API Reference](/guides/advanced-features/international/api.md#i18nlink-component).

package/docs/guides/advanced-features/international.md

@@ -0,0 +1,27 @@
+# Internationalization
+
+`@modern-js/plugin-i18n` 是 Modern.js 的国际化插件，基于 [i18next](https://www.i18next.com/) 和 [react-i18next](https://react.i18next.com/) 构建。
+
+- **插件本身**：负责与 Modern.js 框架的集成，如 SSR 语言传递、路由前缀处理等
+- **i18next**：核心翻译能力，如 `t()` 函数、插值、复数、命名空间。
+- **react-i18next**：React 组件和 Hook，如 `useTranslation`，实现与 React 生命周期的结合。
+
+## Where to start?
+
+| What you want to do                                          | Documentation                                                                                                    |
+| ------------------------------------------------------------ | ---------------------------------------------------------------------------------------------------------------- |
+| Integrate for the first time and run an example              | [Quick Start](/guides/advanced-features/international/quick-start.md)                                            |
+| Learn all configuration options                              | [Configuration](/guides/advanced-features/international/configuration.md)                                        |
+| Detect language from URL / Cookie / Header                   | [Locale Detection](/guides/advanced-features/international/locale-detection.md)                                  |
+| Implement paths with locale prefixes, such as `/en/about`    | [Routing Integration](/guides/advanced-features/international/routing.md)                                        |
+| Load translation resources from a remote service or platform | [Resource Loading -> Custom Backend](/guides/advanced-features/international/resource-loading.md#custom-backend) |
+| SSR, multiple entries, or custom instances                   | [Advanced Usage](/guides/advanced-features/international/advanced.md)                                            |
+| Look up Hooks / components / type definitions                | [API Reference](/guides/advanced-features/international/api.md)                                                  |
+
+## Core Capabilities
+
+- **Locale detection**: Supports detection from URL path, Cookie, LocalStorage, request headers, browser settings, and other sources, with configurable priority.
+- **Resource loading**: Supports HTTP static files, file system loading for SSR, custom SDK functions, and chained backend progressive loading.
+- **Routing integration**: Automatically adds locale path prefixes such as `/en/about`, and provides the `I18nLink` component for locale-aware navigation.
+- **SSR support**: Detects the language on the server and injects it into the page so the client can reuse it directly and avoid language flicker.
+- **TypeScript support**: Provides complete type definitions and supports type-safe translation keys.

package/docs/guides/advanced-features/{low-level.mdx → low-level.md}

@@ -1,7 +1,3 @@
----
-sidebar_position: 10
----
-
 # Low-Level Tools
 
 ## Usage
@@ -10,7 +6,7 @@ Modern.js internally integrates tools such as [TypeScript](https://www.typescrip
 
 Usually, the default configuration can meet most development needs. When there are special needs, it can be achieved through the underlying configuration.
 
-Take configuring Rspack as an example, just add [tools.rspack](/configure/app/tools/rspack) to the modern.config.ts:
+Take configuring Rspack as an example, just add [tools.rspack](/configure/app/tools/rspack.md) to the modern.config.ts:
 
 ```ts title="modern.config.ts"
 export default defineConfig({
@@ -32,19 +28,19 @@ When the value is `Function`, the first parameter is the default configuration v
 
 Currently provided is as follows:
 
-| Tools              | Config                                                               |
-| ------------------ | -------------------------------------------------------------------- |
-| Rspack             | [tools.rspack](/configure/app/tools/rspack)                          |
-| Bundler Chain      | [tools.bundlerChain](/configure/app/tools/bundler-chain)             |
-| SWC                | [tools.swc](/configure/app/tools/swc)                                |
-| TypeScript Checker | [tools.tsChecker](/configure/app/tools/ts-checker)                   |
-| PostCSS            | [tools.postcss](/configure/app/tools/postcss)                        |
-| Less               | [tools.less](/configure/app/tools/less)                              |
-| Sass               | [tools.sass](/configure/app/tools/sass)                              |
-| CSS Extract        | [tools.cssExtract](/configure/app/tools/css-extract)                 |
-| CSS Loader         | [tools.cssLoader](/configure/app/tools/css-loader)                   |
-| Style Loader       | [tools.styleLoader](/configure/app/tools/style-loader)               |
-| Lightning CSS      | [tools.lightningcssLoader](/configure/app/tools/lightningcss-loader) |
-| Minify CSS         | [tools.minifyCss](/configure/app/tools/minify-css)                   |
-| Autoprefixer       | [tools.autoprefixer](/configure/app/tools/autoprefixer)              |
-| HTML Plugin        | [tools.htmlPlugin](/configure/app/tools/html-plugin)                 |
+| Tools              | Config                                                                  |
+| ------------------ | ----------------------------------------------------------------------- |
+| Rspack             | [tools.rspack](/configure/app/tools/rspack.md)                          |
+| Bundler Chain      | [tools.bundlerChain](/configure/app/tools/bundler-chain.md)             |
+| SWC                | [tools.swc](/configure/app/tools/swc.md)                                |
+| TypeScript Checker | [tools.tsChecker](/configure/app/tools/ts-checker.md)                   |
+| PostCSS            | [tools.postcss](/configure/app/tools/postcss.md)                        |
+| Less               | [tools.less](/configure/app/tools/less.md)                              |
+| Sass               | [tools.sass](/configure/app/tools/sass.md)                              |
+| CSS Extract        | [tools.cssExtract](/configure/app/tools/css-extract.md)                 |
+| CSS Loader         | [tools.cssLoader](/configure/app/tools/css-loader.md)                   |
+| Style Loader       | [tools.styleLoader](/configure/app/tools/style-loader.md)               |
+| Lightning CSS      | [tools.lightningcssLoader](/configure/app/tools/lightningcss-loader.md) |
+| Minify CSS         | [tools.minifyCss](/configure/app/tools/minify-css.md)                   |
+| Autoprefixer       | [tools.autoprefixer](/configure/app/tools/autoprefixer.md)              |
+| HTML Plugin        | [tools.htmlPlugin](/configure/app/tools/html-plugin.md)                 |

package/docs/guides/advanced-features/page-performance/{code-split.mdx → code-split.md}

@@ -1,13 +1,9 @@
----
-sidebar_position: 3
----
-
 # Code Splitting
 
 Code splitting is a common way to optimize frontend resource loading. This article will introduce the three types of code splitting supported by Modern.js:
 
 :::info
-When using Modern.js [Conventional routing](/guides/basic-features/routes/routes#conventional-routing). By default, code splitting is done according to the routing component, so you don't need to do it yourself.
+When using Modern.js [Conventional routing](/guides/basic-features/routes/routes.md#conventional-routing). By default, code splitting is done according to the routing component, so you don't need to do it yourself.
 :::
 
 - dynamic `import`
@@ -78,4 +74,4 @@ However, it's important to note that any Loadable API in SSR does not support th
 If you want to use `<Suspense>` in CSR projects with React 17 and below, you can substitute `React.lazy` with `loadable.lazy`.
 :::
 
-For details, see [Loadable API](/apis/app/runtime/utility/loadable).
+For details, see [Loadable API](/apis/app/runtime/utility/loadable.md).

package/docs/guides/advanced-features/page-performance/{inline-assets.mdx → inline-assets.md}

@@ -1,7 +1,3 @@
----
-sidebar_position: 13
----
-
 # Inline Static Assets
 
 Inline static assets refer to the practice of including the content of a static asset directly in a HTML or JS file, instead of linking to an external file. This can improve the performance of a website by reducing the number of HTTP requests that the browser has to make to load the page.
@@ -14,7 +10,7 @@ Modern.js will automatically inline static assets that are less than 10KB, but s
 
 By default, Modern.js will inline assets when the file size of is less than a threshold (the default is 10KB). When inlined, the asset will be converted to a Base64 encoded string and will no longer send a separate HTTP request. When the file size is greater than this threshold, it is loaded as a separate file with a separate HTTP request.
 
-The threshold can be modified with the [output.dataUriLimit](/configure/app/output/data-uri-limit) config. For example, set the threshold of images to 5000 Bytes, and set media assets not to be inlined:
+The threshold can be modified with the [output.dataUriLimit](/configure/app/output/data-uri-limit.md) config. For example, set the threshold of images to 5000 Bytes, and set media assets not to be inlined:
 
 ```ts
 export default {
@@ -102,7 +98,7 @@ Excluding assets from inlining will increase the number of assets that the Web A
 
 In addition to inlining static assets into JS files, Modern.js also supports inlining JS files into HTML files.
 
-Just enable the [output.inlineScripts](/configure/app/output/inline-scripts) config, and the generated JS files will not be written into the output directory, but will be directly inlined to the corresponding in the HTML file.
+Just enable the [output.inlineScripts](/configure/app/output/inline-scripts.md) config, and the generated JS files will not be written into the output directory, but will be directly inlined to the corresponding in the HTML file.
 
 ```ts
 export default {
@@ -120,7 +116,7 @@ Inline JS files may cause the single HTML file to be too large, and it will brea
 
 You can also inline CSS files into HTML files.
 
-Just enable the [output.inlineStyles](/configure/app/output/inline-styles) config, the generated CSS file will not be written into the output directory, but will be directly inlined to the corresponding in the HTML file.
+Just enable the [output.inlineStyles](/configure/app/output/inline-styles.md) config, the generated CSS file will not be written into the output directory, but will be directly inlined to the corresponding in the HTML file.
 
 ```ts
 export default {