npm - create-react-docs-ui - Versions diffs - 0.1.4 → 0.1.5 - Mend

create-react-docs-ui 0.1.4 → 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.

Files changed (9) hide show

package/README.md +85 -82
package/package.json +15 -2
package/template/index.html +3 -2
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/README.md CHANGED Viewed

@@ -1,82 +1,85 @@
-# create-react-docs-ui
-A simple scaffolding tool to quickly set up a modern documentation website powered by [react-docs-ui](https://github.com/btea/react-docs-ui).
-This tool creates a new project with a pre-configured, feature-rich documentation site, allowing you to focus solely on writing your Markdown content.
-## About the underlying library: react-docs-ui
-`react-docs-ui` is a React component library and toolset designed specifically for building documentation websites. Its core philosophy is **configuration over code**.
-### Core Features
-- **Configuration-Driven**: No need to write complex React components or routing logic. Define your entire site—navigation, sidebar, themes, and footer—through a simple `site.yaml` file.
-- **Fully-Featured Out-of-the-Box**:
-  - Responsive, modern design.
-  - Light/dark theme switching.
-  - Markdown rendering (GFM and Frontmatter supported).
-  - Built-in syntax highlighting.
-  - Quick command menu (`Cmd+K`).
-  - Internationalization (i18n) support.
-- **Extremely Simple to Start**: Launch a complete documentation site in under a minute.
-- **Highly Customizable**: Easily customize the logo, color scheme, navigation links, social media icons, and more.
-## Getting Started
-### Prerequisites
-- **Node.js**: Version `>= 18.0.0`
-- **Package Manager**: `npm`, `yarn`, or `pnpm`
-### Creating a New Project
-Run one of the following commands to create your new documentation site. Replace `my-docs` with your desired project name.
-#### npm
-```bash
-npm create react-docs-ui@latest my-docs
-```
-#### yarn
-```bash
-yarn create react-docs-ui my-docs
-```
-#### pnpm
-```bash
-pnpm create react-docs-ui my-docs
-```
-### Running Your Site
-After the project is created, navigate into the new directory, install dependencies, and start the development server.
-```bash
-cd my-docs
-npm install
-npm run dev
-```
-Your new documentation website will be running at `http://localhost:5173`.
-## Project Structure
-The generated project has a straightforward structure:
-- **`public/config/site.yaml`**: The central configuration file for your entire site. This is where you'll define navigation, sidebars, and metadata.
-- **`public/docs/`**: The directory where all your Markdown documentation files reside. It's pre-configured with `en` and `zh-cn` subdirectories for internationalization.
-- **`src/`**: Contains the main application entry point. You typically won't need to modify files here.
-## Basic Configuration
-To customize your site, you'll primarily edit `public/config/site.yaml`. Here you can:
-- **Change the site title and logo**: Modify the `site` object.
-- **Add navigation links**: Add items to the `navbar.items` array.
-- **Structure your documentation**: Define the hierarchy of your content in the `sidebar.collections` object.
-For a complete guide on all available options, please refer to the documentation within your newly created project.
-## License
-This project is licensed under the [MIT License](LICENSE).
+English | [简体中文](README-zh.md)
+## create-react-docs-ui
+Scaffold a React documentation site in seconds, powered by [`react-docs-ui`](https://github.com/shenjianZ/react-docs-ui). Focus on writing Markdown; routing, theming, MDX, syntax highlighting, i18n, sidebar/TOC and a command menu are prewired.
+### Features
+- Configuration over code via `public/config/site.yaml`
+- MD/MDX rendering, syntax highlight, GFM, simple frontmatter parsing
+- Light/dark theme and command palette (Cmd/Ctrl+K)
+- Built-in i18n folders (e.g. `en`, `zh-cn`)
+- Ready-to-run Vite setup
+### Requirements
+- Node.js >= 18
+### Quick start
+- npm:
+```bash
+npm create react-docs-ui@latest my-docs
+```
+- yarn:
+```bash
+yarn create react-docs-ui my-docs
+```
+- pnpm:
+```bash
+pnpm create react-docs-ui my-docs
+```
+Then:
+```bash
+cd my-docs
+npm install
+npm run dev
+```
+Dev server runs at http://localhost:5173
+### Scripts (generated project)
+- `dev`: start Vite dev server
+- `build`: type-check and build
+- `preview`: preview production build
+### Project structure (generated)
+- `public/config/site.yaml` and `public/config/site.en.yaml`: site config per language
+- `public/docs/<lang>/**/*.md`: Markdown docs, matched by route slug
+- `src/`: app entry; usually no changes required
+### Config example (`public/config/site.yaml`)
+```yaml
+site:
+  logo: /logo.svg
+  title: My Docs
+  description: Awesome docs
+navbar:
+  showTitle: true
+  items:
+    - title: GitHub
+      link: https://github.com/shenjianZ/react-docs-ui
+      external: true
+sidebar:
+  collections:
+    guide:
+      sections:
+        - title: Getting Started
+          path: guide
+          children:
+            - { title: Introduction, path: guide/introduction }
+```
+### Docs example (`public/docs/en/guide/introduction.md`)
+```markdown
+---
+title: Introduction
+---
+# Introduction
+Welcome to My Docs!
+```
+### Links
+- Underlying UI library: `react-docs-ui` — https://github.com/shenjianZ/react-docs-ui
+### License
+[MIT](LICENSE)

package/package.json CHANGED Viewed

@@ -1,6 +1,6 @@
 {
   "name": "create-react-docs-ui",
-  "version": "0.1.4",
+  "version": "0.1.5",
   "private": false,
   "type": "module",
   "bin": {
@@ -19,7 +19,20 @@
     "template/vite.config.ts",
     "README.md"
   ],
-  "description": "Scaffold a React Docs UI project powered by react-docs-ui",
+  "description": "Scaffold a React documentation site with one command — built-in routing, theming, MDX, examples, and production-ready build config, powered by react-docs-ui.",
+  "homepage": "https://github.com/shenjianZ/create-react-docs-ui",
+  "keywords": [
+    "react",
+    "cli",
+    "scaffolding",
+    "starter",
+    "template",
+    "docs",
+    "documentation",
+    "mdx",
+    "boilerplate",
+    "create-tool"
+  ],
   "license": "MIT"
 }

package/template/index.html CHANGED Viewed

@@ -2,13 +2,14 @@
 <html lang="en">
   <head>
     <meta charset="UTF-8" />
+    <link rel="icon" type="image/svg+xml" href="/images/favicon.svg" />
     <meta name="viewport" content="width=device-width, initial-scale=1.0" />
-    <title>React Docs UI</title>
+    <title>Docs</title>
   </head>
   <body>
     <div id="root"></div>
     <script type="module" src="/src/main.tsx"></script>
   </body>
-  </html>
+</html>

package/template/public/config/site.en.yaml CHANGED Viewed

@@ -1,7 +1,7 @@
 # Website Configuration
 site:
-  title: "Vue Docs UI Example"
-  description: "Example documentation website built with Vue Docs UI"
+  title: "React Docs UI Example"
+  description: "Example documentation website built with React Docs UI"
   # Logo formats supported:
   # 1. emoji: "🤖"
   # 2. image URL: "https://example.com/logo.png"
@@ -10,7 +10,7 @@ site:
   logo:
     light: "/images/favicon.svg"
     dark: "/images/favicon-dark.svg"
-  author: "Vue Docs UI Team"
+  author: "React Docs UI Team"
 # Navigation Bar Configuration
 navbar:
@@ -25,7 +25,7 @@ navbar:
       link: "/guide"
   actions:
     - type: "github"
-      link: "https://github.com/shenjianZ/vue-docs-ui"
+      link: "https://github.com/shenjianZ/React-docs-ui"
       enabled: true
 # Sidebar Navigation Configuration
@@ -73,7 +73,7 @@ toc:
 # Footer Configuration
 footer:
   enabled: true
-  copyright: "© 2024 Vue Docs UI. All rights reserved."
+  copyright: "© 2024 React Docs UI. All rights reserved."
   repository:
     url: "https://github.com/your_github_id/your_repo_name"
     branch: "master"
@@ -130,8 +130,8 @@ footer:
 # PWA Configuration
 pwa:
   enabled: false
-  name: "Vue Docs UI"
-  shortName: "VueDocsUI"
+  name: "React Docs UI"
+  shortName: "ReactDocsUI"
   description: "Beautiful documentation websites made simple"
   themeColor: "#ffffff"
   backgroundColor: "#ffffff"

package/template/public/config/site.yaml CHANGED Viewed

@@ -1,7 +1,7 @@
 # 网站基本配置
 site:
-  title: "Vue Docs UI 示例项目"
-  description: "基于 Vue Docs UI 构建的文档网站示例"
+  title: "React Docs UI 示例项目"
+  description: "基于 React Docs UI 构建的文档网站示例"
   # logo支持以下格式：
   # 1. emoji: "🤖"
   # 2. 图片URL: "https://example.com/logo.png"
@@ -10,7 +10,7 @@ site:
   logo:
     light: "/images/favicon.svg"
     dark: "/images/favicon-dark.svg"
-  author: "Vue Docs UI Team"
+  author: "React Docs UI Team"
 # 顶部导航配置
 navbar:
@@ -25,7 +25,7 @@ navbar:
       link: "/guide"
   actions:
     - type: "github"
-      link: "https://github.com/shenjianZ/vue-docs-ui"
+      link: "https://github.com/shenjianZ/React-docs-ui"
       enabled: true
 # 侧边栏导航配置
@@ -73,7 +73,7 @@ toc:
 # Footer Configuration
 footer:
   enabled: true
-  copyright: "© 2024 Vue Docs UI. All rights reserved."
+  copyright: "© 2024 React Docs UI. All rights reserved."
   repository:
     url: "https://github.com/your_github_id/your_repo_name"
     branch: "master"
@@ -130,8 +130,8 @@ footer:
 # PWA Configuration
 pwa:
   enabled: true
-  name: "Vue Docs UI"
-  shortName: "VueDocsUI"
+  name: "React Docs UI"
+  shortName: "ReactDocsUI"
   description: "Beautiful documentation websites made simple"
   themeColor: "#ffffff"
   backgroundColor: "#ffffff"

package/template/public/docs/en/guide/configuration.md CHANGED Viewed

@@ -1,122 +1,149 @@
-# Configuration File (`site.yaml`) Explained
-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.
-## Top-Level Configuration Overview
-| Top-Level Field | Description |
-| :--- | :--- |
-| `site` | Global site information, such as title, description, and logo. |
-| `navbar` | Configures the top navigation bar of the website. |
-| `sidebar` | Configures the navigation menu in the website's sidebar. |
-| `theme` | Configures the website's theme, such as colors and light/dark mode. |
-| `footer` | Configures the footer information at the bottom of the website. |
-| `toc` | Configures the Table of Contents on the right side of article pages. |
----
-## `site`
-Basic metadata configuration for the website.
-| Field | Description | Example |
-| :--- | :--- | :--- |
-| `title` | The website title, displayed in the browser tab. | `"React Docs UI"` |
-| `description` | The website description, used for Search Engine Optimization (SEO). | `"A React documentation website builder"` |
-| `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 |
-| `author` | The author of the website. | `"React Docs UI Team"` |
-**Logo Format Guide:**
-1.  **Emoji**: Use an emoji directly, like `"🚀"`.
-2.  **Local Image**: A path to an image in the `public` directory, like `"/images/logo.png"`.
-3.  **Light/Dark Mode Images**: An object with `light` and `dark` keys, pointing to different image paths for each theme.
----
-## `navbar`
-Top navigation bar configuration.
-| Field | Description |
-| :--- | :--- |
-| `items` | An array of navigation items that defines all the links displayed in the navbar. |
-| `actions` | (Optional) Action buttons on the right side of the navbar, such as a GitHub link. |
-### `navbar.items`
-| Field | Description | Example |
-| :--- | :--- | :--- |
-| `title` | The display text for the navigation item. | `"Guide"` |
-| `link` | The link address. Internal links start with `/`. | `"/guide/introduction"` |
-| `external` | (Optional) If `true`, it's an external link that will open in a new tab. | `true` |
----
-## `sidebar`
-Sidebar navigation configuration, which is the core of the documentation structure. It uses `collections` to organize different sections of content.
-| Field | Description |
-| :--- | :--- |
-| `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. |
-### `sidebar.collections.<name>.sections`
-Each collection contains a `sections` array, where each `section` represents a collapsible menu group.
-| Field | Description | Example |
-| :--- | :--- | :--- |
-| `title` | The title of the section. | `"Getting Started"` |
-| `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"` |
-| `children` | An array of child links under this section. | |
-### `sidebar.collections.<name>.sections.children`
-| Field | Description | Example |
-| :--- | :--- | :--- |
-| `title` | The display text for the child link. | `"Introduction"` |
-| `path` | The full path to the child link, pointing to a specific Markdown page. | `"/guide/introduction"` |
----
-## `theme`
-Theme and appearance configuration.
-| Field | Description | Options | Default |
-| :--- | :--- | :--- | :--- |
-| `defaultMode` | The default theme mode for the website. | `'light'`, `'dark'`, `'system'` | `'system'` |
-| `allowToggle` | Whether to allow users to switch the theme. | `true`, `false` | `true` |
----
-## `footer`
-Footer configuration.
-| Field | Description | Example |
-| :--- | :--- | :--- |
-| `copyright` | Copyright information. `{year}` will be replaced with the current year. | `"Copyright © {year} My Company"` |
-| `repository` | (Optional) Repository information, used for displaying links like "Edit this page on GitHub". | |
-| `links` | (Optional) Additional link columns displayed in the footer. | |
-| `social` | (Optional) Social media icon links displayed in the footer. | |
-### `footer.repository`
-| Field | Description | Example |
-| :--- | :--- | :--- |
-| `url` | The URL of the repository. | `"https://github.com/user/repo"` |
-| `branch` | The Git branch where the documentation is located. | `"main"` |
-| `dir` | The root directory of the documentation files in the repository. | `"docs/src"` |
----
-## `toc` (Table of Contents)
-Configuration for the table of contents on the right side of article pages.
-| Field | Description | Example |
-| :--- | :--- | :--- |
-| `enabled` | Whether to enable the page table of contents feature. | `true` |
-| `maxLevel` | The maximum heading level (h1-h6) to display in the TOC. | `3` |
-| `title` | The title of the TOC component. | `"On this page"` |
+# Configuration File (`site.yaml`) Explained
+The project is configuration-driven. Most behavior is defined in `public/config/site.yaml`. This page documents every field using concise tables.
+## Top-level keys
+| Key | Purpose |
+| :-- | :-- |
+| `site` | Global metadata like title, description, logo, author |
+| `navbar` | Top navigation bar (logo/title toggles, items, actions) |
+| `sidebar` | Left navigation tree (collections/sections/children) |
+| `theme` | Theme options (default mode, toggle) |
+| `toc` | Article table of contents (enabled, levels, title) |
+| `footer` | Footer links, socials, repository meta |
+| `pwa` | Progressive Web App settings (reserved/optional) |
+---
+## `site`
+| Field | Type | Description | Example |
+| :-- | :-- | :-- | :-- |
+| `title` | string | Site title | `"React Docs UI Example"` |
+| `description` | string | Short site description (SEO) | `"Beautiful docs made simple"` |
+| `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" }` |
+| `author` | string | Site author/organization | `"React Docs UI Team"` |
+Logo formats supported:
+- Emoji: `"🚀"`
+- URL or public path: `"/images/logo.png"`
+- Light/Dark object: `{ light, dark }`
+---
+## `navbar`
+| Field | Type | Description |
+| :-- | :-- | :-- |
+| `showLogo` | boolean | Show logo at top-left |
+| `showTitle` | boolean | Show site title in navbar |
+| `showLanguageSwitcher` | boolean | Show language switcher |
+| `items` | array<Item> | Primary navigation links |
+| `actions` | array<Action> | Right-side action buttons (e.g. GitHub) |
+Item
+| Field | Type | Description | Example |
+| :-- | :-- | :-- | :-- |
+| `title` | string | Link text | `"Guide"` |
+| `link` | string | Path or URL. Internal paths start with `/`. | `"/guide"` |
+| `external` | boolean (optional) | Open in new tab if true |
+| `visible` | boolean (optional) | Conditionally hide/show |
+Action
+| Field | Type | Description | Example |
+| :-- | :-- | :-- | :-- |
+| `type` | `"github"` or `"custom"` (optional) | Predefined or custom action | `"github"` |
+| `title` | string (optional) | Button text when `type` is `custom` |
+| `link` | string | Destination URL |
+| `icon` | string (optional) | Icon name for custom action |
+| `enabled` | boolean (optional) | Toggle the action |
+---
+## `sidebar`
+| Field | Type | Description |
+| :-- | :-- | :-- |
+| `enabled` | boolean (optional) | Global toggle for sidebar |
+| `collections` | record<string, Collection> | Map of top-level sections (e.g. `guide`) |
+| `sections` | Section[] (legacy, optional) | Backward-compatible single-tree definition |
+Collection
+| Field | Type | Description |
+| :-- | :-- | :-- |
+| `sections` | Section[] | Grouped side-nav sections |
+Section
+| Field | Type | Description | Example |
+| :-- | :-- | :-- | :-- |
+| `title` | string | Section title | `"Getting Started"` |
+| `path` | string | Base path that expands/highlights this section | `"/guide"` |
+| `children` | Child[] (optional) | Leaf links under the section |
+Child
+| Field | Type | Description | Example |
+| :-- | :-- | :-- | :-- |
+| `title` | string | Link text | `"Introduction"` |
+| `path` | string | Full page path | `"/guide/introduction"` |
+---
+## `theme`
+| Field | Type | Description | Options | Default |
+| :-- | :-- | :-- | :-- | :-- |
+| `defaultMode` | string | Default color mode | `light`, `dark`, `auto` | `auto` |
+| `allowToggle` | boolean | Allow user theme switching | `true`/`false` | `true` |
+---
+## `toc`
+| Field | Type | Description | Example |
+| :-- | :-- | :-- | :-- |
+| `enabled` | boolean | Enable page table of contents | `true` |
+| `maxLevel` | number (1-6) | Max heading depth to show | `3` |
+| `title` | string | TOC panel title | `"On This Page"` |
+Note: Per-page TOC visibility/anchors are also affected by page frontmatter.
+---
+## `footer`
+| Field | Type | Description |
+| :-- | :-- | :-- |
+| `enabled` | boolean | Show footer |
+| `copyright` | string | Copyright text |
+| `repository` | Repository (optional) | Repo info used for links like “Edit this page” |
+| `lastUpdated` | string (optional) | Site/content last update date |
+| `links` | Link[] (optional) | Footer link columns |
+| `social` | Social[] (optional) | Social icon links |
+Repository
+| Field | Type | Description | Example |
+| :-- | :-- | :-- | :-- |
+| `url` | string | Repository URL | `"https://github.com/user/repo"` |
+| `branch` | string | Docs branch | `"main"` |
+Link
+| Field | Type | Description |
+| :-- | :-- | :-- |
+| `title` | string | Link title |
+| `link` | string | Path or URL |
+| `external` | boolean (optional) | Open in new tab |
+Social
+| Field | Type | Description |
+| :-- | :-- | :-- |
+| `name` | string | Provider key (e.g. `github`, `twitter`, `bilibili`) |
+| `url` | string | Profile or link URL |
+| `icon` | string | Icon name |
+---
+## `pwa` (optional)
+| Field | Type | Description |
+| :-- | :-- | :-- |
+| `enabled` | boolean | Enable PWA features (reserved) |
+| `name` | string | App name |
+| `shortName` | string | Short app name |
+| `description` | string | App description |
+| `themeColor` | string | Theme color |
+| `backgroundColor` | string | Background color |
+---

package/template/public/docs/en/guide/quick-start.md CHANGED Viewed

@@ -1,109 +1,108 @@
-# Quick Start
-This guide will walk you through creating, configuring, and running your own React documentation website from scratch in 5 minutes.
-## 1. Create the Project
-Using the official scaffolding tool is the most efficient way. Open your terminal and run the following command:
-```bash
-# This creates a project named "my-awesome-docs"
-npx create-react-docs-ui@latest my-awesome-docs
-```
-Next, enter the project directory and install the dependencies:
-```bash
-cd my-awesome-docs
-npm install
-```
-## 2. Organize Your Documents
-All your documentation content is stored as Markdown files in the `public/docs/` directory.
-- Open the `public/docs/en/` directory.
-- You can modify the existing `index.md` and files under the `guide` directory, or create new `.md` files.
-For example, let's create a new page. Create a new file named `about.md` in `public/docs/en/`:
-```markdown
----
-title: About Us
-description: This is a page about our team.
----
-# About Us
-We love open source and creation!
-```
-**Note**: You can use `frontmatter` at the top of your Markdown files to define the page `title` and `description`.
-## 3. Configure the Website
-Now, let's display the newly created page by modifying the configuration file.
-Open the core configuration file `public/config/site.yaml`.
-### a. Modify Site Information
-Update the `site` section to give your website a new title and logo.
-```yaml
-site:
-  title: "My Awesome Docs"
-  description: "A website built with React Docs UI"
-  logo: "🚀" # You can use an emoji or an image path
-```
-### b. Add to the Navbar
-In the `navbar.items` array, add a link for the "About" page. Remember to update the links for the English version.
-```yaml
-navbar:
-  items:
-    - title: "Home"
-      link: "/en/"
-    - title: "Guide"
-      link: "/en/guide/introduction"
-    - title: "About"  # New
-      link: "/en/about" # New
-```
-### c. Add to the Sidebar
-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.
-```yaml
-sidebar:
-  collections:
-    guide:
-      sections:
-        - title: "Getting Started"
-          path: "/en/guide"
-          children:
-            - title: "Introduction"
-              path: "/en/guide/introduction"
-            - title: "Installation"
-              path: "/en/guide/installation"
-            - title: "Quick Start"
-              path: "/en/guide/quick-start"
-        # You can create a new section for the "About" page
-        - title: "About Us"
-          path: "/en/about"
-          children:
-            - title: "About"
-              path: "/en/about"
-```
-## 4. Launch the Website
-Save all your changes and run the following command in your terminal:
-```bash
-npm run dev
-```
+# Quick Start
+This guide will walk you through creating, configuring, and running your own React documentation website from scratch in 5 minutes.
+## 1. Create the Project
+Using the official scaffolding tool is the most efficient way. Open your terminal and run the following command:
+```bash
+# This creates a project named "my-awesome-docs"
+npx create-react-docs-ui@latest my-awesome-docs
+```
+Next, enter the project directory and install the dependencies:
+```bash
+cd my-awesome-docs
+npm install
+```
+## 2. Organize Your Documents
+All your documentation content is stored as Markdown files in the `public/docs/` directory.
+- Open the `public/docs/en/` directory.
+- You can modify the existing `index.md` and files under the `guide` directory, or create new `.md` files.
+For example, let's create a new page. Create a new file named `about.md` in `public/docs/en/`:
+```markdown
+---
+title: About Us
+description: This is a page about our team.
+---
+# About Us
+We love open source and creation!
+```
+## 3. Configure the Website
+Now, let's display the newly created page by modifying the configuration file.
+Open the core configuration file `public/config/site.yaml`.
+### a. Modify Site Information
+Update the `site` section to give your website a new title and logo.
+```yaml
+site:
+  title: "My Awesome Docs"
+  description: "A website built with React Docs UI"
+  logo: "🚀" # You can use an emoji or an image path
+```
+### b. Add to the Navbar
+In the `navbar.items` array, add a link for the "About" page. Remember to update the links for the English version.
+```yaml
+navbar:
+  items:
+    - title: "Home"
+      link: "/en/"
+    - title: "Guide"
+      link: "/en/guide/introduction"
+    - title: "About"  # New
+      link: "/en/about" # New
+```
+### c. Add to the Sidebar
+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.
+```yaml
+sidebar:
+  collections:
+    guide:
+      sections:
+        - title: "Getting Started"
+          path: "/en/guide"
+          children:
+            - title: "Introduction"
+              path: "/en/guide/introduction"
+            - title: "Installation"
+              path: "/en/guide/installation"
+            - title: "Quick Start"
+              path: "/en/guide/quick-start"
+        # You can create a new section for the "About" page
+        - title: "About Us"
+          path: "/en/about"
+          children:
+            - title: "About"
+              path: "/en/about"
+```
+## 4. Launch the Website
+Save all your changes and run the following command in your terminal:
+```bash
+npm run dev
+```
 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!

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

@@ -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 CHANGED Viewed

@@ -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 的基本工作流程！