docs: Split runtime hook docs into dedicated UI hook pages

website/docs/en/api/_meta.json

@@ -9,10 +9,5 @@
     "name": "config",
     "label": "config"
   },
-  {
-    "type": "dir",
-    "name": "client-api",
-    "label": "clientApi"
-  },
   "commands"
 ]

website/docs/en/plugin/official-plugins/algolia.mdx

@@ -247,7 +247,7 @@ new Crawler({
 
 ## Distinguish search results based on i18n
 
-You can achieve internationalized search results by combining [Runtime API](/api/client-api/api-runtime) with `docSearchProps`.
+You can achieve internationalized search results by combining [Runtime API](/ui/hooks/) with `docSearchProps`.
 
 Here's an example using `docSearchProps.searchParameters`:
 

website/docs/en/plugin/system/introduction.mdx

@@ -11,6 +11,6 @@ Rspress is divided into two parts: **Node Side** and **Browser Runtime**. Throug
 - [**Markdown/MDX compilation**](/plugin/system/plugin-api#markdown)。You can add [`remark`](https://github.com/remarkjs/remark)/[`rehype`](https://github.com/rehypejs/rehype) plugins to extend the compilation ability of Markdown/MDX.
 - [**Add custom page**](/plugin/system/plugin-api#addpages). On the basis of Rspress's conventional routing, you can also add new routes through plugins, such as adding a `/blog` route to display a list of blogs, and the content is defined by yourself.
 - [**Custom build tool behavior**](/plugin/system/plugin-api#builderconfig).In Rspress plugin, you can customize the config of the underlying build tool [Rsbuild](https://rsbuild.rs), and you can also add some Rspack or Rsbuild plugins.
-- [**Extend page metadata**](/plugin/system/plugin-api#extendpagedata). For each page, some metadata will be calculated inside Rspress, such as `title`, `description`, etc. You can extend the calculation logic of these metadata through plugins, and pass [usePageData](/api/client-api/api-runtime.html#usepagedata) hook access.
+- [**Extend page metadata**](/plugin/system/plugin-api#extendpagedata). For each page, some metadata will be calculated inside Rspress, such as `title`, `description`, etc. You can extend the calculation logic of these metadata through plugins, and pass [usePageData](/ui/hooks/use-page-data) hook access.
 - Insert some [**custom logic**](/plugin/system/plugin-api#beforebuild/afterbuild) before and after the build process. Such as closing some event listeners after the build process ends.
 - [**Add global components**](/plugin/system/plugin-api#globaluicomponents). Rspress internally uses React for rendering. You can flexibly extend the runtime page by defining global React components, such as `adding a global BackToTop (return to top) component`, `adding a global side effect logic`.

website/docs/en/ui/components/package-manager-tabs.mdx

@@ -1,12 +1,16 @@
-import { PackageManagerTabs } from '@theme';
+---
+overviewHeaders: []
+---
+
+import { PackageManagerTabs, Tag } from '@theme';
 
-# PackageManagerTabs
+# PackageManagerTabs <Tag tag="ejectable" />
 
 PackageManagerTabs displays commands for different package managers.
 
 ## Basic usage
 
-```mdx preview title="index.mdx"
+```mdx title="index.mdx"
 import { PackageManagerTabs } from '@theme';
 
 <PackageManagerTabs command="install -D @rspress/core" />

website/docs/en/ui/custom-theme.mdx

@@ -130,7 +130,7 @@ export { Search, HomeLayout, NotFoundLayout };
 export * from '@rspress/core/theme-original';
 ```
 
-Of course, you may need to use page data during the development process, you can get it through [`Runtime API`](/api/client-api/api-runtime).
+Of course, you may need to use page data during the development process, you can get it through [`Runtime API`](/ui/hooks/).
 
 ### 4. Custom icon
 

website/docs/en/ui/hooks/_meta.json

@@ -1 +1,8 @@
-["use-i18n"]
+[
+  "use-lang",
+  "use-version",
+  "use-dark",
+  "router-hooks",
+  "use-i18n",
+  "use-page-data"
+]

website/docs/en/ui/hooks/index.mdx

@@ -0,0 +1,4 @@
+---
+overview: true
+title: Built-in hooks
+---

website/docs/en/ui/hooks/router-hooks.mdx

@@ -0,0 +1,25 @@
+# Router hooks
+
+Rspress re-exports the routing utilities from `react-router-dom`, letting you access navigation and location data without adding extra dependencies.
+
+- **Type:** the same signatures as the corresponding `react-router-dom` hooks
+
+Commonly used hooks include `useLocation`, `useNavigate`, `useParams`, `useSearchParams`, and `useMatches`.
+
+```tsx
+import { useLocation, useNavigate } from '@rspress/core/runtime';
+
+export default function LocationDebugger() {
+  const location = useLocation();
+  const navigate = useNavigate();
+
+  return (
+    <div>
+      <div>Current path: {location.pathname}</div>
+      <button type="button" onClick={() => navigate('/')}>
+        Back to home
+      </button>
+    </div>
+  );
+}
+```

website/docs/en/ui/hooks/use-dark.mdx

@@ -0,0 +1,40 @@
+# useDark
+
+`useDark` reports whether the current theme is dark mode.
+
+- **Type:** `() => boolean`
+
+```tsx preview
+import { useDark } from '@rspress/core/runtime';
+
+export default function ThemeSwitchHint() {
+  const isDark = useDark();
+  return <div>{isDark ? 'Dark theme enabled' : 'Light theme enabled'}</div>;
+}
+```
+
+:::warning Note
+
+During SSG, `useDark` cannot accurately reflect the user's browser theme setting because SSG is executed at build time. This hook will only return the correct theme value after client-side hydration is complete.
+
+If you need to apply dark theme styles during SSG, it's recommended to use the CSS selector `.dark` for styling. Rspress adds the `dark` class name to the document root element, which works correctly in both SSG and client-side rendering:
+
+```css
+/* Light mode */
+.my-component {
+  color: black;
+  background-color: white;
+}
+
+/* Dark mode */
+.dark .my-component {
+  color: white;
+  background-color: #1a1a1a;
+}
+```
+
+:::
+
+```
+
+```

website/docs/en/ui/hooks/use-lang.mdx

@@ -0,0 +1,16 @@
+# useLang
+
+`useLang` returns the current locale code so you can render language-specific content or route users accordingly.
+
+- **Type:** `() => string`
+
+The hook reads the active language from the runtime context and stays in sync when users switch locales.
+
+```tsx preview
+import { useLang } from '@rspress/core/runtime';
+
+export default function Comp() {
+  const lang = useLang();
+  return <span>Current language: {lang}</span>;
+}
+```

website/docs/en/ui/hooks/use-page-data.mdx

@@ -0,0 +1,22 @@
+---
+tag: deprecated
+---
+
+# usePageData
+
+`usePageData` exposes the metadata of the current page so you can render it inside custom components or utilities.
+
+- **Type:** `() => PageData`
+
+The returned `PageData` object includes information such as the page title, route path, frontmatter, and site-wide data. This hook is available on both the server and client, making it suitable for SSR and SSG-safe rendering.
+
+```tsx
+import { usePageData } from '@rspress/core/runtime';
+
+export default function PageTitle() {
+  const { page } = usePageData();
+  return <h1>{page.title}</h1>;
+}
+```
+
+> Related: you can pair this hook with [`useLang`](./use-lang) or [`useVersion`](./use-version) to tailor content by locale or documentation version.

website/docs/en/ui/hooks/use-version.mdx

@@ -0,0 +1,16 @@
+# useVersion
+
+`useVersion` provides the current documentation version when multi-version docs are enabled.
+
+- **Type:** `() => string`
+
+Use it to surface the active version in UI or to branch logic for versioned content.
+
+```tsx
+import { useVersion } from '@rspress/core/runtime';
+
+export default function VersionTag() {
+  const version = useVersion();
+  return <div>Viewing docs for version {version}</div>;
+}
+```

website/docs/zh/api/_meta.json

@@ -9,10 +9,5 @@
     "name": "config",
     "label": "config"
   },
-  {
-    "type": "dir",
-    "name": "client-api",
-    "label": "clientApi"
-  },
   "commands"
 ]