vue-docs-ui

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)

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

Option 2: Manual Installation

npm install vue-docs-ui
# or
yarn add vue-docs-ui
# or
pnpm add vue-docs-ui

Basic Usage (3 lines of code!)

// main.ts
import createDocsApp from 'vue-docs-ui'
import 'vue-docs-ui/dist/style.css'

createDocsApp()

Configuration File

Create public/config/site.yaml:

# Basic site configuration
site:
  title: "My Documentation"
  description: "Built with Vue Docs UI"
  logo: "📚"  # Supports emoji, images, or URLs
  author: "Your Name"

# Navigation
navbar:
  items:
    - title: "Home"
      link: "/"
    - title: "Guide"
      link: "/guide"
    - title: "GitHub"
      link: "https://github.com/your-repo"
      external: true

# Sidebar
sidebar:
  sections:
    - title: "Getting Started"
      path: "/guide"
      children:
        - title: "Quick Start"
          path: "/guide/quick-start"
        - title: "Configuration"
          path: "/guide/configuration"

# Theme (NEW: Multi-theme support!)
theme:
  # Theme selection: default | vue | github | purple | orange | emerald
  theme: "vue"
  
  # Default mode: light | dark | auto
  defaultMode: "auto"
  
  # Allow users to toggle theme
  allowToggle: true
  
  # Show theme switcher component
  showThemeSwitcher: true

# Table of Contents
toc:
  maxLevel: 2
  enabled: true
  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:

site:
  # Emoji (simplest)
  logo: "🤖"
  
  # Local image
  logo: "/images/logo.png"
  
  # Online image
  logo: "https://example.com/logo.svg"
  
  # Relative path
  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

theme:
  # Select theme: default | vue | github | purple | orange | emerald
  theme: "vue"
  
  # Default mode: light | dark | auto
  defaultMode: "auto"
  
  # Allow users to toggle theme/mode
  allowToggle: true
  
  # Show theme switcher component
  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

• User Selection (localStorage)
• Config File (site.yaml)
• System Preference (for auto mode)
• Default Values

Example Configurations

Fixed Theme Mode:

theme:
  theme: "github"
  defaultMode: "light"
  allowToggle: false
  showThemeSwitcher: false

Full User Control:

theme:
  theme: "default"
  defaultMode: "auto"
  allowToggle: true
  showThemeSwitcher: true

Brand Specific:

theme:
  theme: "vue"          # Vue theme for Vue projects
  defaultMode: "auto"
  allowToggle: true
  showThemeSwitcher: true

🔧 Advanced Usage

Custom Components

import createDocsApp from 'vue-docs-ui'
import 'vue-docs-ui/dist/style.css'
import MyCustomHome from './MyCustomHome.vue'
import MyCustomArticle from './MyCustomArticle.vue'

createDocsApp({
  configPath: '/config/site.yaml',
  el: '#app',
  customComponents: {
    home: MyCustomHome,
    article: MyCustomArticle
  }
})

Component Library Mode

import { createApp } from 'vue'
import { DocsLayout, loadConfig } from 'vue-docs-ui'
import 'vue-docs-ui/dist/style.css'

const config = await loadConfig('/config/site.yaml')
const app = createApp(DocsLayout, { config })
app.mount('#app')

Available Components

import {
  DocsLayout,
  HeaderNav,
  SidebarNav,
  TableOfContents,
  MarkdownRenderer,
  DefaultHome,
  DefaultArticle,
  createDocsApp,
  loadConfig
} 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

# VitePress config.js equivalent in YAML
site:
  title: "My Docs"
  description: "Documentation site"

navbar:
  items:
    - title: "Guide"
      link: "/guide/"

sidebar:
  sections:
    - title: "Getting Started"
      children:
        - title: "Introduction"
          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

# Clone the repository
git clone https://github.com/vue-docs-ui/vue-docs-ui.git
cd vue-docs-ui

# Install dependencies
npm install

# Start development server
npm run dev

# Build library
npm run build:lib

# Run example
cd example && npm run dev

Build Commands

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

📦 Publishing to NPM

This package is ready for NPM publication:

# Dry run (test without publishing)
npm run publish:dry

# Version bump
npm run version:patch  # 1.0.0 → 1.0.1
npm run version:minor  # 1.0.0 → 1.1.0
npm run version:major  # 1.0.0 → 2.0.0

# Publish to NPM
npm 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

• Fork the repository
• Create your feature branch (git checkout -b feature/amazing-feature)
• Commit your changes (git commit -m 'Add amazing feature')
• Push to the branch (git push origin feature/amazing-feature)
• 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