create-react-docs-ui 0.3.0 → 0.4.0

package/template/public/docs/zh-cn/{guide → docs/guide}/configuration.md

@@ -1,150 +1,196 @@
-# 配置文件（`site.yaml`）字段说明
-
-项目遵循“配置驱动”。绝大多数行为由 `public/config/site.yaml` 决定。下面用表格逐项说明所有字段。
-
-## 顶级键
-| 键 | 作用 |
-| :-- | :-- |
-| `site` | 全局元信息（标题、描述、Logo、作者） |
-| `navbar` | 顶部导航（开关、导航项、操作按钮） |
-| `sidebar` | 左侧导航树（集合/分组/子项） |
-| `theme` | 主题配置（默认模式、是否允许切换） |
-| `toc` | 文章右侧目录（开关、层级、标题） |
-| `footer` | 页脚（链接、社交、仓库信息） |
-| `pwa` | PWA 设置（预留/可选） |
-
----
-
-## `site`
-| 字段 | 类型 | 说明 | 示例 |
-| :-- | :-- | :-- | :-- |
-| `title` | string | 网站标题 | `"React Docs UI 示例"` |
-| `description` | string | 简短网站描述（SEO） | `"简单漂亮的文档站"` |
-| `logo` | string 或 object | 网站 Logo。字符串可为 emoji 或图片路径；对象可分别设置亮/暗图标 | `"📚"`、`"/images/logo.png"`、或 `{ light: "/images/favicon.svg", dark: "/images/favicon-dark.svg" }` |
-| `author` | string | 作者或组织 | `"React Docs UI Team"` |
-
-Logo 支持：
-- Emoji：`"🚀"`
-- 公共路径或 URL：`"/images/logo.png"`
-- 明/暗主题对象：`{ light, dark }`
-
----
-
-## `navbar`
-| 字段 | 类型 | 说明 |
-| :-- | :-- | :-- |
-| `showLogo` | boolean | 是否显示左上角 Logo |
-| `showTitle` | boolean | 是否显示站点标题 |
-| `showLanguageSwitcher` | boolean | 是否显示语言切换 |
-| `items` | array<Item> | 主导航链接 |
-| `actions` | array<Action> | 右侧操作按钮（如 GitHub） |
-
-Item
-| 字段 | 类型 | 说明 | 示例 |
-| :-- | :-- | :-- | :-- |
-| `title` | string | 链接文字 | `"指南"` |
-| `link` | string | 路径或 URL。内部路径以 `/` 开头 | `"/guide"` |
-| `external` | boolean(可选) | 外部链接新开标签 |
-| `visible` | boolean(可选) | 条件展示 |
-
-Action
-| 字段 | 类型 | 说明 | 示例 |
-| :-- | :-- | :-- | :-- |
-| `type` | `"github"`/`"custom"`(可选) | 预设或自定义动作 | `"github"` |
-| `title` | string(可选) | 自定义动作按钮文案 |
-| `link` | string | 目标链接 |
-| `icon` | string(可选) | 自定义动作图标名 |
-| `enabled` | boolean(可选) | 是否启用 |
-
----
-
-## `sidebar`
-| 字段 | 类型 | 说明 |
-| :-- | :-- | :-- |
-| `enabled` | boolean(可选) | 全局开启/关闭侧边栏 |
-| `collections` | record<string, Collection> | 顶级集合映射（如 `guide`） |
-| `sections` | Section[] (兼容，可选) | 旧版单树结构 |
-
-Collection
-| 字段 | 类型 | 说明 |
-| :-- | :-- | :-- |
-| `sections` | Section[] | 一组可折叠分组 |
-
-Section
-| 字段 | 类型 | 说明 | 示例 |
-| :-- | :-- | :-- | :-- |
-| `title` | string | 分组标题 | `"快速开始"` |
-| `path` | string | 访问该前缀将自动展开/高亮 | `"/guide"` |
-| `children` | Child[](可选) | 该分组下的子链接 |
-
-Child
-| 字段 | 类型 | 说明 | 示例 |
-| :-- | :-- | :-- | :-- |
-| `title` | string | 子链接文字 | `"介绍"` |
-| `path` | string | 完整页面路径 | `"/guide/introduction"` |
-
----
-
-## `theme`
-| 字段 | 类型 | 说明 | 可选值 | 默认值 |
-| :-- | :-- | :-- | :-- | :-- |
-| `defaultMode` | string | 默认主题模式 | `light`/`dark`/`auto` | `auto` |
-| `allowToggle` | boolean | 是否允许用户切换主题 | `true`/`false` | `true` |
-
----
-
-## `toc`
-| 字段 | 类型 | 说明 | 示例 |
-| :-- | :-- | :-- | :-- |
-| `enabled` | boolean | 是否启用页面目录 | `true` |
-| `maxLevel` | number (1-6) | 展示的最大标题层级 | `3` |
-| `title` | string | 目录标题 | `"本页内容"` |
-
-说明：具体锚点与是否显示也可能受页面 Frontmatter 影响。
-
----
-
-## `footer`
-| 字段 | 类型 | 说明 |
-| :-- | :-- | :-- |
-| `enabled` | boolean | 是否显示页脚 |
-| `copyright` | string | 版权文案 |
-| `repository` | Repository(可选) | 仓库信息（如“在 GitHub 上编辑此页”） |
-| `lastUpdated` | string(可选) | 站点/内容最近更新时间 |
-| `links` | Link[](可选) | 页脚链接列 |
-| `social` | Social[](可选) | 社交图标链接 |
-
-Repository
-| 字段 | 类型 | 说明 | 示例 |
-| :-- | :-- | :-- | :-- |
-| `url` | string | 仓库地址 | `"https://github.com/user/repo"` |
-| `branch` | string | 文档所在分支 | `"main"` |
-
-Link
-| 字段 | 类型 | 说明 |
-| :-- | :-- | :-- |
-| `title` | string | 链接标题 |
-| `link` | string | 路径或 URL |
-| `external` | boolean(可选) | 新开标签 |
-
-Social
-| 字段 | 类型 | 说明 |
-| :-- | :-- | :-- |
-| `name` | string | 平台名称（如 `github`/`twitter`/`bilibili`） |
-| `url` | string | 个人页或链接 |
-| `icon` | string | 图标名 |
-
----
-
-## `pwa`（可选）
-| 字段 | 类型 | 说明 |
-| :-- | :-- | :-- |
-| `enabled` | boolean | 是否启用 PWA（预留） |
-| `name` | string | 应用名 |
-| `shortName` | string | 应用短名 |
-| `description` | string | 应用描述 |
-| `themeColor` | string | 主题色 |
-| `backgroundColor` | string | 背景色 |
-
----
-
+# 配置文件（`site.yaml`）字段说明
+
+项目遵循“配置驱动”。绝大多数行为由 `public/config/site.yaml` 决定。下面用表格逐项说明所有字段。
+
+## 顶级键
+| 键 | 作用 |
+| :-- | :-- |
+| `site` | 全局元信息（标题、描述、Logo、作者） |
+| `navbar` | 顶部导航（开关、导航项、操作按钮） |
+| `sidebar` | 左侧导航树（集合/分组/子项） |
+| `theme` | 主题配置（默认模式、是否允许切换） |
+| `toc` | 文章右侧目录（开关、层级、标题） |
+| `footer` | 页脚（链接、社交、仓库信息） |
+| `contextMenu` | 右键菜单配置 |
+| `mdx` | MDX 组件配置 |
+| `pwa` | PWA 设置（预留/可选） |
+
+---
+
+## `site`
+| 字段 | 类型 | 说明 | 示例 |
+| :-- | :-- | :-- | :-- |
+| `title` | string | 网站标题 | `"React Docs UI 示例"` |
+| `description` | string | 简短网站描述（SEO） | `"简单漂亮的文档站"` |
+| `logo` | string 或 object | 网站 Logo。字符串可为 emoji 或图片路径；对象可分别设置亮/暗图标 | `"📚"`、`"/images/logo.png"`、或 `{ light: "/images/favicon.svg", dark: "/images/favicon-dark.svg" }` |
+| `author` | string | 作者或组织 | `"React Docs UI Team"` |
+
+Logo 支持：
+- Emoji：`"🚀"`
+- 公共路径或 URL：`"/images/logo.png"`
+- 明/暗主题对象：`{ light, dark }`
+
+---
+
+## `navbar`
+| 字段 | 类型 | 说明 |
+| :-- | :-- | :-- |
+| `showLogo` | boolean | 是否显示左上角 Logo |
+| `showTitle` | boolean | 是否显示站点标题 |
+| `showLanguageSwitcher` | boolean | 是否显示语言切换 |
+| `items` | array<Item> | 主导航链接 |
+| `actions` | array<Action> | 右侧操作按钮（如 GitHub） |
+
+Item
+| 字段 | 类型 | 说明 | 示例 |
+| :-- | :-- | :-- | :-- |
+| `title` | string | 链接文字 | `"指南"` |
+| `link` | string | 路径或 URL。内部路径以 `/` 开头 | `"/guide"` |
+| `external` | boolean(可选) | 外部链接新开标签 |
+| `visible` | boolean(可选) | 条件展示 |
+
+Action
+| 字段 | 类型 | 说明 | 示例 |
+| :-- | :-- | :-- | :-- |
+| `type` | `"github"`/`"custom"`(可选) | 预设或自定义动作 | `"github"` |
+| `title` | string(可选) | 自定义动作按钮文案 |
+| `link` | string | 目标链接 |
+| `icon` | string(可选) | 自定义动作图标名 |
+| `enabled` | boolean(可选) | 是否启用 |
+
+---
+
+## `sidebar`
+| 字段 | 类型 | 说明 |
+| :-- | :-- | :-- |
+| `enabled` | boolean(可选) | 全局开启/关闭侧边栏 |
+| `collections` | record<string, Collection> | 顶级集合映射（如 `guide`） |
+| `sections` | Section[] (兼容，可选) | 旧版单树结构 |
+
+Collection
+| 字段 | 类型 | 说明 |
+| :-- | :-- | :-- |
+| `sections` | Section[] | 一组可折叠分组 |
+
+Section
+| 字段 | 类型 | 说明 | 示例 |
+| :-- | :-- | :-- | :-- |
+| `title` | string | 分组标题 | `"快速开始"` |
+| `path` | string | 访问该前缀将自动展开/高亮 | `"/guide"` |
+| `children` | Child[](可选) | 该分组下的子链接 |
+
+Child
+| 字段 | 类型 | 说明 | 示例 |
+| :-- | :-- | :-- | :-- |
+| `title` | string | 子链接文字 | `"介绍"` |
+| `path` | string | 完整页面路径 | `"/guide/introduction"` |
+
+---
+
+## `theme`
+| 字段 | 类型 | 说明 | 可选值 | 默认值 |
+| :-- | :-- | :-- | :-- | :-- |
+| `defaultMode` | string | 默认主题模式 | `light`/`dark`/`auto` | `auto` |
+| `allowToggle` | boolean | 是否允许用户切换主题 | `true`/`false` | `true` |
+
+---
+
+## `toc`
+| 字段 | 类型 | 说明 | 示例 |
+| :-- | :-- | :-- | :-- |
+| `enabled` | boolean | 是否启用页面目录 | `true` |
+| `maxLevel` | number (1-6) | 展示的最大标题层级 | `3` |
+| `title` | string | 目录标题 | `"本页内容"` |
+
+说明：具体锚点与是否显示也可能受页面 Frontmatter 影响。
+
+---
+
+## `footer`
+| 字段 | 类型 | 说明 |
+| :-- | :-- | :-- |
+| `enabled` | boolean | 是否显示页脚 |
+| `copyright` | string | 版权文案 |
+| `repository` | Repository(可选) | 仓库信息（如“在 GitHub 上编辑此页”） |
+| `lastUpdated` | string(可选) | 站点/内容最近更新时间 |
+| `links` | Link[](可选) | 页脚链接列 |
+| `social` | Social[](可选) | 社交图标链接 |
+
+Repository
+| 字段 | 类型 | 说明 | 示例 |
+| :-- | :-- | :-- | :-- |
+| `url` | string | 仓库地址 | `"https://github.com/user/repo"` |
+| `branch` | string | 文档所在分支 | `"main"` |
+
+Link
+| 字段 | 类型 | 说明 |
+| :-- | :-- | :-- |
+| `title` | string | 链接标题 |
+| `link` | string | 路径或 URL |
+| `external` | boolean(可选) | 新开标签 |
+
+Social
+| 字段 | 类型 | 说明 |
+| :-- | :-- | :-- |
+| `name` | string | 平台名称（如 `github`/`twitter`/`bilibili`） |
+| `url` | string | 个人页或链接 |
+| `icon` | string | 图标名 |
+
+---
+
+## `contextMenu`
+| 字段 | 类型 | 说明 |
+| :-- | :-- | :-- |
+| `enabled` | boolean | 全局开关，false 则完全禁用右键菜单 |
+| `page` | object | 页面组菜单项配置 |
+| `site` | object | 站点组菜单项配置 |
+| `appearance` | object | 外观组菜单项配置 |
+
+Page
+| 字段 | 类型 | 说明 | 默认值 |
+| :-- | :-- | :-- | :-- |
+| `copySelectedText` | boolean | 复制选中的文字 | `true` |
+| `copyUrl` | boolean | 复制当前链接 | `true` |
+| `copyTitle` | boolean | 复制页面标题 | `false` |
+| `copyMarkdownLink` | boolean | 复制 Markdown 链接 | `false` |
+| `openInNewTab` | boolean | 在新标签页打开 | `false` |
+| `reload` | boolean | 刷新 | `true` |
+| `printPage` | boolean | 打印页面 | `true` |
+| `scrollToTop` | boolean | 回到顶部 | `true` |
+| `scrollToBottom` | boolean | 滚动到底部 | `true` |
+
+Site
+| 字段 | 类型 | 说明 | 默认值 |
+| :-- | :-- | :-- | :-- |
+| `goHome` | boolean | 返回首页 | `true` |
+| `quickNav` | boolean | 快速跳转 | `false` |
+| `language` | boolean | 语言切换 | `false` |
+
+Appearance
+| 字段 | 类型 | 说明 | 默认值 |
+| :-- | :-- | :-- | :-- |
+| `theme` | boolean | 主题切换 | `false` |
+| `resetThemePref` | boolean | 重置主题偏好 | `false` |
+
+---
+
+## `mdx`
+| 字段 | 类型 | 说明 | 示例 |
+| :-- | :-- | :-- | :-- |
+| `componentsPath` | string | 组件扫描路径 | `"/src/components"` |
+| `enabled` | boolean | 启用 MDX 支持 | `true` |
+
+---
+
+## `pwa`（可选）
+| 字段 | 类型 | 说明 |
+| :-- | :-- | :-- |
+| `enabled` | boolean | 是否启用 PWA（预留） |
+| `name` | string | 应用名 |
+| `shortName` | string | 应用短名 |
+| `description` | string | 应用描述 |
+| `themeColor` | string | 主题色 |
+| `backgroundColor` | string | 背景色 |
+
+---
+

