Vue Docs UI

中文文档

A modern, feature-rich documentation UI component library built with Vue 3. Create beautiful documentation websites with YAML configuration and Markdown rendering - ready to use out of the box.

✨ Features

• 🎨 Modern Design: Grid-based responsive layout with beautiful UI
• 📱 Mobile Optimized: Perfect mobile experience with touch-friendly navigation
• 🌈 Multi-Theme System: 6 beautiful preset themes (Default, Vue, GitHub, Purple, Orange, Emerald)
• 🌙 Smart Theme Mode: Light/dark mode with auto system preference detection
• 📖 Markdown Rendering: Complete Markdown support with syntax highlighting
• 🔍 Auto Navigation: Automatic table of contents generation
• ⚙️ YAML Configuration: Configuration-driven approach with YAML files
• 🚀 Zero Setup: Get started with just 3 lines of code
• 📊 TypeScript: Full TypeScript support with type definitions
• 🎯 Vue 3: Built for Vue 3 with Composition API
• 🔧 Highly Customizable: Flexible theming and component customization

🚀 Quick Start

Option 1: Use Scaffolding Tool (Recommended)

1# Create a new documentation project with one command
2npm create vue-docs-ui my-docs
3cd my-docs
4npm install
5npm run dev

Option 2: Manual Installation

1npm install vue-docs-ui
2# or
3yarn add vue-docs-ui
4# or
5pnpm add vue-docs-ui

Basic Usage (3 lines of code!)

1// main.ts
2import createDocsApp from 'vue-docs-ui'
3import 'vue-docs-ui/dist/style.css'
4
5createDocsApp()

Configuration File

Create public/config/site.yaml:

1# Basic site configuration
2site:
3  title: "My Documentation"
4  description: "Built with Vue Docs UI"
5  logo: "📚"  # Supports emoji, images, or URLs
6  author: "Your Name"
7
8# Navigation
9navbar:
10  items:
11    - title: "Home"
12      link: "/"
13    - title: "Guide"
14      link: "/guide"
15    - title: "GitHub"
16      link: "https://github.com/your-repo"
17      external: true
18
19# Sidebar
20sidebar:
21  sections:
22    - title: "Getting Started"
23      path: "/guide"
24      children:
25        - title: "Quick Start"
26          path: "/guide/quick-start"
27        - title: "Configuration"
28          path: "/guide/configuration"
29
30# Theme (NEW: Multi-theme support!)
31theme:
32  # Theme selection: default | vue | github | purple | orange | emerald
33  theme: "vue"
34  
35  # Default mode: light | dark | auto
36  defaultMode: "auto"
37  
38  # Allow users to toggle theme
39  allowToggle: true
40  
41  # Show theme switcher component
42  showThemeSwitcher: true
43
44# Table of Contents
45toc:
46  maxLevel: 2
47  enabled: true
48  title: "Contents"

Add Markdown Content

Create your markdown files in public/docs/:

public/
├── config/
│   └── site.yaml
└── docs/
    ├── guide/
    │   ├── quick-start.md
    │   └── configuration.md
    └── advanced/
        └── customization.md

That's it! 🎉 Run npm run dev and your documentation site is ready.

📦 What's Included

• DocsLayout: Main layout component with responsive design
• HeaderNav: Top navigation with theme toggle and mobile menu
• SidebarNav: Collapsible sidebar navigation
• TableOfContents: Auto-generated table of contents
• MarkdownRenderer: Markdown rendering with syntax highlighting
• DefaultHome: Beautiful homepage component
• DefaultArticle: Article page with breadcrumbs and navigation

🎯 Logo Configuration

Vue Docs UI supports multiple logo formats:

1site:
2  # Emoji (simplest)
3  logo: "🤖"
4  
5  # Local image
6  logo: "/images/logo.png"
7  
8  # Online image
9  logo: "https://example.com/logo.svg"
10  
11  # Relative path
12  logo: "./assets/logo.svg"

Logo Requirements:

• Recommended formats: PNG, SVG (vector graphics preferred)
• Recommended size: 32-64px height, auto width
• File size: < 100KB recommended
• Supported formats: PNG, SVG, JPG, GIF, WebP, ICO

🎨 Multi-Theme System (NEW!)

Vue Docs UI now supports 6 beautiful preset themes with complete configuration control:

Available Themes

Theme	Description	Best for
default	Modern blue theme	General documentation
vue	Vue.js official green theme	Vue projects
github	GitHub-style monochrome	Open source projects
purple	Elegant purple theme	Design systems
orange	Warm orange theme	Marketing sites
emerald	Fresh green theme	Eco-friendly projects

Basic Theme Configuration

1theme:
2  # Select theme: default | vue | github | purple | orange | emerald
3  theme: "vue"
4  
5  # Default mode: light | dark | auto
6  defaultMode: "auto"
7  
8  # Allow users to toggle theme/mode
9  allowToggle: true
10  
11  # Show theme switcher component
12  showThemeSwitcher: true

Theme Mode Options

• "light": Force light mode
• "dark": Force dark mode
• "auto": Auto-detect system preference (recommended)

Theme Control Options

• allowToggle: true: Users can switch themes and modes
• allowToggle: false: Lock theme configuration
• showThemeSwitcher: true: Show theme picker in header
• showThemeSwitcher: false: Hide theme picker

Configuration Priority

1. User Selection (localStorage)
2. Config File (site.yaml)
3. System Preference (for auto mode)
4. Default Values

Example Configurations

Fixed Theme Mode:

1theme:
2  theme: "github"
3  defaultMode: "light"
4  allowToggle: false
5  showThemeSwitcher: false

Full User Control:

