react-docs-ui 0.1.0

package/dist/docs/en/guide/quick-start.md

@@ -0,0 +1,217 @@
+# Quick Start
+
+This guide will help you understand the basics of Vue Docs UI and get your documentation website up and running quickly.
+
+## Project Overview
+
+Vue Docs UI follows a simple file-based routing system. Your documentation is organized as:
+
+- **Configuration**: `public/config/site.yaml` - Site settings and navigation
+- **Content**: `public/docs/` - Markdown files for your documentation pages
+- **Assets**: `public/images/` - Images and other static assets
+
+## Writing Your First Page
+
+Let's create a simple documentation page:
+
+### 1. Create a Markdown File
+
+Create a new file at `public/docs/my-first-page.md`:
+
+```markdown
+# My First Page
+
+Welcome to my documentation! This is written in **Markdown**.
+
+## Features
+
+- Easy to write
+- Supports code syntax highlighting
+- Responsive design
+- Built-in search
+
+## Code Example
+
+## Lists and More
+
+1. Ordered lists work great
+2. With automatic numbering
+3. And proper styling
+
+- Unordered lists too
+- With bullet points
+- And consistent spacing
+```
+
+> **Tip**: Use blockquotes for important notes and tips!
+
+
+### 2. Add to Navigation
+
+Update your `public/config/site.yaml` to include the new page:
+
+```yaml
+sidebar:
+  sections:
+    - title: "Getting Started"
+      path: "/guide"
+      children:
+        - title: "My First Page"
+          path: "/my-first-page"
+```
+
+### 3. View Your Page
+
+Start the development server and navigate to your new page:
+
+```bash
+npm run dev
+```
+
+Visit `http://localhost:5173/my-first-page` to see your page!
+
+## Understanding Configuration
+
+The `site.yaml` file controls your entire site structure:
+
+### Site Settings
+```yaml
+site:
+  title: "Your Site Title"
+  description: "Site description for SEO"
+  logo: "📚"  # Emoji, image URL, or path
+  author: "Your Name"
+```
+
+### Navigation Bar
+```yaml
+navbar:
+  items:
+    - title: "Home"
+      link: "/"
+    - title: "GitHub"
+      link: "https://github.com/username/repo"
+      external: true
+```
+
+### Sidebar Navigation
+```yaml
+sidebar:
+  sections:
+    - title: "Section Name"
+      path: "/section"
+      children:
+        - title: "Page Title"
+          path: "/page-path"
+```
+
+## Markdown Features
+
+Vue Docs UI supports enhanced Markdown with:
+
+### Code Highlighting
+```javascript
+// JavaScript code is highlighted
+function greet(name) {
+  return `Hello, ${name}!`
+}
+```
+
+### Tables
+| Feature | Status | Description |
+|---------|--------|-------------|
+| Responsive | ✅ | Works on all devices |
+| Themes | ✅ | Light and dark mode |
+| Search | ✅ | Built-in search |
+
+### Math (Optional)
+If you need math equations, you can add support for LaTeX:
+
+Inline math: $E = mc^2$
+
+Block math:
+$$
+\int_{-\infty}^{\infty} e^{-x^2} dx = \sqrt{\pi}
+$$
+
+## Customizing Appearance
+
+### Theme Colors
+Customize your site's colors in `site.yaml`:
+
+```yaml
+theme:
+  colors:
+    primary: "#3b82f6"    # Main brand color
+    secondary: "#64748b"  # Secondary text
+    accent: "#06b6d4"     # Accent color
+```
+
+### Fonts
+```yaml
+theme:
+  fonts:
+    primary: "Inter, -apple-system, BlinkMacSystemFont, sans-serif"
+    mono: "JetBrains Mono, Consolas, monospace"
+```
+
+## Adding Images
+
+Place images in `public/images/` and reference them in your Markdown:
+
+```markdown
+![Logo](/images/logo.png)
+```
+
+Or with custom sizing:
+```markdown
+<img src="/images/screenshot.png" alt="Screenshot" width="600">
+```
+
+## Best Practices
+
+### 1. Organize Your Content
+```
+public/docs/
+├── guide/
+│   ├── introduction.md
+│   ├── installation.md
+│   └── quick-start.md
+├── api/
+│   ├── components.md
+│   └── utilities.md
+└── examples/
+    ├── basic.md
+    └── advanced.md
+```
+
+### 2. Use Descriptive Titles
+- Good: "Setting up Authentication"
+- Bad: "Auth Setup"
+
+### 3. Add Table of Contents
+Enable TOC in your `site.yaml`:
+
+```yaml
+toc:
+  enabled: true
+  maxLevel: 3
+  title: "On This Page"
+```
+
+### 4. Link Between Pages
+Use relative links to connect your content:
+
+```markdown
+Check out our [Installation Guide](/guide/installation) for setup instructions.
+```
+
+## What's Next?
+
+Now that you understand the basics:
+
+1. **[Configuration](/guide/configuration)** - Learn about all available options
+2. **[Advanced Features](/advanced/customization)** - Customize your site further
+3. **[Deployment](/advanced/deployment)** - Deploy your site to production
+
+Happy documenting! 🚀 