package/template/public/docs/zh-cn/{guide → docs/guide}/installation.md

@@ -39,7 +39,7 @@
     ```
 
 2.  **创建配置文件**:
-    在你的 `public` 目录下创建一个 `config` 文件夹，并在其中新建一个 `site.yaml` 文件。你可以从[这里](https://github.com/shenjianZ/react-docs-ui/blob/main/react-docs-ui/public/config/site.yaml)复制一个基础模板。
+    在你的 `public` 目录下创建一个 `config` 文件夹，并在其中新建一个 `site.yaml` 文件。你可以从[这里](https://github.com/shenjianZ/create-vue-docs-ui/blob/master/template/public/config/site.yaml)复制一个基础模板。
 
 3.  **创建文档目录**:
     在 `public` 目录下创建一个 `docs` 文件夹，用于存放你的 Markdown 文件。例如: `public/docs/zh-cn/index.md`。
@@ -60,4 +60,4 @@
       </React.StrictMode>,
     )
     ```
-5.  **确保 `index.html` 中有 `<div id="root"></div>`**
+5.  **确保 `index.html` 中有 `<div id="root"></div>`**

package/template/public/docs/zh-cn/{guide → docs/guide}/quick-start.md

@@ -25,17 +25,15 @@ npm install
 - 打开 `public/docs/zh-cn/` 目录。
 - 你可以修改现有的 `index.md` 和 `guide` 目录下的文件，或者创建新的 `.md` 文件。
 
