贡献指南
感谢你对 VitePress 学习指南项目的关注！我们欢迎所有形式的贡献，包括内容完善、问题反馈、功能建议等。
快速开始
环境准备
在开始贡献之前，请确保你的开发环境满足以下要求：
| 工具 | 版本要求 | 说明 |
|---|---|---|
| Node.js | >= 18.0.0 | JavaScript 运行环境 |
| npm | >= 9.0.0 | 包管理器 |
| Git | >= 2.0.0 | 版本控制工具 |
本地开发
bash
# 1. Fork 并克隆仓库
git clone https://cnb.cool/ZhangWeilong/VitePress.git
cd VitePress
# 2. 安装依赖
npm install
# 3. 启动开发服务器
npm run docs:dev
# 4. 在浏览器中访问
# http://localhost:5173贡献类型
1. 内容贡献
我们非常欢迎以下类型的内容贡献：
新增教程
- 确保内容与 VitePress 相关
- 内容组织清晰，循序渐进
- 包含代码示例和截图说明
完善现有内容
- 修正错别字和语法错误
- 补充遗漏的信息
- 更新过时的内容
翻译贡献
- 保持术语一致性
- 遵循中文技术写作规范
2. 问题反馈
在提交 Issue 之前，请：
- 搜索已有的 Issue，避免重复
- 使用清晰的标题描述问题
- 提供复现步骤（如适用）
- 说明你的环境信息
3. 功能建议
欢迎提出新功能建议：
- 描述功能的使用场景
- 说明预期效果
- 如果可能，提供实现思路
文档规范
目录结构
docs/
├── guide/ # 入门指南
├── basics/ # 基础功能
├── theme/ # 主题定制
├── advanced/ # 高级功能
├── examples/ # 实战案例
├── best-practices/ # 最佳实践
└── .vitepress/ # 配置和主题Frontmatter 规范
每个页面都应包含 frontmatter：
markdown
---
title: 页面标题
description: 页面描述，用于 SEO（建议 50-160 字符）
---标题规范
- 一级标题（#）：页面主标题，每个页面只有一个
- 二级标题（##）：章节标题
- 三级标题（###）：小节标题
- 避免跳级使用标题
代码块规范
语法高亮
markdown
```javascript
// 使用正确的语言标识
const greeting = 'Hello VitePress!'
#### 代码注释
- 添加必要的注释说明
- 注释简洁明了
- 中文注释使用中文标点
#### 代码组
当需要展示多种语言或多个文件时，使用代码组：
````markdown
::: code-group
```npm
npm install vitepressyarn
yarn add vitepresspnpm
pnpm add vitepress:::
### 自定义容器
使用自定义容器突出重要信息：
```markdown
::: tip 提示
这是一个提示信息。
:::
::: warning 注意
这是一个警告信息。
:::
::: danger 危险
这是一个危险警告。
:::
::: info 信息
这是一个信息提示。
:::
```
### 图片规范
- 使用相对路径：`./images/example.png`
- 或使用 public 目录：`/images/example.png`
- 图片命名：使用小写字母和连字符，如 `project-structure.png`
- 添加 alt 属性：``
## Git 提交规范
### 提交信息格式
```
<type>(<scope>): <subject>
<body>
<footer>
```
### Type 类型
| 类型 | 说明 |
|------|------|
| docs | 文档更新 |
| feat | 新功能 |
| fix | 修复问题 |
| style | 代码格式调整 |
| refactor | 代码重构 |
| perf | 性能优化 |
| test | 测试相关 |
| chore | 构建/工具相关 |
### 示例
```bash
# 文档更新
git commit -m "docs: 更新安装指南中的 Node.js 版本要求"
# 新增内容
git commit -m "docs(guide): 添加主题开发教程"
# 修复错误
git commit -m "fix: 修正配置示例中的语法错误"
```
## Pull Request 流程
### 1. 创建分支
```bash
# 从 main 创建功能分支
git checkout -b docs/your-feature-name
```
分支命名建议：
- `docs/xxx` - 文档更新
- `feat/xxx` - 新功能
- `fix/xxx` - 问题修复
### 2. 进行修改
- 遵循文档规范
- 保持提交历史整洁
- 一个 PR 只做一件事
### 3. 提交 PR
在 GitHub 上创建 Pull Request：
1. 填写清晰的标题和描述
2. 关联相关的 Issue
3. 等待审核和反馈
### 4. 代码审核
- 响应审核意见
- 及时修改问题
- 保持讨论专业友好
## 样式贡献
### CSS 规范
- 使用 CSS 变量，便于主题切换
- 遵循 BEM 命名约定（可选）
- 响应式设计优先
### 组件规范
- 使用 Vue 3 Composition API
- 组件名使用 PascalCase
- Props 添加类型定义
## 社区准则
### 行为准则
- 尊重所有贡献者
- 使用包容性语言
- 接受建设性批评
- 关注对社区最有利的事情
### 获得帮助
如果你在贡献过程中遇到问题：
1. 查阅本文档
2. 搜索已有 Issue
3. 在 Discussions 中提问
## 🏆 贡献者荣誉
我们非常珍视每一位贡献者的付出，项目设有以下荣誉体系：
### 贡献等级
| 等级 | 条件 | 徽章 |
|------|------|------|
| 🌱 新手贡献者 | 首次提交 PR 并合并 | `first-pr` |
| ✍️ 内容作者 | 提交 3+ 篇文档改进 | `content-writer` |
| 🐛 问题猎人 | 提交 5+ 有效 Issue | `bug-hunter` |
| 🎨 样式设计师 | 提交 3+ 样式/UI 改进 | `designer` |
| 📚 核心贡献者 | 累计 10+ 合并 PR | `core-contributor` |
| 💎 杰出贡献者 | 由维护者评选 | `outstanding` |
### 贡献者榜单
我们会在 [贡献者页面](/contributors) 和 GitHub 仓库首页展示所有贡献者。
### 获得认可的方式
1. **贡献者列表**：所有合并 PR 的贡献者都会显示在贡献者列表中
2. **Changelog 致谢**：每个版本的更新日志会感谢该版本的贡献者
3. **GitHub Stars**：高质量的贡献会在仓库 README 中特别致谢
4. **社区推荐**：活跃贡献者有机会被推荐到 VitePress 中文社区
### 季度贡献之星
每季度评选一次，基于以下维度：
- 📝 内容贡献数量和质量
- 🔄 持续贡献的稳定性
- 🤝 社区互动和帮助他人
- 🎯 对项目发展的实际影响
---
## 📊 贡献统计
想要查看贡献统计？访问 [贡献者页面](/contributors) 查看详细的贡献数据和排行榜。
---