详细贡献指南
感谢你对 VitePress 学习指南项目的关注！本指南将帮助你了解如何参与项目贡献。
快速开始
贡献方式
| 方式 | 难度 | 时间投入 | 说明 |
|---|---|---|---|
| 报告问题 | ⭐ | 5 分钟 | 提交 Bug 或建议 |
| 修复错别字 | ⭐ | 10 分钟 | 改正文档错误 |
| 完善文档 | ⭐⭐ | 1 小时+ | 补充或改进内容 |
| 贡献代码 | ⭐⭐⭐ | 2 小时+ | 开发新功能 |
| 翻译文档 | ⭐⭐ | 1 小时+ | 英文翻译 |
贡献流程
Fork 仓库 → 创建分支 → 进行修改 → 提交 PR → 代码审查 → 合并文档贡献
文档规范
Frontmatter 配置
每个文档必须包含以下 frontmatter：
yaml
---
title: 页面标题
description: 页面描述（150-160 字符）
tags:
- 标签1
- 标签2
author: 作者名
date: YYYY-MM-DD
updated: YYYY-MM-DD
difficulty: Beginner | Intermediate | Advanced
---Markdown 规范
| 规范 | 说明 |
|---|---|
| 标题层级 | 不要跳级，从 # 到 ## 再到 ### |
| 代码块 | 必须指定语言类型 |
| 表格 | 使用标准格式，有表头 |
| 图片 | 必须有 alt 文本 |
| 链接 | 使用描述性文本 |
文件命名
- 使用小写字母
- 使用连字符分隔单词
- 示例：
getting-started.md、custom-theme.md
新增文档
- 确定文档所属目录
- 创建
.md文件 - 添加完整的 frontmatter
- 编写内容
- 更新侧边栏配置
改进现有文档
- 阅读原文，理解上下文
- 保持原有风格一致
- 小改动直接修改，大改动先提 Issue 讨论
代码贡献
开发环境
bash
# 克隆仓库
git clone https://cnb.cool/ZhangWeilong/VitePress.git
cd VitePress
# 安装依赖
npm install
# 启动开发服务器
npm run dev
# 构建预览
npm run build
npm run preview代码规范
TypeScript
- 严格模式开启
- 避免使用
any - 为函数添加类型注解
typescript
// ✅ 正确
function greet(name: string): string {
return `Hello, ${name}!`
}
// ❌ 错误
function greet(name) {
return `Hello, ${name}!`
}Vue 组件
- 使用
<script setup lang="ts">语法 - Props 必须定义类型
- 使用
scoped样式
vue
<script setup lang="ts">
interface Props {
title: string
count?: number
}
const props = withDefaults(defineProps<Props>(), {
count: 0
})
</script>提交规范
Commit Message 格式
<type>(<scope>): <subject>
<body>
<footer>类型说明
| 类型 | 说明 | 示例 |
|---|---|---|
| feat | 新功能 | feat(theme): 添加暗色模式支持 |
| fix | 修复 Bug | fix(nav): 修复移动端导航问题 |
| docs | 文档更新 | docs: 更新安装说明 |
| style | 代码格式 | style: 格式化代码缩进 |
| refactor | 重构 | refactor(utils): 优化日期函数 |
| perf | 性能优化 | perf(list): 虚拟滚动优化 |
| test | 测试 | test: 添加组件单元测试 |
| chore | 构建/工具 | chore: 更新依赖版本 |
Pull Request 规范
PR 标题
使用与 Commit Message 相同的格式
PR 描述模板
markdown
## 变更类型
- [ ] 新功能
- [ ] Bug 修复
- [ ] 文档更新
- [ ] 代码重构
- [ ] 其他
## 变更说明
<!-- 简要描述本次变更的内容 -->
## 相关 Issue
<!-- 关联的 Issue 编号，如：Closes #123 -->
## 测试情况
<!-- 如何测试这些变更 -->
## 截图
<!-- 如有 UI 变更，请附上截图 -->翻译贡献
翻译流程
- 选择要翻译的文档
- 在对应目录创建
en/子目录 - 复制原文并进行翻译
- 提交 PR
翻译规范
| 规范 | 说明 |
|---|---|
| 技术术语 | 保持英文原样（如 Vue、VitePress） |
| 代码示例 | 不翻译代码和命令 |
| 链接 | 保持原有链接不变 |
| 专有名词 | 使用官方翻译 |
审查流程
审查标准
| 维度 | 检查项 |
|---|---|
| 内容 | 准确性、完整性、可读性 |
| 格式 | Markdown 规范、代码规范 |
| 兼容 | 不影响现有功能 |
| 安全 | 无敏感信息泄露 |
审查周期
- 小改动：1-3 天
- 大改动：3-7 天
- 重大更新：需要维护者讨论
贡献者权益
贡献者名单
所有贡献者都会被添加到贡献者名单页面。
贡献者徽章
| 徽章 | 条件 |
|---|---|
| 🥇 首次贡献 | 完成第一个 PR |
| 📝 文档贡献者 | 贡献 3+ 文档 |
| 💻 代码贡献者 | 贡献 5+ 代码 PR |
| 🌐 翻译贡献者 | 完成翻译任务 |
| 🎨 设计贡献者 | 贡献设计资源 |
获取帮助
| 渠道 | 用途 |
|---|---|
| GitHub Issues | 问题反馈 |
| GitHub Discussions | 讨论交流 |
感谢你的贡献
每一个贡献都对项目非常重要，感谢你愿意花时间参与开源！