-例如，我们来创建一个新页面。在 `public/docs/zh-cn/` 下新建一个 `about.md` 文件：
+例如，我们来创建一个新页面。在`public/docs/zh-cn/`新建`about`目录以及`about.md`文件 ,
+`about.md`的内容如下
 
 ```markdown
----
-title: 关于我们
-description: 这是一个关于我们团队的页面。
----
 
 # 关于我们
 
 我们热爱开源和创造！
+
 ```
 
 
@@ -64,39 +62,29 @@ site:
 navbar:
   items:
     - title: "首页"
-      link: "/zh-cn/"
-    - title: "指南"
-      link: "/zh-cn/guide/introduction"
+        link: "/"
+        active: true
+    - title: "文档"
+        link: "/docs"
     - title: "关于"  # 新增
-      link: "/zh-cn/about" # 新增
+        link: "/about" # 新增
 ```
 
 ### c. 添加到侧边栏
 
-为了让“关于”页面在侧边栏也可见，我们在 `sidebar.collections.guide.sections` 中添加一个新条目。
+为了让“关于”页面在侧边栏也可见，我们在 新建一个 `sidebar.collections.about.sections` ，并且添加一个新条目。
 
 ```yaml
 sidebar:
   collections:
-    guide:
+    about:
       sections:
