create-react-docs-ui 0.1.4 → 0.1.6

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

@@ -1,122 +1,150 @@
-# 配置文件 (`site.yaml`) 详解
-
-`react-docs-ui` 的核心是其**配置驱动**的理念。你几乎可以通过 `public/config/site.yaml` 这一个文件来定义整个网站的外观和行为。本文档将详细解释每个配置项。
-
-## 顶级配置项概览
-
-| 顶级字段 | 说明 |
-| :--- | :--- |
-| `site` | 网站的全局信息，如标题、描述、Logo。 |
-| `navbar` | 配置网站顶部的导航栏。 |
-| `sidebar` | 配置网站侧边栏的导航菜单。 |
-| `theme` | 配置网站的主题，如颜色、浅色/深色模式。 |
-| `footer` | 配置网站底部的页脚信息。 |
-| `toc` | 配置文章页面右侧的目录（Table of Contents）。 |
-
----
-
-## `site`
-
-网站的基础元数据配置。
-
-| 字段 | 说明 | 示例 |
-| :--- | :--- | :--- |
-| `title` | 网站标题，显示在浏览器标签页上。 | `"React Docs UI"` |
-| `description` | 网站描述，用于搜索引擎优化 (SEO)。 | `"一个 React 文档网站构建工具"` |
-| `logo` | 网站 Logo，显示在导航栏左上角。 | `"📚"` 或 `"/images/logo.png"` 或一个包含 `light` 和 `dark` 模式图片路径的对象 |
-| `author` | 网站作者。 | `"React Docs UI Team"` |
-
-**Logo 格式说明:**
-1.  **Emoji**: 直接使用一个表情符号，如 `"🚀"`。
-2.  **本地图片**: 指向 `public` 目录下的图片路径，如 `"/images/logo.png"`。
-3.  **亮/暗模式图片**: 一个对象，包含 `light` 和 `dark` 两个键，分别指向不同主题下的图片路径。
-
----
-
-## `navbar`
-
-顶部导航栏配置。
-
-| 字段 | 说明 |
-| :--- | :--- |
-| `items` | 导航项数组，定义了导航栏中显示的所有链接。 |
-| `actions` | (可选) 导航栏右侧的操作按钮，如 GitHub 链接。 |
-
-### `navbar.items`
-
-| 字段 | 说明 | 示例 |
-| :--- | :--- | :--- |
-| `title` | 导航项的显示文本。 | `"指南"` |
-| `link` | 链接地址。内部链接以 `/` 开头。 | `"/guide/introduction"` |
-| `external` | (可选) `true` 表示为外部链接，将在新标签页打开。 | `true` |
-
----
-
-## `sidebar`
-
-侧边栏导航配置，是文档结构的核心。它使用 `collections` 来组织不同部分的内容。
-
-| 字段 | 说明 |
-| :--- | :--- |
-| `collections` | 一个对象，键是集合的名称（通常对应一级路由，如 `guide`），值是该集合的侧边栏配置。 |
-
-### `sidebar.collections.<name>.sections`
-
-每个集合包含一个 `sections` 数组，每个 `section` 代表一个可折叠的菜单组。
-
-| 字段 | 说明 | 示例 |
-| :--- | :--- | :--- |
-| `title` | 区域的标题。 | `"入门指南"` |
-| `path` | 区域的基础路径。当用户访问的 URL 以此路径开头时，该区域会自动展开并高亮。 | `"/guide"` |
-| `children` | 该区域下的子链接数组。 | |
-
-### `sidebar.collections.<name>.sections.children`
-
-| 字段 | 说明 | 示例 |
-| :--- | :--- | :--- |
-| `title` | 子链接的显示文本。 | `"介绍"` |
-| `path` | 子链接的完整路径，指向一个具体的 Markdown 页面。 | `"/guide/introduction"` |
-
----
-
-## `theme`
-
-主题和外观配置。
-
-| 字段 | 说明 | 可选值 | 默认值 |
-| :--- | :--- | :--- | :--- |
-| `defaultMode` | 网站的默认主题模式。 | `'light'`, `'dark'`, `'system'` | `'system'` |
-| `allowToggle` | 是否允许用户切换主题。 | `true`, `false` | `true` |
-
----
-
-## `footer`
-
-页脚配置。
-
-| 字段 | 说明 | 示例 |
-| :--- | :--- | :--- |
-| `copyright` | 版权信息。`{year}` 会被替换为当前年份。 | `"Copyright © {year} My Company"` |
-| `repository` | (可选) 仓库信息，用于显示“在 GitHub 上编辑此页”等链接。 | |
-| `links` | (可选) 在页脚显示的额外链接列。 | |
-| `social` | (可选) 在页脚显示的社交媒体图标链接。 | |
-
-### `footer.repository`
-
-| 字段 | 说明 | 示例 |
-| :--- | :--- | :--- |
-| `url` | 仓库的 URL。 | `"https://github.com/user/repo"` |
-| `branch` | 文档所在的 Git 分支。 | `"main"` |
-| `dir` | 文档文件在仓库中的根目录。 | `"docs/src"` |
-
----
-
-## `toc` (Table of Contents)
-
-文章页面右侧的目录配置。
-
-| 字段 | 说明 | 示例 |
-| :--- | :--- | :--- |
-| `enabled` | 是否启用页面目录功能。 | `true` |
-| `maxLevel` | 在目录中显示的最大标题级别（h1-h6）。 | `3` |
-| `title` | 目录组件的标题。 | `"本页内容"` |
+# 配置文件（`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 | 背景色 |
+
+---
+

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

