From 028ee31b06c398368f2dfa401c132c64964ec223 Mon Sep 17 00:00:00 2001
From: =?UTF-8?q?=E5=86=B0=E5=86=BB=E5=A4=A7=E8=A5=BF=E7=93=9C?=
 <34816426+bd-dxg@users.noreply.github.com>
Date: Sun, 19 Jul 2026 16:20:44 +0800
Subject: [PATCH] docs: add base path prefix docs to sidebar reference (#5324)

Co-authored-by: Divyansh Singh <40380293+brc-dd@users.noreply.github.com>
---
 docs/en/reference/default-theme-sidebar.md | 60 ++++++++++++++++++++++
 docs/zh/reference/default-theme-sidebar.md | 60 ++++++++++++++++++++++
 2 files changed, 120 insertions(+)

diff --git a/docs/en/reference/default-theme-sidebar.md b/docs/en/reference/default-theme-sidebar.md
index cd44425d..559cd61d 100644
--- a/docs/en/reference/default-theme-sidebar.md
+++ b/docs/en/reference/default-theme-sidebar.md
@@ -184,3 +184,63 @@ export default {
   }
 }
 ```
+
+## Path Prefix
+
+When your documentation structure has deep directories or groups located under the same subdirectory, you can use the `base` option to automatically prepend a path prefix to all nested `items` inside that group. This avoids repeating the same path prefix for every `link`.
+
+The `base` option is supported in both multiple sidebar configurations and nested sidebar groups.
+
+### In Multiple Sidebars
+
+You can define `base` at the root of a sidebar section configuration:
+
+```js {5}
+export default {
+  themeConfig: {
+    sidebar: {
+      '/guide/': {
+        base: '/guide/',
+        items: [
+          // This link is resolved to `/guide/introduction`
+          { text: 'Introduction', link: 'introduction' },
+          // This link is resolved to `/guide/getting-started`
+          { text: 'Getting Started', link: 'getting-started' }
+        ]
+      }
+    }
+  }
+}
+```
+
+### In Nested Groups
+
+You can also use `base` inside nested sidebar groups. It will apply to the immediate children of that group:
+
+```js{6,13}
+export default {
+  themeConfig: {
+    sidebar: [
+      {
+        text: 'Reference',
+        base: '/reference/',
+        items: [
+          // This link is resolved to `/reference/site-config`
+          { text: 'Site Config', link: 'site-config' },
+          {
+            text: 'Default Theme',
+            // Nested base overrides the parent path prefix
+            base: '/reference/default-theme-',
+            items: [
+              // This link is resolved to `/reference/default-theme-nav`
+              { text: 'Nav', link: 'nav' },
+              // This link is resolved to `/reference/default-theme-sidebar`
+              { text: 'Sidebar', link: 'sidebar' }
+            ]
+          }
+        ]
+      }
+    ]
+  }
+}
+```
diff --git a/docs/zh/reference/default-theme-sidebar.md b/docs/zh/reference/default-theme-sidebar.md
index d6cb585c..b98c46e4 100644
--- a/docs/zh/reference/default-theme-sidebar.md
+++ b/docs/zh/reference/default-theme-sidebar.md
@@ -182,3 +182,63 @@ export default {
   }
 }
 ```
+
+## 路径前缀 {#path-prefix}
+
+当文档结构具有较深的目录，或者多个分组位于同一个子目录下时，可以使用 `base` 选项为该分组下的所有嵌套 `items` 拼接的一个路径前缀。
+
+这样可以避免为每个 `link` 重复书写相同的路径。`base` 选项既支持在多侧边栏配置中使用，也支持在嵌套的侧边栏分组中使用。
+
+### 在多侧边栏中使用 {#in-multiple-sidebars}
+
+可以在多侧边栏配置的根部定义 `base`：
+
+```js {5}
+export default {
+  themeConfig: {
+    sidebar: {
+      '/guide/': {
+        base: '/guide/',
+        items: [
+          // 实际解析为 `/guide/introduction`
+          { text: 'Introduction', link: 'introduction' },
+          // 实际解析为 `/guide/getting-started`
+          { text: 'Getting Started', link: 'getting-started' }
+        ]
+      }
+    }
+  }
+}
+```
+
+### 在嵌套分组中使用 {#in-nested-groups}
+
+也可以在嵌套的侧边栏分组内部使用 `base`，它将作用于该分组的直接子项：
+
+```js {6,13}
+export default {
+  themeConfig: {
+    sidebar: [
+      {
+        text: 'Reference',
+        base: '/reference/',
+        items: [
+          // 实际解析为 `/reference/site-config`
+          { text: 'Site Config', link: 'site-config' },
+          {
+            text: 'Default Theme',
+            // 嵌套的 base 会覆盖父级的路径前缀
+            base: '/reference/default-theme-',
+            items: [
+              // 实际解析为 `/reference/default-theme-nav`
+              { text: 'Nav', link: 'nav' },
+              // 实际解析为 `/reference/default-theme-sidebar`
+              { text: 'Sidebar', link: 'sidebar' }
+            ]
+          }
+        ]
+      }
+    ]
+  }
+}
+```