create-react-docs-ui 0.2.0 → 0.4.0

package/template/public/docs/en/{guide → docs/guide}/configuration.md

@@ -1,149 +1,195 @@
-# 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 |
-
----
+# 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 |
+| `contextMenu` | Context menu configuration |
+| `mdx` | MDX component configuration |
+| `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 |
+
+---
+
+## `contextMenu`
+| Field | Type | Description |
+| :-- | :-- | :-- |
+| `enabled` | boolean | Global switch, set to false to completely disable context menu |
+| `page` | object | Page group menu items configuration |
+| `site` | object | Site group menu items configuration |
+| `appearance` | object | Appearance group menu items configuration |
+
+Page
+| Field | Type | Description | Default |
+| :-- | :-- | :-- | :-- |
+| `copySelectedText` | boolean | Copy selected text | `true` |
+| `copyUrl` | boolean | Copy current URL | `true` |
+| `copyTitle` | boolean | Copy page title | `false` |
+| `copyMarkdownLink` | boolean | Copy Markdown link | `false` |
+| `openInNewTab` | boolean | Open in new tab | `false` |
+| `reload` | boolean | Refresh | `true` |
+| `printPage` | boolean | Print page | `true` |
+| `scrollToTop` | boolean | Scroll to top | `true` |
+| `scrollToBottom` | boolean | Scroll to bottom | `true` |
+
+Site
+| Field | Type | Description | Default |
+| :-- | :-- | :-- | :-- |
+| `goHome` | boolean | Go to home | `true` |
+| `quickNav` | boolean | Quick navigation | `false` |
+| `language` | boolean | Language switch | `false` |
+
+Appearance
+| Field | Type | Description | Default |
+| :-- | :-- | :-- | :-- |
+| `theme` | boolean | Theme switch | `false` |
+| `resetThemePref` | boolean | Reset theme preference | `false` |
+
+---
+
+## `mdx`
+| Field | Type | Description | Example |
+| :-- | :-- | :-- | :-- |
+| `componentsPath` | string | Component scan path | `"/src/components"` |
+| `enabled` | boolean | Enable MDX support | `true` |
+
+---
+
+## `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 → docs/guide}/installation.md

@@ -39,7 +39,7 @@ If you want to manually integrate `react-docs-ui` into an existing Vite + React
     ```
 
 2.  **Create configuration files**:
-    In your `public` directory, create a `config` folder, and inside it, create a `site.yaml` file. You can copy a basic template from [here](https://github.com/shenjianZ/react-docs-ui/blob/main/react-docs-ui/public/config/site.yaml).
+    In your `public` directory, create a `config` folder, and inside it, create a `site.yaml` file. You can copy a basic template from [here](https://github.com/shenjianZ/create-vue-docs-ui/blob/master/template/public/config/site.en.yaml).
 
 3.  **Create the documentation directory**:
     In your `public` directory, create a `docs` folder to store your Markdown files. For example: `public/docs/en/index.md`.
@@ -60,4 +60,4 @@ If you want to manually integrate `react-docs-ui` into an existing Vite + React
       </React.StrictMode>,
     )
     ```
-5.  **Ensure your `index.html` contains `<div id="root"></div>`**
+5.  **Ensure your `index.html` contains `<div id="root"></div>`**

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

@@ -0,0 +1,96 @@
+# Quick Start
+
+This guide will walk you through creating, configuring, and running your own React documentation website from scratch in 5 minutes.
+
+## 1. Create Project
+
+Using the official scaffold is the most efficient way. Open your terminal and run the following command:
+
+```bash
+# This will create a project named "my-awesome-docs"
+npx create-react-docs-ui@latest my-awesome-docs
+```
+
+Then, navigate to the project directory and install dependencies:
+
+```bash
+cd my-awesome-docs
+npm install
+```
+
+## 2. Organize Your Documentation
+
+All 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 in the `guide` directory, or create new `.md` files.
+
+For example, let's create a new page. Create an `about` directory and an `about.md` file in `public/docs/en/` with the following content:
+
+```markdown
+
+# About Us
+
+We love open source and creating!
+
+```
+
+
+## 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.en.yaml`.
+
+### a. Modify Website 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 emoji or image path
+```
+
+### b. Add to Navigation Bar
+
+Add a link for the "About" page in the `navbar.items` array.
+
+```yaml
+navbar:
+  items:
+    - title: "Home"
+        link: "/"
+        active: true
+    - title: "Docs"
+        link: "/docs"
+    - title: "About"  # New
+        link: "/about" # New
+```
+
+### c. Add to Sidebar
+
+To make the "About" page visible in the sidebar as well, create a new `sidebar.collections.about.sections` and add a new entry.
+
+```yaml
+sidebar:
+  collections:
+    about:
+      sections:
+        # You can create a new section for the "About" page
+        - title: "About Us"
+          path: "/about/about"
+```
+
+Here, the about item in the sidebar also needs to create a file `about.md` under `public/docs/en/about`
+
+## 4. Launch the Website
+
+Save all your changes, then run in the 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 newly added "About" link in the navigation bar and sidebar. Congratulations, you have successfully mastered the basic workflow of React Docs UI!

package/template/public/docs/en/docs/guide.md

@@ -0,0 +1,10 @@
+# Guide
+
+This guide will help you fully understand and master all the features of React Docs UI. Whether you are a beginner or looking for in-depth customization, you will find the information you need here.
+
+## Table of Contents
+
+- **[Introduction](/docs/guide/introduction)**: Learn about the core philosophy and main advantages of React Docs UI.
+- **[Installation](/docs/guide/installation)**: Learn how to install via the scaffolding tool or manually.
+- **[Quick Start](/docs/guide/quick-start)**: Create and run your first documentation website in 5 minutes.
+- **[Configuration (`site.yaml`)](/docs/guide/configuration)**: Dive deep into each configuration option to take full control of your site.