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

create-react-docs-ui 0.1.4 → 0.1.6

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 (10) hide show

package/README-zh.md +85 -0
package/README.md +85 -82
package/package.json +17 -3
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/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!