package/dist/docs/en/guide.md

@@ -0,0 +1,31 @@
+# Getting Started
+
+## Getting Started with Vue Docs UI
+
+Welcome to Vue Docs UI! This is a modern documentation website building tool based on Vue 3.
+
+## Quick Overview
+
+Vue Docs UI enables you to:
+- 🚀 **Quick Start** - Create beautiful documentation websites with just a few lines of code
+- 📱 **Responsive Design** - Perfect adaptation to all devices
+- 🎨 **Highly Customizable** - Flexible theme and style configuration
+- 📝 **Markdown Support** - Use familiar Markdown syntax
+
+## Learning Path
+
+### [📖 Introduction](/guide/introduction)
+Learn about Vue Docs UI's core concepts and features
+
+### [⚡ Installation](/guide/installation)
+Learn how to install and set up Vue Docs UI
+
+### [🏃‍♂️ Quick Start](/guide/quick-start)
+Get hands-on experience through practical examples
+
+### [⚙️ Configuration](/guide/configuration)
+Deep dive into configuration options and customization methods
+
+## Ready to Start?
+
+Choose any of the topics above to begin your learning journey, or jump directly to [Quick Start](/guide/quick-start) to experience it immediately! 

package/dist/docs/en/index.md

@@ -0,0 +1,58 @@
+# Welcome to Vue Docs UI
+
+Vue Docs UI is a modern documentation website builder based on Vue 3, providing an out-of-the-box documentation solution.
+
+## 🌟 Key Features
+
+- **🚀 Ready to Use** - Launch your documentation website with just 3 lines of code
+- **🎨 Modern Design** - Beautiful interface design with light/dark theme support
+- **📱 Mobile Responsive** - Perfect responsive design
+- **🌐 Internationalization** - Built-in multi-language support
+- **🤖 AI Assistant** - Integrated AI chat assistant with multiple model support
+- **⚡ High Performance** - Built with Vite for fast hot reload
+- **🔍 Full-text Search** - Smart search functionality
+- **📝 Enhanced Markdown** - Rich Markdown extensions
+
+## 🏗️ Architecture Features
+
+- **Component-based Design** - Modular components, easy to extend
+- **TypeScript Support** - Complete type support
+- **Customizable Themes** - Flexible theme configuration
+- **Plugin System** - Extensible plugin architecture
+
+## 📦 Quick Start
+
+```bash
+# Create new project
+npm create vue-docs-ui@latest my-docs
+
+# Navigate to project directory
+cd my-docs
+
+# Install dependencies
+npm install
+
+# Start development server
+npm run dev
+```
+
+## 📖 Usage
+
+```javascript
+import { createDocsApp } from 'vue-docs-ui'
+import 'vue-docs-ui/dist/vue-docs-ui.css'
+
+createDocsApp({
+  configPath: '/config/site.yaml',
+  el: '#app'
+})
+```
+
+It's that simple! No complex configuration needed, get a fully functional documentation website immediately.
+
+## 🔗 Related Links
+
+- [GitHub Repository](https://github.com/shenjianZ/vue-docs-ui)
+- [Online Demo](https://vue-docs-ui.example.com)
+- [User Guide](/guide/introduction)
+- [API Documentation](/advanced/api) 

package/dist/docs/zh-cn/guide/configuration.md

@@ -0,0 +1,169 @@
+# 配置文件 (`site.yaml`) 详解
+
+`vue-docs-ui` 的核心是其**配置驱动**的理念。你几乎可以通过 `public/config/site.yaml` 这一个文件来定义整个网站的外观和行为。本文档将详细解释每个配置项。
+
+## 顶级配置项概览
+
+| 顶级字段 | 说明 |
+| :--- | :--- |
+| `site` | 网站的全局信息，如标题、描述、Logo。 |
+| `navbar` | 配置网站顶部的导航栏。 |
+| `sidebar` | 配置网站侧边栏的导航菜单。 |
+| `theme` | 配置网站的主题，如颜色、浅色/深色模式。 |
+| `footer` | 配置网站底部的页脚信息。 |
+| `toc` | 配置文章页面右侧的目录（Table of Contents）。 |
+| `search` | 配置内置的全文搜索功能。 |
+| `pwa` | 配置渐进式Web应用（PWA）相关设置。 |
+| `ai` | 配置 AI 助手功能。 |
+
+---
+
+## `site`
+
+网站的基础元数据配置。
+
+| 字段 | 说明 | 示例 |
+| :--- | :--- | :--- |
+| `title` | 网站标题，显示在浏览器标签页上。 | `"Vue Docs UI"` |
+| `description` | 网站描述，用于搜索引擎优化 (SEO)。 | `"一个 Vue 3 文档网站构建工具"` |
+| `logo` | 网站 Logo，显示在导航栏左上角。 | `"📚"` 或 `"/images/logo.png"` |
+| `author` | 网站作者。 | `"Vue Docs UI Team"` |
+
+**Logo 格式说明:**
+1.  **Emoji**: 直接使用一个表情符号，如 `"🚀"`。
+2.  **本地图片**: 指向 `public` 目录下的图片路径，如 `"/images/logo.png"`。
+3.  **外部图片 URL**: 一个完整的图片链接。
+
+---
+
+## `navbar`
+
+顶部导航栏配置。
+
+| 字段 | 说明 |
+| :--- | :--- |
+| `items` | 导航项数组，定义了导航栏中显示的所有链接。 |
+
+### `navbar.items`
+
+| 字段 | 说明 | 示例 |
+| :--- | :--- | :--- |
+| `title` | 导航项的显示文本。 | `"指南"` |
+| `link` | 链接地址。内部链接以 `/` 开头。 | `"/guide/introduction"` |
+| `external` | (可选) `true` 表示为外部链接，将在新标签页打开。 | `true` |
+
+---
+
+## `sidebar`
+
+侧边栏导航配置，是文档结构的核心。
+
+| 字段 | 说明 |
+| :--- | :--- |
+| `sections` | 侧边栏区域数组，每个区域代表一个可折叠的菜单组。 |
+
+### `sidebar.sections`
+
+| 字段 | 说明 | 示例 |
+| :--- | :--- | :--- |
+| `title` | 区域的标题。 | `"入门指南"` |
+| `path` | 区域的基础路径。当用户访问的 URL 以此路径开头时，该区域会自动展开并高亮。 | `"/guide"` |
+| `children` | 该区域下的子链接数组。 | |
+
+### `sidebar.sections.children`
+
+| 字段 | 说明 | 示例 |
+| :--- | :--- | :--- |
+| `title` | 子链接的显示文本。 | `"介绍"` |
+| `path` | 子链接的完整路径，指向一个具体的 Markdown 页面。 | `"/guide/introduction"` |
+
+---
+
+## `theme`
+
+主题和外观配置。
+
+| 字段 | 说明 | 可选值 | 默认值 |
+| :--- | :--- | :--- | :--- |
+| `defaultMode` | 网站的默认主题模式。 | `'light'`, `'dark'`, `'auto'` | `'auto'` |
+| `allowToggle` | 是否允许用户切换主题。 | `true`, `false` | `true` |
+| `primaryColor`| 网站的主题色。 | CSS 颜色值 | `"#3b82f6"` |
+
+---
+
+## `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"` |
+
+### `footer.social`
+
+| 字段 | 说明 | 示例 |
+| :--- | :--- | :--- |
+| `name` | 社交媒体名称，用于 `aria-label`。 | `"GitHub"` |
+| `url` | 链接地址。 | `"https://github.com/user"` |
+| `icon` | 图标标识符，支持 `github`, `twitter`, `discord` 等。 | `"github"` |
+
+---
+
+## `toc` (Table of Contents)
+
+文章页面右侧的目录配置。
+
+| 字段 | 说明 | 示例 |
+| :--- | :--- | :--- |
+| `enabled` | 是否启用页面目录功能。 | `true` |
+| `maxLevel` | 在目录中显示的最大标题级别（h1-h6）。 | `3` |
+| `title` | 目录组件的标题。 | `"本页内容"` |
+
+---
+
+## `search`
+
+内置搜索功能配置。
+
+| 字段 | 说明 | 示例 |
+| :--- | :--- | :--- |
+| `enabled` | 是否启用搜索功能。 | `true` |
+| `placeholder` | 搜索框的占位文本。 | `"搜索文档..."` |
+
+---
+
+## `pwa`
+
+渐进式Web应用配置。
+
+| 字段 | 说明 | 示例 |
+| :--- | :--- | :--- |
+| `enabled` | 是否启用 PWA 功能。 | `true` |
+| `name` | PWA 的完整名称。 | `"Vue Docs UI"` |
+| `shortName` | PWA 的短名称。 | `"VueDocs"` |
+
+---
+
+## `ai`
+
+AI 助手配置。
+
+| 字段 | 说明 | 示例 |
+| :--- | :--- | :--- |
+| `enabled` | 是否启用 AI 助手功能。 | `true` |
+| `buttonTitle` | 浮动按钮的标题。 | `"AI 助手"` |
+| `modalTitle` | 对话框的标题。 | `"与 AI 对话"` |
+| `placeholder` | 输入框的占位文本。 | `"向我提问..."` |
+
+**注意**: AI 功能的 `provider` 和 `apiKey` 等敏感信息在 `public/config/ai.json` 中单独配置，以避免意外泄露。

package/dist/docs/zh-cn/guide/installation.md

@@ -0,0 +1,66 @@
+# 安装
+
+## 环境要求
+
+在开始之前，请确保你的开发环境满足以下要求：
+
+- **Node.js**: 版本 `>= 18.0.0`
+- **包管理器**: `npm`、`yarn` 或 `pnpm`
+
+## 推荐方式：使用脚手架
+
+我们强烈推荐使用官方的 `create-vue-docs-ui` 脚手架来创建你的新文档项目。这是最快、最简单的方式，可以确保所有配置都已就绪。
+
+1.  **运行创建命令**:
+    ```bash
+    npm create vue-docs-ui@latest my-docs
+    ```
+    这会在当前目录下创建一个名为 `my-docs` 的新文件夹。
+
+2.  **进入项目并安装依赖**:
+    ```bash
+    cd my-docs
+    npm install
+    ```
+
+3.  **启动开发服务器**:
+    ```bash
+    npm run dev
+    ```
+    现在，你的文档网站已经运行在 `http://localhost:5173` 上了。
+
+## 手动安装 (适用于现有项目)
+
+如果你想在已有的 Vite + Vue 3 项目中手动集成 `vue-docs-ui`，可以按照以下步骤操作：
+
+1.  **安装核心库**:
+    ```bash
+    npm install vue-docs-ui
+    ```
+
+2.  **创建配置文件**:
+    在你的 `public` 目录下创建一个 `config` 文件夹，并在其中新建一个 `site.yaml` 文件。你可以从[这里](https://github.com/shenjianZ/vue-docs-ui/blob/main/vue-docs-ui/public/config/site.yaml)复制一个基础模板。
+
+3.  **创建文档目录**:
+    在 `public` 目录下创建一个 `docs` 文件夹，用于存放你的 Markdown 文件。
+
+4.  **修改应用入口文件**:
+    更新你的 `src/main.ts` (或 `main.js`) 文件，使用 `createDocsApp` 来初始化应用。
+
+    ```typescript
+    // src/main.ts
+    import { createApp } from 'vue'
+    import { createDocsApp } from 'vue-docs-ui'
+    import 'vue-docs-ui/dist/style.css' // 引入核心样式
+
+    // 移除原有的 createApp(App).mount('#app')
+    
+    createDocsApp({
+      // el 是挂载点，必须与 index.html 中的 id 一致
+      el: '#app',
+      // configPath 指向你的主配置文件
+      configPath: '/config/site.yaml',
+      // aiConfigPath 是可选的 AI 助手配置
+      aiConfigPath: '/config/ai.json' 
+    })
+    ```

package/dist/docs/zh-cn/guide/introduction.md

@@ -0,0 +1,29 @@
+# 介绍
+
+Vue Docs UI 是一个专为构建现代化文档网站而设计的 Vue 3 组件库与工具集。它的核心哲学是**配置优于编码**，让你能将精力完全集中在内容创作上。
+
+## 核心优势
+
+- **配置驱动**: 这是 Vue Docs UI 最核心的特性。你不需要编写 Vue 组件或复杂的路由逻辑，只需维护一个清晰的 `site.yaml` 文件，就能定义网站的导航、侧边栏、主题、页脚等所有内容。
+
+- **功能完备**: 开箱即用，提供了现代文档网站所需的一切：
+  - 响应式布局
+  - 明暗主题切换
+  - 基于 Markdown 的内容渲染
+  - 代码语法高亮
+  - 内置全文搜索
+  - PWA (渐进式Web应用) 支持
+  - 可选的 AI 问答助手
+
+- **极简上手**: 通过官方的 `create-vue-docs-ui` 脚手架，你可以在一分钟内启动一个功能齐全的文档网站，无需任何复杂的环境配置。
+
+- **高度可定制**: 虽然开箱即用，但每个部分（如 Logo、配色、导航链接、社交媒体图标等）都可以通过配置文件进行深度定制。
+
+## 适用场景
+
+无论你是个人开发者还是团队，Vue Docs UI 都非常适合以下场景：
+
+- **开源项目文档**: 为你的项目提供一个专业、易于维护的文档网站。
+- **产品手册**: 清晰地展示你的产品功能和使用指南。
+- **团队知识库**: 在团队内部沉淀和分享知识。
+- **个人博客或作品集**: 以优雅的方式组织和展示你的技术文章或项目。

package/dist/docs/zh-cn/guide/quick-start.md

@@ -0,0 +1,100 @@
+# 快速上手
+
+本指南将引导你在 5 分钟内，从零开始创建、配置并运行一个属于你自己的文档网站。
+
+## 1. 创建项目
+
+使用官方脚手架是最高效的方式。打开你的终端，运行以下命令：
+
+```bash
+# 这会创建一个名为 "my-awesome-docs" 的项目
+npm create vue-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
+# 关于我们
+
+这是一个关于我们团队的页面。
+我们热爱开源和创造！
+```
+
+## 3. 配置网站
+
+现在，让我们通过修改配置文件来展示新创建的页面。
+
+打开核心配置文件 `public/config/site.yaml`。
+
+### a. 修改网站信息
+
+更新 `site` 部分，给你的网站一个新标题和 Logo。
+
+```yaml
+site:
+  title: "我的超赞文档"
+  description: "一个使用 Vue 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.sections` 中添加一个新区域。
+
+```yaml
+sidebar:
+  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"
+    - title: "关于我们" # 新增区域
+      path: "/zh-cn/about" # 新增区域
+      children: # 新增区域
+        - title: "关于" # 新增区域
+          path: "/zh-cn/about" # 新增区域
+```
+
+## 4. 启动网站
+
+保存你的所有修改，然后在终端运行：
+
+```bash
+npm run dev
+```
+
+你的网站现在应该运行在 `http://localhost:5173` 上了。访问它，你会看到更新后的标题、Logo，以及导航栏和侧边栏中新增的“关于”链接。恭喜你，你已经成功掌握了 Vue Docs UI 的基本工作流程！

package/dist/docs/zh-cn/guide.md

@@ -0,0 +1,10 @@
+# 指南
+
+本指南将帮助你全面了解并掌握 Vue Docs UI 的各项功能。无论你是初学者还是希望进行深度定制，都能在这里找到所需的信息。
+
+## 目录
+
+- **[介绍](/guide/introduction)**: 了解 Vue Docs UI 的核心理念和主要优势。
+- **[安装](/guide/installation)**: 学习如何通过脚手架或手动方式安装。
+- **[快速上手](/guide/quick-start)**: 在 5 分钟内创建并运行你的第一个文档网站。
+- **[配置说明 (`site.yaml`)](/guide/configuration)**: 深入了解每个配置项，完全掌控你的网站。