react-docs-ui 0.1.3 → 0.1.7

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
Files changed (14) hide show
  1. package/LICENSE +21 -0
  2. package/README.md +77 -88
  3. package/dist/config/site.en.yaml +39 -18
  4. package/dist/config/site.yaml +39 -10
  5. package/dist/docs/en/guide/configuration.md +149 -122
  6. package/dist/docs/en/guide/quick-start.md +107 -108
  7. package/dist/docs/zh-cn/guide/configuration.md +207 -122
  8. package/dist/docs/zh-cn/guide/quick-start.md +107 -108
  9. package/dist/react-docs-ui.css +1 -1
  10. package/dist/react-docs-ui.es.js +6023 -5748
  11. package/dist/react-docs-ui.es.js.map +1 -1
  12. package/dist/react-docs-ui.umd.js +123 -73
  13. package/dist/react-docs-ui.umd.js.map +1 -1
  14. package/package.json +96 -83
package/LICENSE ADDED
@@ -0,0 +1,21 @@
1
+ MIT License
2
+
3
+ Copyright (c) 2025 shenjianZ
4
+
5
+ Permission is hereby granted, free of charge, to any person obtaining a copy
6
+ of this software and associated documentation files (the "Software"), to deal
7
+ in the Software without restriction, including without limitation the rights
8
+ to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
9
+ copies of the Software, and to permit persons to whom the Software is
10
+ furnished to do so, subject to the following conditions:
11
+
12
+ The above copyright notice and this permission notice shall be included in all
13
+ copies or substantial portions of the Software.
14
+
15
+ THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
16
+ IMPLIED, INCLUDING BUT NOTT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
17
+ FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
18
+ AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
19
+ LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
20
+ OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
21
+ SOFTWARE.
package/README.md CHANGED
@@ -1,88 +1,77 @@
1
- # React Docs UI (Vite)
2
-
3
- This package can be used as a library, similar to `vue-docs-ui`.
4
-
5
- ## Install
6
-
7
- ```bash
8
- npm install @react-docs-ui-vite/core
9
- ```
10
-
11
- ## Usage
12
-
13
- ```tsx
14
- import "@react-docs-ui-vite/core/dist/react-docs-ui.css"
15
- import { DocsLayout, HeaderNav, SidebarNav, TableOfContents } from "@react-docs-ui-vite/core"
16
- ```
17
-
18
- See `public/config/site.yaml` and `public/docs` in this repo for an example content structure.
19
-
20
- # React + TypeScript + Vite
21
-
22
- This template provides a minimal setup to get React working in Vite with HMR and some ESLint rules.
23
-
24
- Currently, two official plugins are available:
25
-
26
- - [@vitejs/plugin-react](https://github.com/vitejs/vite-plugin-react/blob/main/packages/plugin-react) uses [Babel](https://babeljs.io/) for Fast Refresh
27
- - [@vitejs/plugin-react-swc](https://github.com/vitejs/vite-plugin-react/blob/main/packages/plugin-react-swc) uses [SWC](https://swc.rs/) for Fast Refresh
28
-
29
- ## Expanding the ESLint configuration
30
-
31
- If you are developing a production application, we recommend updating the configuration to enable type-aware lint rules:
32
-
33
- ```js
34
- export default tseslint.config([
35
- globalIgnores(['dist']),
36
- {
37
- files: ['**/*.{ts,tsx}'],
38
- extends: [
39
- // Other configs...
40
-
41
- // Remove tseslint.configs.recommended and replace with this
42
- ...tseslint.configs.recommendedTypeChecked,
43
- // Alternatively, use this for stricter rules
44
- ...tseslint.configs.strictTypeChecked,
45
- // Optionally, add this for stylistic rules
46
- ...tseslint.configs.stylisticTypeChecked,
47
-
48
- // Other configs...
49
- ],
50
- languageOptions: {
51
- parserOptions: {
52
- project: ['./tsconfig.node.json', './tsconfig.app.json'],
53
- tsconfigRootDir: import.meta.dirname,
54
- },
55
- // other options...
56
- },
57
- },
58
- ])
59
- ```
60
-
61
- You can also install [eslint-plugin-react-x](https://github.com/Rel1cx/eslint-react/tree/main/packages/plugins/eslint-plugin-react-x) and [eslint-plugin-react-dom](https://github.com/Rel1cx/eslint-react/tree/main/packages/plugins/eslint-plugin-react-dom) for React-specific lint rules:
62
-
63
- ```js
64
- // eslint.config.js
65
- import reactX from 'eslint-plugin-react-x'
66
- import reactDom from 'eslint-plugin-react-dom'
67
-
68
- export default tseslint.config([
69
- globalIgnores(['dist']),
70
- {
71
- files: ['**/*.{ts,tsx}'],
72
- extends: [
73
- // Other configs...
74
- // Enable lint rules for React
75
- reactX.configs['recommended-typescript'],
76
- // Enable lint rules for React DOM
77
- reactDom.configs.recommended,
78
- ],
79
- languageOptions: {
80
- parserOptions: {
81
- project: ['./tsconfig.node.json', './tsconfig.app.json'],
82
- tsconfigRootDir: import.meta.dirname,
83
- },
84
- // other options...
85
- },
86
- },
87
- ])
88
- ```
1
+ English | [简体中文](README-zh.md)
2
+
3
+ ## react-docs-ui
4
+
5
+ React documentation site UI components. Ship a modern docs site with a small set of composable primitives and a ready-to-use app shell.
6
+
7
+ ### Install
8
+ ```bash
9
+ npm install react-docs-ui
10
+ ```
11
+
12
+ ### Quick usage
13
+ Minimal layout:
14
+ ```tsx
15
+ import 'react-docs-ui/dist/react-docs-ui.css'
16
+ import { DocsLayout, HeaderNav, SidebarNav, TableOfContents, MdxContent } from 'react-docs-ui'
17
+
18
+ function Page() {
19
+ const source = `# Hello\n\nSome markdown...`
20
+ return (
21
+ <DocsLayout lang="en" config={{
22
+ site: { logo: '/logo.svg', title: 'My Docs', description: 'Awesome docs' },
23
+ navbar: { items: [] },
24
+ sidebar: { collections: {} },
25
+ }}>
26
+ <MdxContent source={source} />
27
+ </DocsLayout>
28
+ )
29
+ }
30
+ ```
31
+
32
+ Or use the full app router (reads `public/config/site(.lang).yaml` and `public/docs/<lang>/**/*.md` at runtime):
33
+ ```tsx
34
+ import 'react-docs-ui/dist/react-docs-ui.css'
35
+ import { DocsApp } from 'react-docs-ui'
36
+
37
+ export default function App() {
38
+ return <DocsApp />
39
+ }
40
+ ```
41
+
42
+ ### Exports
43
+ - Layout: `DocsLayout`
44
+ - App shell: `DocsApp`
45
+ - Navigation: `HeaderNav`, `SidebarNav`, `TableOfContents`
46
+ - Theming: `ThemeProvider`, `ModeToggle`, `LanguageSwitcher`
47
+ - Markdown: `MdxContent`
48
+ - Primitives: `ScrollArea`, `Tooltip`, `Dialog`, `DropdownMenu`, `Command`, `ContextMenu`, `buttonVariants`
49
+ - Utils: `cn`, `getConfig`, types `SiteConfig`
50
+
51
+ ### Configuration file (`public/config/site.yaml`)
52
+ See the `create-react-docs-ui` README for a full example. Basic shape:
53
+ ```yaml
54
+ site:
55
+ logo: /logo.svg
56
+ title: My Docs
57
+ description: Awesome docs
58
+ navbar:
59
+ items:
60
+ - title: GitHub
61
+ link: https://github.com/shenjianZ/react-docs-ui
62
+ external: true
63
+ sidebar:
64
+ collections: {}
65
+ ```
66
+
67
+ ### Documentation content
68
+ - Place markdown under `public/docs/<lang>/**/*.md`
69
+ - Route path maps to file path after the language segment
70
+ - Optional frontmatter is supported by a simple parser
71
+
72
+ ### Requirements
73
+ - React 18+
74
+ - Works with Vite; CSS file must be imported
75
+
76
+ ### License
77
+ MIT
package/dist/config/site.en.yaml CHANGED
@@ -1,7 +1,7 @@
1
1
  # Website Configuration
2
2
  site:
3
- title: "Vue Docs UI Example"
4
- description: "Example documentation website built with Vue Docs UI"
3
+ title: "React Docs UI Example"
4
+ description: "Example documentation website built with React Docs UI"
5
5
  # Logo formats supported:
6
6
  # 1. emoji: "🤖"
7
7
  # 2. image URL: "https://example.com/logo.png"
@@ -10,7 +10,7 @@ site:
10
10
  logo:
11
11
  light: "/images/favicon.svg"
12
12
  dark: "/images/favicon-dark.svg"
13
- author: "Vue Docs UI Team"
13
+ author: "React Docs UI Team"
14
14
 
15
15
  # Navigation Bar Configuration
16
16
  navbar:
@@ -25,7 +25,7 @@ navbar:
25
25
  link: "/guide"
26
26
  actions:
27
27
  - type: "github"
28
- link: "https://github.com/shenjianZ/vue-docs-ui"
28
+ link: "https://github.com/shenjianZ/React-docs-ui"
29
29
  enabled: true
30
30
 
31
31
  # Sidebar Navigation Configuration
@@ -73,25 +73,46 @@ toc:
73
73
  # Footer Configuration
74
74
  footer:
75
75
  enabled: true
76
- copyright: "© 2024 Vue Docs UI. All rights reserved."
76
+ copyright: "© 2024 React Docs UI. All rights reserved."
77
77
  repository:
78
- url: "https://github.com/your_github_id/your_repo_name"
78
+ url: "https://github.com/shenjianZ/React-docs-ui"
79
79
  branch: "master"
80
- lastUpdated: "2024-12-19"
81
- links:
82
- - title: "Documentation"
83
- link: "/guide/introduction"
84
- - title: "GitHub"
85
- link: "https://github.com/your_github_id/your_repo_name"
86
- external: true
87
- - title: "License"
88
- link: "/license"
80
+ lastUpdated: "2025-08-14"
81
+ version: "v0.1.7"
82
+ groups:
83
+ - title: "Community"
84
+ items:
85
+ - title: "Discussions"
86
+ link: "https://github.com/shenjianZ/React-docs-ui/discussions"
87
+ external: true
88
+ - title: "Issues"
89
+ link: "https://github.com/shenjianZ/React-docs-ui/issues"
90
+ external: true
91
+ - title: "Contributing"
92
+ link: "https://github.com/shenjianZ/React-docs-ui/blob/master/CONTRIBUTING.md"
93
+ external: true
94
+ - title: "Releases"
95
+ link: "https://github.com/shenjianZ/React-docs-ui/releases"
96
+ external: true
97
+ - title: "Help & Support"
98
+ items:
99
+ - title: "Examples"
100
+ link: "/guide/quick-start"
101
+ - title: "Source Code"
102
+ link: "https://github.com/shenjianZ/React-docs-ui"
103
+ external: true
104
+ - title: "License"
105
+ link: "https://github.com/shenjianZ/React-docs-ui/blob/master/LICENSE"
106
+ external: true
107
+ - title: "Back to Top"
108
+ link: "#"
109
+ action: "scrollTop"
89
110
  social:
90
111
  - name: "email"
91
112
  url: "mailto:contact@example.com"
92
113
  icon: "mail"
93
114
  - name: "github"
94
- url: "https://github.com/your_github_id"
115
+ link: "https://github.com/shenjianZ/React-docs-ui"
95
116
  icon: "github"
96
117
  # - name: "youtube"
97
118
  # url: "https://youtube.com/@yourhandle"
@@ -130,8 +151,8 @@ footer:
130
151
  # PWA Configuration
131
152
  pwa:
132
153
  enabled: false
133
- name: "Vue Docs UI"
134
- shortName: "VueDocsUI"
154
+ name: "React Docs UI"
155
+ shortName: "ReactDocsUI"
135
156
  description: "Beautiful documentation websites made simple"
136
157
  themeColor: "#ffffff"
137
158
  backgroundColor: "#ffffff"
package/dist/config/site.yaml CHANGED
@@ -1,7 +1,7 @@
1
1
  # 网站基本配置
2
2
  site:
3
- title: "Vue Docs UI 示例项目"
4
- description: "基于 Vue Docs UI 构建的文档网站示例"
3
+ title: "React Docs UI 示例项目"
4
+ description: "基于 React Docs UI 构建的文档网站示例"
5
5
  # logo支持以下格式：
6
6
  # 1. emoji: "🤖"
7
7
  # 2. 图片URL: "https://example.com/logo.png"
@@ -10,7 +10,7 @@ site:
10
10
  logo:
11
11
  light: "/images/favicon.svg"
12
12
  dark: "/images/favicon-dark.svg"
13
- author: "Vue Docs UI Team"
13
+ author: "React Docs UI Team"
14
14
 
15
15
  # 顶部导航配置
16
16
  navbar:
@@ -25,7 +25,7 @@ navbar:
25
25
  link: "/guide"
26
26
  actions:
27
27
  - type: "github"
28
- link: "https://github.com/shenjianZ/vue-docs-ui"
28
+ link: "https://github.com/shenjianZ/React-docs-ui"
29
29
  enabled: true
30
30
 
31
31
  # 侧边栏导航配置
@@ -73,16 +73,45 @@ toc:
73
73
  # Footer Configuration
74
74
  footer:
75
75
  enabled: true
76
- copyright: "© 2024 Vue Docs UI. All rights reserved."
76
+ copyright: "© 2025 React Docs UI. All rights reserved."
77
77
  repository:
78
- url: "https://github.com/your_github_id/your_repo_name"
78
+ url: "https://github.com/shenjianZ/React-docs-ui"
79
79
  branch: "master"
80
- lastUpdated: "2024-12-19"
80
+ lastUpdated: "2025-08-14"
81
+ version: "v0.1.7"
82
+ groups:
83
+ - title: "社区"
84
+ items:
85
+ - title: "讨论区"
86
+ link: "https://github.com/shenjianZ/React-docs-ui/discussions"
87
+ external: true
88
+ - title: "问题反馈"
89
+ link: "https://github.com/shenjianZ/React-docs-ui/issues"
90
+ external: true
91
+ - title: "贡献指南"
92
+ link: "https://github.com/shenjianZ/React-docs-ui/blob/master/CONTRIBUTING.md"
93
+ external: true
94
+ - title: "版本发布"
95
+ link: "https://github.com/shenjianZ/React-docs-ui/releases"
96
+ external: true
97
+ - title: "帮助支持"
98
+ items:
99
+ - title: "示例"
100
+ link: "/guide/quick-start"
101
+ - title: "源代码"
102
+ link: "https://github.com/shenjianZ/React-docs-ui"
103
+ external: true
104
+ - title: "开源许可"
105
+ link: "https://github.com/shenjianZ/React-docs-ui/blob/master/LICENSE"
106
+ external: true
107
+ - title: "回到顶部"
108
+ link: "#"
109
+ action: "scrollTop"
81
110
  links:
82
111
  - title: "Documentation"
83
112
  link: "/guide/introduction"
84
113
  - title: "GitHub"
85
- link: "https://github.com/your_github_id/your_repo_name"
114
+ link: "https://github.com/shenjianZ/React-docs-ui"
86
115
  external: true
87
116
  - title: "License"
88
117
  link: "/license"
@@ -130,8 +159,8 @@ footer:
130
159
  # PWA Configuration
131
160
  pwa:
132
161
  enabled: true
133
- name: "Vue Docs UI"
134
- shortName: "VueDocsUI"
162
+ name: "React Docs UI"
163
+ shortName: "ReactDocsUI"
135
164
  description: "Beautiful documentation websites made simple"
136
165
  themeColor: "#ffffff"
137
166
  backgroundColor: "#ffffff"
package/dist/docs/en/guide/configuration.md CHANGED
@@ -1,122 +1,149 @@
1
- # Configuration File (`site.yaml`) Explained
2
-
3
- The core of `react-docs-ui` is its **configuration-driven** philosophy. You can define the entire look and behavior of your website almost exclusively through the `public/config/site.yaml` file. This document explains each configuration option in detail.
4
-
5
- ## Top-Level Configuration Overview
6
-
7
- | Top-Level Field | Description |
8
- | :--- | :--- |
9
- | `site` | Global site information, such as title, description, and logo. |
10
- | `navbar` | Configures the top navigation bar of the website. |
11
- | `sidebar` | Configures the navigation menu in the website's sidebar. |
12
- | `theme` | Configures the website's theme, such as colors and light/dark mode. |
13
- | `footer` | Configures the footer information at the bottom of the website. |
14
- | `toc` | Configures the Table of Contents on the right side of article pages. |
15
-
16
- ---
17
-
18
- ## `site`
19
-
20
- Basic metadata configuration for the website.
21
-
22
- | Field | Description | Example |
23
- | :--- | :--- | :--- |
24
- | `title` | The website title, displayed in the browser tab. | `"React Docs UI"` |
25
- | `description` | The website description, used for Search Engine Optimization (SEO). | `"A React documentation website builder"` |
26
- | `logo` | The website logo, displayed in the top-left corner of the navbar. | `"📚"` or `"/images/logo.png"` or an object with `light` and `dark` image paths |
27
- | `author` | The author of the website. | `"React Docs UI Team"` |
28
-
29
- **Logo Format Guide:**
30
- 1. **Emoji**: Use an emoji directly, like `"🚀"`.
31
- 2. **Local Image**: A path to an image in the `public` directory, like `"/images/logo.png"`.
32
- 3. **Light/Dark Mode Images**: An object with `light` and `dark` keys, pointing to different image paths for each theme.
33
-
34
- ---
35
-
36
- ## `navbar`
37
-
38
- Top navigation bar configuration.
39
-
40
- | Field | Description |
41
- | :--- | :--- |
42
- | `items` | An array of navigation items that defines all the links displayed in the navbar. |
43
- | `actions` | (Optional) Action buttons on the right side of the navbar, such as a GitHub link. |
44
-
45
- ### `navbar.items`
46
-
47
- | Field | Description | Example |
48
- | :--- | :--- | :--- |
49
- | `title` | The display text for the navigation item. | `"Guide"` |
50
- | `link` | The link address. Internal links start with `/`. | `"/guide/introduction"` |
51
- | `external` | (Optional) If `true`, it's an external link that will open in a new tab. | `true` |
52
-
53
- ---
54
-
55
- ## `sidebar`
56
-
57
- Sidebar navigation configuration, which is the core of the documentation structure. It uses `collections` to organize different sections of content.
58
-
59
- | Field | Description |
60
- | :--- | :--- |
61
- | `collections` | An object where keys are collection names (usually corresponding to top-level routes like `guide`), and values are the sidebar configurations for that collection. |
62
-
63
- ### `sidebar.collections.<name>.sections`
64
-
65
- Each collection contains a `sections` array, where each `section` represents a collapsible menu group.
66
-
67
- | Field | Description | Example |
68
- | :--- | :--- | :--- |
69
- | `title` | The title of the section. | `"Getting Started"` |
70
- | `path` | The base path for the section. When a user visits a URL starting with this path, this section will automatically expand and be highlighted. | `"/guide"` |
71
- | `children` | An array of child links under this section. | |
72
-
73
- ### `sidebar.collections.<name>.sections.children`
74
-
75
- | Field | Description | Example |
76
- | :--- | :--- | :--- |
77
- | `title` | The display text for the child link. | `"Introduction"` |
78
- | `path` | The full path to the child link, pointing to a specific Markdown page. | `"/guide/introduction"` |
79
-
80
- ---
81
-
82
- ## `theme`
83
-
84
- Theme and appearance configuration.
85
-
86
- | Field | Description | Options | Default |
87
- | :--- | :--- | :--- | :--- |
88
- | `defaultMode` | The default theme mode for the website. | `'light'`, `'dark'`, `'system'` | `'system'` |
89
- | `allowToggle` | Whether to allow users to switch the theme. | `true`, `false` | `true` |
90
-
91
- ---
92
-
93
- ## `footer`
94
-
95
- Footer configuration.
96
-
97
- | Field | Description | Example |
98
- | :--- | :--- | :--- |
99
- | `copyright` | Copyright information. `{year}` will be replaced with the current year. | `"Copyright © {year} My Company"` |
100
- | `repository` | (Optional) Repository information, used for displaying links like "Edit this page on GitHub". | |
101
- | `links` | (Optional) Additional link columns displayed in the footer. | |
102
- | `social` | (Optional) Social media icon links displayed in the footer. | |
103
-
104
- ### `footer.repository`
105
-
106
- | Field | Description | Example |
107
- | :--- | :--- | :--- |
108
- | `url` | The URL of the repository. | `"https://github.com/user/repo"` |
109
- | `branch` | The Git branch where the documentation is located. | `"main"` |
110
- | `dir` | The root directory of the documentation files in the repository. | `"docs/src"` |
111
-
112
- ---
113
-
114
- ## `toc` (Table of Contents)
115
-
116
- Configuration for the table of contents on the right side of article pages.
117
-
118
- | Field | Description | Example |
119
- | :--- | :--- | :--- |
120
- | `enabled` | Whether to enable the page table of contents feature. | `true` |
121
- | `maxLevel` | The maximum heading level (h1-h6) to display in the TOC. | `3` |
122
- | `title` | The title of the TOC component. | `"On this page"` |
1
+ # Configuration File (`site.yaml`) Explained
2
+
3
+ The project is configuration-driven. Most behavior is defined in `public/config/site.yaml`. This page documents every field using concise tables.
4
+
5
+ ## Top-level keys
6
+ | Key | Purpose |
7
+ | :-- | :-- |
8
+ | `site` | Global metadata like title, description, logo, author |
9
+ | `navbar` | Top navigation bar (logo/title toggles, items, actions) |
10
+ | `sidebar` | Left navigation tree (collections/sections/children) |
11
+ | `theme` | Theme options (default mode, toggle) |
12
+ | `toc` | Article table of contents (enabled, levels, title) |
13
+ | `footer` | Footer links, socials, repository meta |
14
+ | `pwa` | Progressive Web App settings (reserved/optional) |
15
+
16
+ ---
17
+
18
+ ## `site`
19
+ | Field | Type | Description | Example |
20
+ | :-- | :-- | :-- | :-- |
21
+ | `title` | string | Site title | `"React Docs UI Example"` |
22
+ | `description` | string | Short site description (SEO) | `"Beautiful docs made simple"` |
23
+ | `logo` | string or object | Logo to display. String can be emoji or image path. Object allows light/dark images. | `"📚"`, `"/images/logo.png"`, or `{ light: "/images/favicon.svg", dark: "/images/favicon-dark.svg" }` |
24
+ | `author` | string | Site author/organization | `"React Docs UI Team"` |
25
+
26
+ Logo formats supported:
27
+ - Emoji: `"🚀"`
28
+ - URL or public path: `"/images/logo.png"`
29
+ - Light/Dark object: `{ light, dark }`
30
+
31
+ ---
32
+
33
+ ## `navbar`
34
+ | Field | Type | Description |
35
+ | :-- | :-- | :-- |
36
+ | `showLogo` | boolean | Show logo at top-left |
37
+ | `showTitle` | boolean | Show site title in navbar |
38
+ | `showLanguageSwitcher` | boolean | Show language switcher |
39
+ | `items` | array<Item> | Primary navigation links |
40
+ | `actions` | array<Action> | Right-side action buttons (e.g. GitHub) |
41
+
42
+ Item
43
+ | Field | Type | Description | Example |
44
+ | :-- | :-- | :-- | :-- |
45
+ | `title` | string | Link text | `"Guide"` |
46
+ | `link` | string | Path or URL. Internal paths start with `/`. | `"/guide"` |
47
+ | `external` | boolean (optional) | Open in new tab if true |
48
+ | `visible` | boolean (optional) | Conditionally hide/show |
49
+
50
+ Action
51
+ | Field | Type | Description | Example |
52
+ | :-- | :-- | :-- | :-- |
53
+ | `type` | `"github"` or `"custom"` (optional) | Predefined or custom action | `"github"` |
54
+ | `title` | string (optional) | Button text when `type` is `custom` |
55
+ | `link` | string | Destination URL |
56
+ | `icon` | string (optional) | Icon name for custom action |
57
+ | `enabled` | boolean (optional) | Toggle the action |
58
+
59
+ ---
60
+
61
+ ## `sidebar`
62
+ | Field | Type | Description |
63
+ | :-- | :-- | :-- |
64
+ | `enabled` | boolean (optional) | Global toggle for sidebar |
65
+ | `collections` | record<string, Collection> | Map of top-level sections (e.g. `guide`) |
66
+ | `sections` | Section[] (legacy, optional) | Backward-compatible single-tree definition |
67
+
68
+ Collection
69
+ | Field | Type | Description |
70
+ | :-- | :-- | :-- |
71
+ | `sections` | Section[] | Grouped side-nav sections |
72
+
73
+ Section
74
+ | Field | Type | Description | Example |
75
+ | :-- | :-- | :-- | :-- |
76
+ | `title` | string | Section title | `"Getting Started"` |
77
+ | `path` | string | Base path that expands/highlights this section | `"/guide"` |
78
+ | `children` | Child[] (optional) | Leaf links under the section |
79
+
80
+ Child
81
+ | Field | Type | Description | Example |
82
+ | :-- | :-- | :-- | :-- |
83
+ | `title` | string | Link text | `"Introduction"` |
84
+ | `path` | string | Full page path | `"/guide/introduction"` |
85
+
86
+ ---
87
+
88
+ ## `theme`
89
+ | Field | Type | Description | Options | Default |
90
+ | :-- | :-- | :-- | :-- | :-- |
91
+ | `defaultMode` | string | Default color mode | `light`, `dark`, `auto` | `auto` |
92
+ | `allowToggle` | boolean | Allow user theme switching | `true`/`false` | `true` |
93
+
94
+ ---
95
+
96
+ ## `toc`
97
+ | Field | Type | Description | Example |
98
+ | :-- | :-- | :-- | :-- |
99
+ | `enabled` | boolean | Enable page table of contents | `true` |
100
+ | `maxLevel` | number (1-6) | Max heading depth to show | `3` |
101
+ | `title` | string | TOC panel title | `"On This Page"` |
102
+
103
+ Note: Per-page TOC visibility/anchors are also affected by page frontmatter.
104
+
105
+ ---
106
+
107
+ ## `footer`
108
+ | Field | Type | Description |
109
+ | :-- | :-- | :-- |
110
+ | `enabled` | boolean | Show footer |
111
+ | `copyright` | string | Copyright text |
112
+ | `repository` | Repository (optional) | Repo info used for links like “Edit this page” |
113
+ | `lastUpdated` | string (optional) | Site/content last update date |
114
+ | `links` | Link[] (optional) | Footer link columns |
115
+ | `social` | Social[] (optional) | Social icon links |
116
+
117
+ Repository
118
+ | Field | Type | Description | Example |
119
+ | :-- | :-- | :-- | :-- |
120
+ | `url` | string | Repository URL | `"https://github.com/user/repo"` |
121
+ | `branch` | string | Docs branch | `"main"` |
122
+
123
+ Link
124
+ | Field | Type | Description |
125
+ | :-- | :-- | :-- |
126
+ | `title` | string | Link title |
127
+ | `link` | string | Path or URL |
128
+ | `external` | boolean (optional) | Open in new tab |
129
+
130
+ Social
131
+ | Field | Type | Description |
132
+ | :-- | :-- | :-- |
133
+ | `name` | string | Provider key (e.g. `github`, `twitter`, `bilibili`) |
134
+ | `url` | string | Profile or link URL |
135
+ | `icon` | string | Icon name |
136
+
137
+ ---
138
+
139
+ ## `pwa` (optional)
140
+ | Field | Type | Description |
141
+ | :-- | :-- | :-- |
142
+ | `enabled` | boolean | Enable PWA features (reserved) |
143
+ | `name` | string | App name |
144
+ | `shortName` | string | Short app name |
145
+ | `description` | string | App description |
146
+ | `themeColor` | string | Theme color |
147
+ | `backgroundColor` | string | Background color |
148
+
149
+ ---