create-react-docs-ui 0.1.3 → 0.1.5
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.
- package/README.md +85 -82
- package/package.json +16 -2
- package/template/index.html +3 -2
- package/template/package.json +6 -1
- package/template/public/config/site.en.yaml +7 -7
- package/template/public/config/site.yaml +7 -7
- package/template/public/docs/en/guide/configuration.md +149 -122
- package/template/public/docs/en/guide/quick-start.md +107 -108
- package/template/public/docs/zh-cn/guide/configuration.md +150 -122
- package/template/public/docs/zh-cn/guide/quick-start.md +107 -108
- package/template/src/react-docs-ui.d.ts +1 -0
|
@@ -1,109 +1,108 @@
|
|
|
1
|
-
# Quick Start
|
|
2
|
-
|
|
3
|
-
This guide will walk you through creating, configuring, and running your own React documentation website from scratch in 5 minutes.
|
|
4
|
-
|
|
5
|
-
## 1. Create the Project
|
|
6
|
-
|
|
7
|
-
Using the official scaffolding tool is the most efficient way. Open your terminal and run the following command:
|
|
8
|
-
|
|
9
|
-
```bash
|
|
10
|
-
# This creates a project named "my-awesome-docs"
|
|
11
|
-
npx create-react-docs-ui@latest my-awesome-docs
|
|
12
|
-
```
|
|
13
|
-
|
|
14
|
-
Next, enter the project directory and install the dependencies:
|
|
15
|
-
|
|
16
|
-
```bash
|
|
17
|
-
cd my-awesome-docs
|
|
18
|
-
npm install
|
|
19
|
-
```
|
|
20
|
-
|
|
21
|
-
## 2. Organize Your Documents
|
|
22
|
-
|
|
23
|
-
All your documentation content is stored as Markdown files in the `public/docs/` directory.
|
|
24
|
-
|
|
25
|
-
- Open the `public/docs/en/` directory.
|
|
26
|
-
- You can modify the existing `index.md` and files under the `guide` directory, or create new `.md` files.
|
|
27
|
-
|
|
28
|
-
For example, let's create a new page. Create a new file named `about.md` in `public/docs/en/`:
|
|
29
|
-
|
|
30
|
-
```markdown
|
|
31
|
-
---
|
|
32
|
-
title: About Us
|
|
33
|
-
description: This is a page about our team.
|
|
34
|
-
---
|
|
35
|
-
|
|
36
|
-
# About Us
|
|
37
|
-
|
|
38
|
-
We love open source and creation!
|
|
39
|
-
```
|
|
40
|
-
|
|
41
|
-
|
|
42
|
-
|
|
43
|
-
|
|
44
|
-
|
|
45
|
-
|
|
46
|
-
|
|
47
|
-
|
|
48
|
-
|
|
49
|
-
|
|
50
|
-
|
|
51
|
-
|
|
52
|
-
|
|
53
|
-
|
|
54
|
-
|
|
55
|
-
|
|
56
|
-
|
|
57
|
-
|
|
58
|
-
|
|
59
|
-
|
|
60
|
-
|
|
61
|
-
|
|
62
|
-
|
|
63
|
-
|
|
64
|
-
|
|
65
|
-
|
|
66
|
-
|
|
67
|
-
|
|
68
|
-
|
|
69
|
-
|
|
70
|
-
|
|
71
|
-
|
|
72
|
-
|
|
73
|
-
|
|
74
|
-
|
|
75
|
-
|
|
76
|
-
|
|
77
|
-
|
|
78
|
-
|
|
79
|
-
|
|
80
|
-
|
|
81
|
-
|
|
82
|
-
|
|
83
|
-
|
|
84
|
-
|
|
85
|
-
|
|
86
|
-
|
|
87
|
-
|
|
88
|
-
|
|
89
|
-
|
|
90
|
-
|
|
91
|
-
|
|
92
|
-
|
|
93
|
-
|
|
94
|
-
|
|
95
|
-
|
|
96
|
-
|
|
97
|
-
|
|
98
|
-
|
|
99
|
-
|
|
100
|
-
|
|
101
|
-
|
|
102
|
-
|
|
103
|
-
|
|
104
|
-
|
|
105
|
-
|
|
106
|
-
|
|
107
|
-
|
|
108
|
-
|
|
1
|
+
# Quick Start
|
|
2
|
+
|
|
3
|
+
This guide will walk you through creating, configuring, and running your own React documentation website from scratch in 5 minutes.
|
|
4
|
+
|
|
5
|
+
## 1. Create the Project
|
|
6
|
+
|
|
7
|
+
Using the official scaffolding tool is the most efficient way. Open your terminal and run the following command:
|
|
8
|
+
|
|
9
|
+
```bash
|
|
10
|
+
# This creates a project named "my-awesome-docs"
|
|
11
|
+
npx create-react-docs-ui@latest my-awesome-docs
|
|
12
|
+
```
|
|
13
|
+
|
|
14
|
+
Next, enter the project directory and install the dependencies:
|
|
15
|
+
|
|
16
|
+
```bash
|
|
17
|
+
cd my-awesome-docs
|
|
18
|
+
npm install
|
|
19
|
+
```
|
|
20
|
+
|
|
21
|
+
## 2. Organize Your Documents
|
|
22
|
+
|
|
23
|
+
All your documentation content is stored as Markdown files in the `public/docs/` directory.
|
|
24
|
+
|
|
25
|
+
- Open the `public/docs/en/` directory.
|
|
26
|
+
- You can modify the existing `index.md` and files under the `guide` directory, or create new `.md` files.
|
|
27
|
+
|
|
28
|
+
For example, let's create a new page. Create a new file named `about.md` in `public/docs/en/`:
|
|
29
|
+
|
|
30
|
+
```markdown
|
|
31
|
+
---
|
|
32
|
+
title: About Us
|
|
33
|
+
description: This is a page about our team.
|
|
34
|
+
---
|
|
35
|
+
|
|
36
|
+
# About Us
|
|
37
|
+
|
|
38
|
+
We love open source and creation!
|
|
39
|
+
```
|
|
40
|
+
|
|
41
|
+
|
|
42
|
+
## 3. Configure the Website
|
|
43
|
+
|
|
44
|
+
Now, let's display the newly created page by modifying the configuration file.
|
|
45
|
+
|
|
46
|
+
Open the core configuration file `public/config/site.yaml`.
|
|
47
|
+
|
|
48
|
+
### a. Modify Site Information
|
|
49
|
+
|
|
50
|
+
Update the `site` section to give your website a new title and logo.
|
|
51
|
+
|
|
52
|
+
```yaml
|
|
53
|
+
site:
|
|
54
|
+
title: "My Awesome Docs"
|
|
55
|
+
description: "A website built with React Docs UI"
|
|
56
|
+
logo: "🚀" # You can use an emoji or an image path
|
|
57
|
+
```
|
|
58
|
+
|
|
59
|
+
### b. Add to the Navbar
|
|
60
|
+
|
|
61
|
+
In the `navbar.items` array, add a link for the "About" page. Remember to update the links for the English version.
|
|
62
|
+
|
|
63
|
+
```yaml
|
|
64
|
+
navbar:
|
|
65
|
+
items:
|
|
66
|
+
- title: "Home"
|
|
67
|
+
link: "/en/"
|
|
68
|
+
- title: "Guide"
|
|
69
|
+
link: "/en/guide/introduction"
|
|
70
|
+
- title: "About" # New
|
|
71
|
+
link: "/en/about" # New
|
|
72
|
+
```
|
|
73
|
+
|
|
74
|
+
### c. Add to the Sidebar
|
|
75
|
+
|
|
76
|
+
To make the "About" page visible in the sidebar, we'll add a new entry in `sidebar.collections.guide.sections`. Make sure to use English paths.
|
|
77
|
+
|
|
78
|
+
```yaml
|
|
79
|
+
sidebar:
|
|
80
|
+
collections:
|
|
81
|
+
guide:
|
|
82
|
+
sections:
|
|
83
|
+
- title: "Getting Started"
|
|
84
|
+
path: "/en/guide"
|
|
85
|
+
children:
|
|
86
|
+
- title: "Introduction"
|
|
87
|
+
path: "/en/guide/introduction"
|
|
88
|
+
- title: "Installation"
|
|
89
|
+
path: "/en/guide/installation"
|
|
90
|
+
- title: "Quick Start"
|
|
91
|
+
path: "/en/guide/quick-start"
|
|
92
|
+
# You can create a new section for the "About" page
|
|
93
|
+
- title: "About Us"
|
|
94
|
+
path: "/en/about"
|
|
95
|
+
children:
|
|
96
|
+
- title: "About"
|
|
97
|
+
path: "/en/about"
|
|
98
|
+
```
|
|
99
|
+
|
|
100
|
+
## 4. Launch the Website
|
|
101
|
+
|
|
102
|
+
Save all your changes and run the following command in your terminal:
|
|
103
|
+
|
|
104
|
+
```bash
|
|
105
|
+
npm run dev
|
|
106
|
+
```
|
|
107
|
+
|
|
109
108
|
Your website should now be running at `http://localhost:5173`. Visit it, and you will see the updated title, logo, and the new "About" link in the navbar and sidebar. Congratulations, you have successfully mastered the basic workflow of React Docs UI!
|
|
@@ -1,122 +1,150 @@
|
|
|
1
|
-
#
|
|
2
|
-
|
|
3
|
-
|
|
4
|
-
|
|
5
|
-
##
|
|
6
|
-
|
|
7
|
-
|
|
|
8
|
-
|
|
|
9
|
-
| `
|
|
10
|
-
| `
|
|
11
|
-
| `
|
|
12
|
-
| `
|
|
13
|
-
| `footer` |
|
|
14
|
-
| `
|
|
15
|
-
|
|
16
|
-
---
|
|
17
|
-
|
|
18
|
-
## `site`
|
|
19
|
-
|
|
20
|
-
|
|
21
|
-
|
|
22
|
-
|
|
|
23
|
-
|
|
|
24
|
-
| `
|
|
25
|
-
|
|
26
|
-
|
|
27
|
-
|
|
28
|
-
|
|
29
|
-
|
|
30
|
-
|
|
31
|
-
|
|
32
|
-
|
|
33
|
-
|
|
34
|
-
|
|
35
|
-
|
|
36
|
-
|
|
37
|
-
|
|
38
|
-
|
|
39
|
-
|
|
40
|
-
|
|
|
41
|
-
|
|
42
|
-
|
|
43
|
-
|
|
|
44
|
-
|
|
45
|
-
|
|
46
|
-
|
|
47
|
-
|
|
|
48
|
-
|
|
|
49
|
-
|
|
50
|
-
|
|
51
|
-
|
|
|
52
|
-
|
|
53
|
-
|
|
54
|
-
|
|
55
|
-
|
|
56
|
-
|
|
57
|
-
|
|
58
|
-
|
|
59
|
-
|
|
60
|
-
|
|
61
|
-
|
|
62
|
-
|
|
63
|
-
|
|
64
|
-
|
|
65
|
-
|
|
66
|
-
|
|
67
|
-
|
|
68
|
-
|
|
69
|
-
|
|
|
70
|
-
|
|
|
71
|
-
| `
|
|
72
|
-
|
|
73
|
-
|
|
74
|
-
|
|
75
|
-
|
|
|
76
|
-
|
|
|
77
|
-
| `
|
|
78
|
-
| `
|
|
79
|
-
|
|
80
|
-
|
|
81
|
-
|
|
82
|
-
|
|
83
|
-
|
|
84
|
-
|
|
85
|
-
|
|
86
|
-
|
|
87
|
-
|
|
88
|
-
|
|
89
|
-
|
|
|
90
|
-
|
|
91
|
-
|
|
92
|
-
|
|
93
|
-
|
|
94
|
-
|
|
95
|
-
|
|
96
|
-
|
|
97
|
-
| 字段 | 说明 | 示例 |
|
|
98
|
-
|
|
|
99
|
-
| `
|
|
100
|
-
| `
|
|
101
|
-
| `
|
|
102
|
-
|
|
103
|
-
|
|
104
|
-
|
|
105
|
-
|
|
106
|
-
|
|
107
|
-
|
|
108
|
-
|
|
|
109
|
-
|
|
|
110
|
-
| `
|
|
111
|
-
|
|
112
|
-
|
|
113
|
-
|
|
114
|
-
|
|
115
|
-
|
|
116
|
-
|
|
117
|
-
|
|
118
|
-
| 字段 | 说明 | 示例 |
|
|
119
|
-
|
|
|
120
|
-
| `
|
|
121
|
-
| `
|
|
122
|
-
|
|
1
|
+
# 配置文件（`site.yaml`）字段说明
|
|
2
|
+
|
|
3
|
+
项目遵循“配置驱动”。绝大多数行为由 `public/config/site.yaml` 决定。下面用表格逐项说明所有字段。
|
|
4
|
+
|
|
5
|
+
## 顶级键
|
|
6
|
+
| 键 | 作用 |
|
|
7
|
+
| :-- | :-- |
|
|
8
|
+
| `site` | 全局元信息（标题、描述、Logo、作者） |
|
|
9
|
+
| `navbar` | 顶部导航（开关、导航项、操作按钮） |
|
|
10
|
+
| `sidebar` | 左侧导航树（集合/分组/子项） |
|
|
11
|
+
| `theme` | 主题配置（默认模式、是否允许切换） |
|
|
12
|
+
| `toc` | 文章右侧目录（开关、层级、标题） |
|
|
13
|
+
| `footer` | 页脚（链接、社交、仓库信息） |
|
|
14
|
+
| `pwa` | PWA 设置（预留/可选） |
|
|
15
|
+
|
|
16
|
+
---
|
|
17
|
+
|
|
18
|
+
## `site`
|
|
19
|
+
| 字段 | 类型 | 说明 | 示例 |
|
|
20
|
+
| :-- | :-- | :-- | :-- |
|
|
21
|
+
| `title` | string | 网站标题 | `"React Docs UI 示例"` |
|
|
22
|
+
| `description` | string | 简短网站描述（SEO） | `"简单漂亮的文档站"` |
|
|
23
|
+
| `logo` | string 或 object | 网站 Logo。字符串可为 emoji 或图片路径；对象可分别设置亮/暗图标 | `"📚"`、`"/images/logo.png"`、或 `{ light: "/images/favicon.svg", dark: "/images/favicon-dark.svg" }` |
|
|
24
|
+
| `author` | string | 作者或组织 | `"React Docs UI Team"` |
|
|
25
|
+
|
|
26
|
+
Logo 支持：
|
|
27
|
+
- Emoji：`"🚀"`
|
|
28
|
+
- 公共路径或 URL：`"/images/logo.png"`
|
|
29
|
+
- 明/暗主题对象：`{ light, dark }`
|
|
30
|
+
|
|
31
|
+
---
|
|
32
|
+
|
|
33
|
+
## `navbar`
|
|
34
|
+
| 字段 | 类型 | 说明 |
|
|
35
|
+
| :-- | :-- | :-- |
|
|
36
|
+
| `showLogo` | boolean | 是否显示左上角 Logo |
|
|
37
|
+
| `showTitle` | boolean | 是否显示站点标题 |
|
|
38
|
+
| `showLanguageSwitcher` | boolean | 是否显示语言切换 |
|
|
39
|
+
| `items` | array<Item> | 主导航链接 |
|
|
40
|
+
| `actions` | array<Action> | 右侧操作按钮（如 GitHub） |
|
|
41
|
+
|
|
42
|
+
Item
|
|
43
|
+
| 字段 | 类型 | 说明 | 示例 |
|
|
44
|
+
| :-- | :-- | :-- | :-- |
|
|
45
|
+
| `title` | string | 链接文字 | `"指南"` |
|
|
46
|
+
| `link` | string | 路径或 URL。内部路径以 `/` 开头 | `"/guide"` |
|
|
47
|
+
| `external` | boolean(可选) | 外部链接新开标签 |
|
|
48
|
+
| `visible` | boolean(可选) | 条件展示 |
|
|
49
|
+
|
|
50
|
+
Action
|
|
51
|
+
| 字段 | 类型 | 说明 | 示例 |
|
|
52
|
+
| :-- | :-- | :-- | :-- |
|
|
53
|
+
| `type` | `"github"`/`"custom"`(可选) | 预设或自定义动作 | `"github"` |
|
|
54
|
+
| `title` | string(可选) | 自定义动作按钮文案 |
|
|
55
|
+
| `link` | string | 目标链接 |
|
|
56
|
+
| `icon` | string(可选) | 自定义动作图标名 |
|
|
57
|
+
| `enabled` | boolean(可选) | 是否启用 |
|
|
58
|
+
|
|
59
|
+
---
|
|
60
|
+
|
|
61
|
+
## `sidebar`
|
|
62
|
+
| 字段 | 类型 | 说明 |
|
|
63
|
+
| :-- | :-- | :-- |
|
|
64
|
+
| `enabled` | boolean(可选) | 全局开启/关闭侧边栏 |
|
|
65
|
+
| `collections` | record<string, Collection> | 顶级集合映射（如 `guide`） |
|
|
66
|
+
| `sections` | Section[] (兼容，可选) | 旧版单树结构 |
|
|
67
|
+
|
|
68
|
+
Collection
|
|
69
|
+
| 字段 | 类型 | 说明 |
|
|
70
|
+
| :-- | :-- | :-- |
|
|
71
|
+
| `sections` | Section[] | 一组可折叠分组 |
|
|
72
|
+
|
|
73
|
+
Section
|
|
74
|
+
| 字段 | 类型 | 说明 | 示例 |
|
|
75
|
+
| :-- | :-- | :-- | :-- |
|
|
76
|
+
| `title` | string | 分组标题 | `"快速开始"` |
|
|
77
|
+
| `path` | string | 访问该前缀将自动展开/高亮 | `"/guide"` |
|
|
78
|
+
| `children` | Child[](可选) | 该分组下的子链接 |
|
|
79
|
+
|
|
80
|
+
Child
|
|
81
|
+
| 字段 | 类型 | 说明 | 示例 |
|
|
82
|
+
| :-- | :-- | :-- | :-- |
|
|
83
|
+
| `title` | string | 子链接文字 | `"介绍"` |
|
|
84
|
+
| `path` | string | 完整页面路径 | `"/guide/introduction"` |
|
|
85
|
+
|
|
86
|
+
---
|
|
87
|
+
|
|
88
|
+
## `theme`
|
|
89
|
+
| 字段 | 类型 | 说明 | 可选值 | 默认值 |
|
|
90
|
+
| :-- | :-- | :-- | :-- | :-- |
|
|
91
|
+
| `defaultMode` | string | 默认主题模式 | `light`/`dark`/`auto` | `auto` |
|
|
92
|
+
| `allowToggle` | boolean | 是否允许用户切换主题 | `true`/`false` | `true` |
|
|
93
|
+
|
|
94
|
+
---
|
|
95
|
+
|
|
96
|
+
## `toc`
|
|
97
|
+
| 字段 | 类型 | 说明 | 示例 |
|
|
98
|
+
| :-- | :-- | :-- | :-- |
|
|
99
|
+
| `enabled` | boolean | 是否启用页面目录 | `true` |
|
|
100
|
+
| `maxLevel` | number (1-6) | 展示的最大标题层级 | `3` |
|
|
101
|
+
| `title` | string | 目录标题 | `"本页内容"` |
|
|
102
|
+
|
|
103
|
+
说明：具体锚点与是否显示也可能受页面 Frontmatter 影响。
|
|
104
|
+
|
|
105
|
+
---
|
|
106
|
+
|
|
107
|
+
## `footer`
|
|
108
|
+
| 字段 | 类型 | 说明 |
|
|
109
|
+
| :-- | :-- | :-- |
|
|
110
|
+
| `enabled` | boolean | 是否显示页脚 |
|
|
111
|
+
| `copyright` | string | 版权文案 |
|
|
112
|
+
| `repository` | Repository(可选) | 仓库信息（如“在 GitHub 上编辑此页”） |
|
|
113
|
+
| `lastUpdated` | string(可选) | 站点/内容最近更新时间 |
|
|
114
|
+
| `links` | Link[](可选) | 页脚链接列 |
|
|
115
|
+
| `social` | Social[](可选) | 社交图标链接 |
|
|
116
|
+
|
|
117
|
+
Repository
|
|
118
|
+
| 字段 | 类型 | 说明 | 示例 |
|
|
119
|
+
| :-- | :-- | :-- | :-- |
|
|
120
|
+
| `url` | string | 仓库地址 | `"https://github.com/user/repo"` |
|
|
121
|
+
| `branch` | string | 文档所在分支 | `"main"` |
|
|
122
|
+
|
|
123
|
+
Link
|
|
124
|
+
| 字段 | 类型 | 说明 |
|
|
125
|
+
| :-- | :-- | :-- |
|
|
126
|
+
| `title` | string | 链接标题 |
|
|
127
|
+
| `link` | string | 路径或 URL |
|
|
128
|
+
| `external` | boolean(可选) | 新开标签 |
|
|
129
|
+
|
|
130
|
+
Social
|
|
131
|
+
| 字段 | 类型 | 说明 |
|
|
132
|
+
| :-- | :-- | :-- |
|
|
133
|
+
| `name` | string | 平台名称（如 `github`/`twitter`/`bilibili`） |
|
|
134
|
+
| `url` | string | 个人页或链接 |
|
|
135
|
+
| `icon` | string | 图标名 |
|
|
136
|
+
|
|
137
|
+
---
|
|
138
|
+
|
|
139
|
+
## `pwa`（可选）
|
|
140
|
+
| 字段 | 类型 | 说明 |
|
|
141
|
+
| :-- | :-- | :-- |
|
|
142
|
+
| `enabled` | boolean | 是否启用 PWA（预留） |
|
|
143
|
+
| `name` | string | 应用名 |
|
|
144
|
+
| `shortName` | string | 应用短名 |
|
|
145
|
+
| `description` | string | 应用描述 |
|
|
146
|
+
| `themeColor` | string | 主题色 |
|
|
147
|
+
| `backgroundColor` | string | 背景色 |
|
|
148
|
+
|
|
149
|
+
---
|
|
150
|
+
|