Dux VitePress Theme

🎨 现代、优雅、可定制的 VitePress 文档主题

轻松打造高颜值、多语言、组件丰富的技术文档站点

📖 在线文档 · 🏠 GitHub · 🌐 官网

中文 · English

---

✨ 特性亮点

• 🚀 开箱即用：一行命令安装，零配置快速上手
• 🎨 现代设计：优雅的 UI，支持亮/暗色主题
• 🌍 多语言：完整的 i18n 支持与语言跳转页
• 📚 多种布局：Home / Doc / Page / Sponsor / Changelog / Jump
• 🔍 本地搜索：内置搜索与优雅降级
• 🧩 丰富组件：自定义容器、代码组、Badge、Mermaid 等
• ⚡ 高性能：基于 VitePress 1.x 与按需构建

---

🧱 Monorepo 结构

本仓库为 Monorepo：

vitepress-monorepo/
├─ packages/
│  ├─ theme/     # 主题源码（发布包）
│  └─ docs/      # 文档站点（演示与说明）
├─ .github/workflows/deploy-docs.yml  # 自动部署文档到 GitHub Pages
└─ README.md

文档站点默认部署到 https://duxweb.github.io/vitepress-theme/。

---

🚀 快速开始（在你的项目中使用主题）

1. 安装主题

# 使用 pnpm
pnpm add @duxweb/vitepress-theme

# 或 npm / yarn
npm i @duxweb/vitepress-theme
# yarn add @duxweb/vitepress-theme

2. 启用主题

// .vitepress/theme/index.ts
import theme from '@duxweb/vitepress-theme'
import '@duxweb/vitepress-theme/dist/index.css'

export default {
  extends: theme
}

3. 最小化配置（推荐）

会自动注入 vite.ssr.noExternal、optimizeDeps.exclude，并启用 Mermaid 运行时渲染（基于 vitepress-mermaid-renderer，GPL-3.0-only）。

// .vitepress/config.mts
import { withDuxTheme } from '@duxweb/vitepress-theme/config'

export default withDuxTheme({
  // 你的配置...
})

4. 首页示例

---
layout: home
hero:
  name: My Project
  text: Modern VitePress Theme
  actions:
    - theme: brand
      text: Get Started
      link: /guide/
features:
  - icon: ⚡
    title: Fast
    details: Built on VitePress
---

---

🧭 文档开发（本仓库）

# 开发文档站点
pnpm dev

# 构建所有包（主题与文档）
pnpm build

# 仅构建文档
pnpm build:docs

# 预览文档
pnpm preview

文档构建已根据 GitHub 环境自动设置 base：

• 本地：/
• GitHub Pages：/vitepress-theme/

---

🧩 布局与能力

布局	用途	说明
home	首页	Hero / Features / QuickStart
doc	文档页	侧边栏 / 目录 / 页脚导航
page	单页	居中内容 + 自定义 PageHero
sponsor	赞助页	支付方式 / 支持者列表 / 统计
changelog	更新日志	版本历史 / 类型分类
jump	语言跳转	智能检测语言并跳转

更多示例与 API 详见在线文档。

---

🤝 参与贡献

欢迎通过 Issue / PR 参与贡献：

1. Fork 本仓库
2. 新建分支：feat/your-feature
3. 提交代码并发起 PR

---

📄 协议

MIT

---

Made with ❤️ by DuxWeb