create-react-docs-ui 0.1.1 → 0.1.3

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2025 shenjianZ
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOTT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -0,0 +1,82 @@
+# 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).

package/package.json

@@ -1,11 +1,23 @@
 {
   "name": "create-react-docs-ui",
-  "version": "0.1.1",
+  "version": "0.1.3",
   "private": false,
   "type": "module",
   "bin": {
     "create-react-docs-ui": "./index.js"
   },
+  "files": [
+    "index.js",
+    "template/index.html",
+    "template/package.json",
+    "template/public/**/*",
+    "template/src/main.tsx",
+    "template/src/vite-env.d.ts",
+    "template/tsconfig.app.json",
+    "template/tsconfig.json",
+    "template/vite.config.ts",
+    "README.md"
+  ],
   "description": "Scaffold a React Docs UI project powered by react-docs-ui",
   "license": "MIT"
 }

package/template/package.json

@@ -1,6 +1,6 @@
 {
   "name": "my-react-docs-project",
-  "version": "0.0.0",
+  "version": "0.0.1",
   "private": true,
   "type": "module",
   "scripts": {
@@ -9,7 +9,7 @@
     "preview": "vite preview"
   },
   "dependencies": {
-    "react-docs-ui": "^0.1.0",
+    "react-docs-ui": "^0.1.3",
     "buffer": "^6.0.3",
     "react": ">=18",
     "react-dom": ">=18",

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

@@ -1,69 +1,122 @@
-# Configuration
-
-## Configuration Overview
-
-Vue Docs UI provides flexible configuration options that allow you to customize the appearance and behavior of your documentation website.
-
-## Basic Configuration
-
-### site.yaml File
-
-The configuration file is located at `public/config/site.yaml` and contains the following main sections:
-
-```yaml
-# Website Configuration
-site:
-  title: "Vue Docs UI"
-  description: "Beautiful documentation websites made simple"
-  logo: "📚"
-  author: "Vue Docs UI Team"
-```
-
-### Navigation Bar Configuration
-
-```yaml
-navbar:
-  items:
-    - title: "Home"
-      link: "/"
-      active: true
-    - title: "Documentation"
-      link: "/guide"
-```
-
-### Sidebar Configuration
-
-```yaml
-sidebar:
-  sections:
-    - title: "Getting Started"
-      path: "/guide"
-      children:
-        - title: "Introduction"
-          path: "/guide/introduction"
-```
-
-## Theme Configuration
-
-### Color Customization
-
-```yaml
-theme:
-  colors:
-    primary: "#3b82f6"
-    secondary: "#64748b"
-    accent: "#06b6d4"
-```
-
-### Font Configuration
-
-```yaml
-theme:
-  fonts:
-    primary: "Inter, -apple-system, BlinkMacSystemFont, sans-serif"
-    mono: "JetBrains Mono, Consolas, monospace"
-```
-
-## Advanced Configuration
-
-For more advanced configuration options, please refer to the related documentation. 
+# 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"` |

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

@@ -1,139 +1,63 @@
-# Installation
-
-Get Vue Docs UI up and running in your project with these simple steps.
-
-## Prerequisites
-Before you begin, make sure you have the following installed:
-
-- **Node.js** 14.18+ or 16+
-- **npm** 6+ or **yarn** 1.22+
-
-## Quick Start
-
-The fastest way to get started is using our CLI tool:
-
-```bash
-# Create a new project
-npm create vue-docs-ui@latest my-docs
-
-# Navigate to your project
-cd my-docs
-
-# Install dependencies
-npm install
-
-# Start the development server
-npm run dev
-```
-
-Your documentation website will be running at `http://localhost:5173`!
-
-## Manual Installation
-
-If you prefer to set up Vue Docs UI manually in an existing project:
-
-### 1. Install Vue Docs UI
-
-```bash
-npm install vue-docs-ui
-```
-
-### 2. Create Your App
-
-Create a `main.ts` file:
-
-```typescript
-import { createApp } from 'vue'
-import { createRouter, createWebHistory } from 'vue-router'
-import App from './App.vue'
-
-const router = createRouter({
-  history: createWebHistory(),
-  routes: [
-    { path: '/:pathMatch(.*)*', redirect: '/' }
-  ]
-})
-
-const app = createApp(App)
-app.use(router)
-app.mount('#app')
-```
-
-### 3. Create App Component
-
-Create an `App.vue` file:
-
-```vue
-<template>
-  <DocsLayout />
-</template>
-
-<script setup lang="ts">
-import { DocsLayout } from 'vue-docs-ui'
-import 'vue-docs-ui/style.css'
-</script>
-```
-
-### 4. Configure Your Site
-
-Create a `public/config/site.yaml` file with your site configuration:
-
-```yaml
-site:
-  title: "My Documentation"
-  description: "My awesome documentation website"
-  logo: "📚"
-  author: "Your Name"
-```
-
-### 5. Add Your Content
-
-Create your documentation files in the `public/docs/` directory as Markdown files.
-
-## Project Structure
-
-After installation, your project structure should look like this:
-
-```
-my-docs/
-├── public/
-│   ├── config/
-│   │   └── site.yaml
-│   └── docs/
-│       └── guide/
-│           └── introduction.md
-├── src/
-│   ├── App.vue
-│   └── main.ts
-├── index.html
-├── package.json
-└── vite.config.js
-```
-
-## Development
-
-Start the development server:
-
-```bash
-npm run dev
-```
-
-Your site will be available at `http://localhost:5173` with hot reload enabled.
-
-## Building for Production
-
-Build your documentation for production:
-
-```bash
-npm run build
-```
-
-The built files will be in the `dist/` directory, ready to deploy to any static hosting service.
-
-## Next Steps
-
-- [Quick Start Guide](/guide/quick-start) - Learn the basics
-- [Configuration](/guide/configuration) - Customize your site
-- [Examples](/examples) - See Vue Docs UI in action 
-
-
+# Installation
+
+## Prerequisites
+
+Before you begin, make sure your development environment meets the following requirements:
+
+- **Node.js**: Version `>= 18.0.0`
+- **Package Manager**: `npm`, `yarn`, or `pnpm`
+
+## Recommended Method: Use the Scaffolding Tool
+
+We strongly recommend using the official `create-react-docs-ui` scaffolding tool to create your new documentation project. This is the fastest and easiest way to ensure all configurations are set up correctly.
+
+1.  **Run the creation command**:
+    ```bash
+    npx create-react-docs-ui@latest my-docs
+    ```
+    This will create a new folder named `my-docs` in the current directory.
+
+2.  **Enter the project and install dependencies**:
+    ```bash
+    cd my-docs
+    npm install
+    ```
+
+3.  **Start the development server**:
+    ```bash
+    npm run dev
+    ```
+    Your documentation website is now running at `http://localhost:5173` (or another available port).
+
+## Manual Installation (for existing projects)
+
+If you want to manually integrate `react-docs-ui` into an existing Vite + React project, follow these steps:
+
+1.  **Install the core library**:
+    ```bash
+    npm install react-docs-ui
+    ```
+
+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).
+
+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`.
+
+4.  **Modify the application entry file**:
+    Update your `src/main.tsx` (or `main.jsx`) file to render the `DocsApp` component to initialize the application.
+
+    ```tsx
+    // src/main.tsx
+    import React from 'react'
+    import ReactDOM from 'react-dom/client'
+    import { DocsApp } from 'react-docs-ui'
+    import 'react-docs-ui/dist/style.css' // Import core styles
+
+    ReactDOM.createRoot(document.getElementById('root')!).render(
+      <React.StrictMode>
+        <DocsApp />
+      </React.StrictMode>,
+    )
+    ```
+5.  **Ensure your `index.html` contains `<div id="root"></div>`**

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

@@ -1,50 +1,28 @@
-# Introduction
-
-Welcome to **Vue Docs UI** - the simplest way to create beautiful documentation websites with Vue.js!
-
-## What is Vue Docs UI?
-
-Vue Docs UI is a modern, lightweight, and highly customizable documentation framework built with Vue 3 and TypeScript. It helps you create professional documentation websites with minimal setup and maximum flexibility.
-
-## Key Features
-
-### 🚀 **Quick Setup**
-Get started in minutes with zero configuration required.
-
-### 📱 **Responsive Design**
-Looks great on all devices - from mobile phones to desktop computers.
-
-### 🎨 **Customizable Themes**
-Built-in light and dark themes with full customization support.
-
-### 📝 **Markdown Support**
-Write your documentation in Markdown with enhanced features.
-
-### 🔍 **Built-in Search**
-Powerful search functionality to help users find content quickly.
-
-### ⚡ **Lightning Fast**
-Built with Vite for incredibly fast development and build times.
-
-## Why Vue Docs UI?
-
-- **Developer Friendly**: Simple API and intuitive configuration
-- **Production Ready**: Optimized for performance and SEO
-- **Extensible**: Easy to customize and extend with your own components
-- **Modern**: Built with the latest Vue 3 and TypeScript technologies
-
-## Getting Started
-
-Ready to create your first documentation website? Check out our [Installation Guide](/guide/installation) to get started in just a few minutes!
-
-## Community
-
-Join our growing community:
-
-- 🐛 [Report Issues](https://github.com/shenjianZ/vue-docs-ui/issues)
-- 💡 [Feature Requests](https://github.com/shenjianZ/vue-docs-ui/discussions)
-- 📖 [Documentation](https://github.com/shenjianZ/vue-docs-ui)
-
----
-
-*Happy documenting! 📚* 
+# Introduction
+
+React Docs UI is a React component library and toolset designed specifically for building modern documentation websites. Its core philosophy is **configuration over code**, allowing you to focus entirely on content creation.
+
+## Core Advantages
+
+- **Configuration-Driven**: This is the core feature of React Docs UI. You don't need to write complex React components or routing logic; just maintain a clear `site.yaml` file to define everything from the site's navigation and sidebar to its theme and footer.
+
+- **Fully-Featured**: Out-of-the-box, it provides everything a modern documentation website needs:
+  - Responsive layout
+  - Light/dark theme switching
+  - Markdown-based content rendering (with GFM and Frontmatter support)
+  - Built-in code syntax highlighting
+  - Quick command menu (Cmd+K)
+  - Internationalization support
+
+- **Extremely Simple to Start**: With the official `create-react-docs-ui` scaffolding tool, you can launch a fully functional documentation website in under a minute, without any complex environment setup.
+
+- **Highly Customizable**: While it works out-of-the-box, every part (like the logo, color scheme, navigation links, social media icons, etc.) can be deeply customized through the configuration file.
+
+## Use Cases
+
+Whether you are an individual developer or part of a team, React Docs UI is perfect for the following scenarios:
+
+- **Open Source Project Documentation**: Provide a professional and easy-to-maintain documentation site for your React project.
+- **Product Manuals**: Clearly present your product's features and usage guides.
+- **Team Knowledge Bases**: Build and share knowledge based on React technology within your team.
+- **Personal Blogs or Portfolios**: Organize and display your technical articles or projects in an elegant way.