docs: Add wrap vs eject guides for customizing Rspress theme

website/docs/en/guide/basic/_meta.json

@@ -7,5 +7,6 @@
   "i18n",
   "multi-version",
   "home-page",
-  "deploy"
+  "deploy",
+  "wrap-and-eject"
 ]

website/docs/en/guide/basic/wrap-and-eject.mdx

@@ -0,0 +1,40 @@
+# Customize themes with wrap and eject
+
+In simple terms: `theme/index.tsx` can re-export and replace built-in components. After that you have two paths—**wrap (no source edits, pass props/slots)** or **eject (copy source, edit freely)**. See [custom theme](/ui/custom-theme) for more examples.
+
+## `theme/index.tsx`: override built-ins via re-export
+
+Rspress loads the theme from `theme/index.tsx` at the project root. You can use **ESM re-export** here to override default exports or same-name components; any internal usage will prefer your re-exported version:
+
+```tsx title="theme/index.tsx"
+import { Layout as BasicLayout } from '@rspress/core/theme-original';
+
+const Layout = () => <BasicLayout beforeNavTitle={<div>some content</div>} />;
+
+export { Layout };
+
+export * from '@rspress/core/theme-original';
+```
+
+- `Layout` is the theme entry; Rspress auto-loads it. By exporting a same-name component you can wrap or replace the default.
+- `export * from '@rspress/core/theme-original'` keeps other default exports available while your overrides take effect.
+- This capability underpins all customization: you may simply wrap defaults or swap in your own implementations before re-exporting.
+
+## Wrap: add props/slots on top of re-exports
+
+Wrap means extending the re-exported components with extra props, e.g., using `Layout` slots:
+
+- No source edits: just wrap in `theme/index.tsx` and pass props/slots to built-ins.
+- Great for light tweaks: style nits, slot content, or swapping a few same-name components.
+
+## Eject: copy source then edit directly
+
+Eject uses the CLI `rspress eject` to copy `@rspress/core/theme-original` source into your project so you can edit it directly:
+
+- Gives you source: `rspress eject` copies theme source locally so you can change internals.
+- You maintain it: decoupled from upstream; you must sync updates yourself when upgrading.
+
+## Recommendations
+
+- **Prefer Wrap**: safer, easier to upgrade, covers most style/slot needs.
+- **Consider Eject**: only when you must change internals that Wrap can’t cover.

website/docs/zh/guide/basic/_meta.json

@@ -7,5 +7,6 @@
   "i18n",
   "multi-version",
   "home-page",
-  "deploy"
+  "deploy",
+  "wrap-and-eject"
 ]

website/docs/zh/guide/basic/wrap-and-eject.mdx

@@ -0,0 +1,40 @@
+# 用 wrap 和 eject 定制主题
+
+本篇用更直白的方式说明：通过 `theme/index.tsx` 重导出可以替换 Rspress 内置组件，然后有两条路——**wrap（不改源码，传 props/插槽）** 和 **eject（复制源码，直接改）**。可参考 [自定义主题](/zh/ui/custom-theme) 里的示例。
+
+## `theme/index.tsx`：重导出覆盖内置组件
+
+Rspress 通过项目根目录的 `theme/index.tsx` 加载主题。你可以在这里通过 **ESM 重导出**覆写默认导出或同名组件，所有 Rspress 内部引用的内置组件都会优先使用你重导出的版本：
+
+```tsx title="theme/index.tsx"
+import { Layout as BasicLayout } from '@rspress/core/theme-original';
+
+const Layout = () => <BasicLayout beforeNavTitle={<div>some content</div>} />;
+
+export { Layout };
+
+export * from '@rspress/core/theme-original';
+```
+
+- `Layout` 是主题入口，Rspress 会自动加载；通过同名导出你可以替换或包裹默认组件。
+- `export * from '@rspress/core/theme-original'` 保留默认主题的其它导出，仅对你覆写的组件生效。
+- 该能力是所有自定义方式的基础：你可以只包裹默认组件，也可以在重导出前彻底替换。
+
+## Wrap：在重导出的基础上传 props/插槽
+
+Wrap 指在重导出的组件上增加 props 进行定制，例如利用 Layout 的插槽：
+
+- 不改源码：只在 `theme/index.tsx` 里包一层，给内置组件传 props/插槽。
+- 轻量改动：样式微调、在插槽里加内容、或用同名导出替换少量组件。
+
+## Eject：复制源码后直接修改
+
+Eject 指使用 CLI `rspress eject` 将 `@rspress/core/theme-original` 的源码拷贝到本地，然后直接改动：
+
+- 有源码：`rspress eject` 把主题源码拷到本地，直接改内部实现。
+- 需维护：与上游解耦，后续升级要自己同步改动。
+
+## 选择建议
+
+- **优先使用 Wrap**：低风险、易升级，能满足大多数样式和插槽需求。
+- **再考虑 Eject**：只有当需要改内部逻辑、Wrap 覆盖不了时，再执行 `rspress eject`。