@@ -1,109 +1,108 @@
-# 快速上手
-
-本指南将引导你在 5 分钟内，从零开始创建、配置并运行一个属于你自己的 React 文档网站。
-
-## 1. 创建项目
-
-使用官方脚手架是最高效的方式。打开你的终端，运行以下命令：
-
-```bash
-# 这会创建一个名为 "my-awesome-docs" 的项目
-npx create-react-docs-ui@latest my-awesome-docs
-```
-
-然后，进入项目目录并安装依赖：
-
-```bash
-cd my-awesome-docs
-npm install
-```
-
-## 2. 组织你的文档
-
-所有的文档内容都以 Markdown 文件的形式存放在 `public/docs/` 目录下。
-
-- 打开 `public/docs/zh-cn/` 目录。
-- 你可以修改现有的 `index.md` 和 `guide` 目录下的文件，或者创建新的 `.md` 文件。
-
-例如，我们来创建一个新页面。在 `public/docs/zh-cn/` 下新建一个 `about.md` 文件：
-
-```markdown
----
-title: 关于我们
-description: 这是一个关于我们团队的页面。
----
-
-# 关于我们
-
-我们热爱开源和创造！
-```
-
-**注意**: 你可以在 Markdown 文件顶部使用 `frontmatter` 来定义页面标题 (`title`) 和描述 (`description`)。
-
-## 3. 配置网站
-
-现在，让我们通过修改配置文件来展示新创建的页面。
-
-打开核心配置文件 `public/config/site.yaml`。
-
-### a. 修改网站信息
-
-更新 `site` 部分，给你的网站一个新标题和 Logo。
-
-```yaml
-site:
-  title: "我的超赞文档"
-  description: "一个使用 React Docs UI 构建的网站"
-  logo: "🚀" # 你可以使用 emoji 或图片路径
-```
-
-### b. 添加到导航栏
-
-在 `navbar.items` 数组中，为“关于”页面添加一个链接。
-
-```yaml
-navbar:
-  items:
-    - title: "首页"
-      link: "/zh-cn/"
-    - title: "指南"
-      link: "/zh-cn/guide/introduction"
-    - title: "关于"  # 新增
-      link: "/zh-cn/about" # 新增
-```
-
-### c. 添加到侧边栏
-
-为了让“关于”页面在侧边栏也可见，我们在 `sidebar.collections.guide.sections` 中添加一个新条目。
-
-```yaml
-sidebar:
-  collections:
-    guide:
-      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"
-```
-
-## 4. 启动网站
-
-保存你的所有修改，然后在终端运行：
-
-```bash
-npm run dev
-```
-
+# 快速上手
+
+本指南将引导你在 5 分钟内，从零开始创建、配置并运行一个属于你自己的 React 文档网站。
+
+## 1. 创建项目
+
+使用官方脚手架是最高效的方式。打开你的终端，运行以下命令：
+
+```bash
+# 这会创建一个名为 "my-awesome-docs" 的项目
+npx create-react-docs-ui@latest my-awesome-docs
+```
+
+然后，进入项目目录并安装依赖：
+
+```bash
+cd my-awesome-docs
+npm install
+```
+
+## 2. 组织你的文档
+
+所有的文档内容都以 Markdown 文件的形式存放在 `public/docs/` 目录下。
+
+- 打开 `public/docs/zh-cn/` 目录。
+- 你可以修改现有的 `index.md` 和 `guide` 目录下的文件，或者创建新的 `.md` 文件。
+
+例如，我们来创建一个新页面。在 `public/docs/zh-cn/` 下新建一个 `about.md` 文件：
+
+```markdown
+---
+title: 关于我们
+description: 这是一个关于我们团队的页面。
+---
+
+# 关于我们
+
+我们热爱开源和创造！
+```
+
+
+## 3. 配置网站
+
+现在，让我们通过修改配置文件来展示新创建的页面。
+
+打开核心配置文件 `public/config/site.yaml`。
+
+### a. 修改网站信息
+
+更新 `site` 部分，给你的网站一个新标题和 Logo。
+
+```yaml
+site:
+  title: "我的超赞文档"
+  description: "一个使用 React Docs UI 构建的网站"
+  logo: "🚀" # 你可以使用 emoji 或图片路径
+```
+
+### b. 添加到导航栏
+
+在 `navbar.items` 数组中，为“关于”页面添加一个链接。
+
+```yaml
+navbar:
+  items:
+    - title: "首页"
+      link: "/zh-cn/"
+    - title: "指南"
+      link: "/zh-cn/guide/introduction"
+    - title: "关于"  # 新增
+      link: "/zh-cn/about" # 新增
+```
+
+### c. 添加到侧边栏
+
+为了让“关于”页面在侧边栏也可见，我们在 `sidebar.collections.guide.sections` 中添加一个新条目。
+
+```yaml
+sidebar:
+  collections:
+    guide:
+      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"
+```
+
+## 4. 启动网站
+
+保存你的所有修改，然后在终端运行：
+
+```bash
+npm run dev
+```
+
 你的网站现在应该运行在 `http://localhost:5173` 上了。访问它，你会看到更新后的标题、Logo，以及导航栏和侧边栏中新增的“关于”链接。恭喜你，你已经成功掌握了 React Docs UI 的基本工作流程！