1theme:
2  theme: "default"
3  defaultMode: "auto"
4  allowToggle: true
5  showThemeSwitcher: true

Brand Specific:

1theme:
2  theme: "vue"          # Vue theme for Vue projects
3  defaultMode: "auto"
4  allowToggle: true
5  showThemeSwitcher: true

🔧 Advanced Usage

Custom Components

1import createDocsApp from 'vue-docs-ui'
2import 'vue-docs-ui/dist/style.css'
3import MyCustomHome from './MyCustomHome.vue'
4import MyCustomArticle from './MyCustomArticle.vue'
5
6createDocsApp({
7  configPath: '/config/site.yaml',
8  el: '#app',
9  customComponents: {
10    home: MyCustomHome,
11    article: MyCustomArticle
12  }
13})

Component Library Mode

1import { createApp } from 'vue'
2import { DocsLayout, loadConfig } from 'vue-docs-ui'
3import 'vue-docs-ui/dist/style.css'
4
5const config = await loadConfig('/config/site.yaml')
6const app = createApp(DocsLayout, { config })
7app.mount('#app')

Available Components

1import {
2  DocsLayout,
3  HeaderNav,
4  SidebarNav,
5  TableOfContents,
6  MarkdownRenderer,
7  DefaultHome,
8  DefaultArticle,
9  createDocsApp,
10  loadConfig
11} from 'vue-docs-ui'

📱 Responsive Design

Vue Docs UI is fully responsive:

• Desktop: Full sidebar + content + table of contents
• Tablet: Sidebar + content (TOC hidden)
• Mobile: Overlay sidebar with smooth animations

🔍 Markdown Features

• ✅ Standard Markdown syntax
• ✅ Syntax highlighting for code blocks
• ✅ Auto-generated table of contents
• ✅ Responsive tables and images
• ✅ Custom heading anchors
• ✅ Math equations support (coming soon)

📁 Project Structure

my-docs-project/
├── public/
│   ├── config/
│   │   └── site.yaml        # Site configuration
│   └── docs/               # Markdown content
│       ├── guide/
│       │   ├── quick-start.md
│       │   └── configuration.md
│       └── advanced/
│           └── customization.md
├── src/
│   └── main.ts             # Just 3 lines of code
├── index.html
├── package.json
└── vite.config.js

🚦 Migration from Other Tools

From VitePress

1# VitePress config.js equivalent in YAML
2site:
3  title: "My Docs"
4  description: "Documentation site"
5
6navbar:
7  items:
8    - title: "Guide"
9      link: "/guide/"
10
11sidebar:
12  sections:
13    - title: "Getting Started"
14      children:
15        - title: "Introduction"
16          path: "/guide/introduction"

From Docusaurus

Vue Docs UI provides a simpler, Vue-focused alternative with zero configuration complexity.

🎯 Comparison

Feature	Vue Docs UI	VitePress	Docusaurus
Setup Complexity	⭐ 3 lines	⭐⭐ Config needed	⭐⭐⭐ Complex setup
Vue 3 Support	✅ Native	✅ Yes	❌ React only
Zero Config	✅ Out of box	⭐⭐ Needs config	⭐⭐ Needs config
TypeScript	✅ Full support	✅ Yes	✅ Yes
Customization	⭐⭐⭐ Highly flexible	⭐⭐ Medium	⭐⭐⭐ Highly flexible
Performance	⭐⭐⭐ Excellent	⭐⭐⭐ Excellent	⭐⭐ Good

🛠️ Development

Prerequisites

• Node.js 16+
• npm/yarn/pnpm

Development Setup

1# Clone the repository
2git clone https://github.com/vue-docs-ui/vue-docs-ui.git
3cd vue-docs-ui
4
5# Install dependencies
6npm install
7
8# Start development server
9npm run dev
10
11# Build library
12npm run build:lib
13
14# Run example
15cd example && npm run dev

Build Commands

1npm run build:lib     # Build library for production
2npm run build         # Build example site
3npm run type-check    # TypeScript type checking
4npm run preview       # Preview built site

📦 Publishing to NPM

This package is ready for NPM publication:

1# Dry run (test without publishing)
2npm run publish:dry
3
4# Version bump
5npm run version:patch  # 1.0.0 → 1.0.1
6npm run version:minor  # 1.0.0 → 1.1.0
7npm run version:major  # 1.0.0 → 2.0.0
8
9# Publish to NPM
10npm publish

The package includes:

• ✅ TypeScript declarations
• ✅ ES and UMD builds
• ✅ CSS bundle
• ✅ Proper exports configuration
• ✅ Tree-shaking support

🌐 Browser Support

• Chrome >= 87
• Firefox >= 78
• Safari >= 14
• Edge >= 88

📝 License

MIT License - see LICENSE file for details.

🤝 Contributing

We welcome contributions! Please see our Contributing Guide for details.

📖 Documentation in multiple languages:

• 🇺🇸 English Contributing Guide
• 🇨🇳 中文贡献指南

Quick Contributing

• 🐛 Report bugs
• 💡 Request features
• 📖 Improve documentation
• 💬 Join discussions

Development Workflow

1. Fork the repository
2. Create your feature branch (git checkout -b feature/amazing-feature)
3. Commit your changes (git commit -m 'Add amazing feature')
4. Push to the branch (git push origin feature/amazing-feature)
5. Open a Pull Request

📞 Support

• 📖 Documentation
• 🐛 Issue Tracker
• 💬 Discussions
• 📧 Email Support

📊 Stats

🙏 Acknowledgments

• Built with Vue.js 3
• Powered by Vite
• Icons by Lucide
• Inspired by modern documentation tools

---

Made with ❤️ by the Vue Docs UI Team