-        - title: "快速开始"
-          path: "/zh-cn/guide"
-          children:
-            - title: "介绍"
-              path: "/zh-cn/guide/introduction"
-            - title: "安装"
-              path: "/zh-cn/guide/installation"
-            - title: "快速上手"
-              path: "/zh-cn/guide/quick-start"
         # 你可以为 "关于" 页面创建一个新的 section
         - title: "关于我们"
-          path: "/zh-cn/about"
-          children:
-            - title: "关于"
-              path: "/zh-cn/about"
+          path: "/about/about"
 ```
 
+这里侧边栏的about项还需要再创建一个文件`public/docs/zh-cn/about` 下`创建about.md`
 ## 4. 启动网站
 
 保存你的所有修改，然后在终端运行：
@@ -105,4 +93,4 @@ sidebar:
 npm run dev
 ```
 
-你的网站现在应该运行在 `http://localhost:5173` 上了。访问它，你会看到更新后的标题、Logo，以及导航栏和侧边栏中新增的“关于”链接。恭喜你，你已经成功掌握了 React Docs UI 的基本工作流程！
+你的网站现在应该运行在 `http://localhost:5173` 上了。访问它，你会看到更新后的标题、Logo，以及导航栏和侧边栏中新增的“关于”链接。恭喜你，你已经成功掌握了 React Docs UI 的基本工作流程！

package/template/public/docs/zh-cn/docs/guide.md

@@ -0,0 +1,10 @@
+# 指南
+
+本指南将帮助你全面了解并掌握 React Docs UI 的各项功能。无论你是初学者还是希望进行深度定制，都能在这里找到所需的信息。
+
+## 目录
+
+- **[介绍](/docs/guide/introduction)**: 了解 React Docs UI 的核心理念和主要优势。
+- **[安装](/docs/guide/installation)**: 学习如何通过脚手架或手动方式安装。
+- **[快速上手](/docs/guide/quick-start)**: 在 5 分钟内创建并运行你的第一个文档网站。
+- **[配置说明 (`site.yaml`)](/docs/guide/configuration)**: 深入了解每个配置项，完全掌控你的网站。