贡献文档

​

提供反馈

​

在任何页面

• 点赞/点踩 — 快速反馈该页面是否有帮助
• 评论 — 分享具体的反馈、建议或问题
• 问题报告 — 报告错误、过时的信息或损坏的链接

​

一般反馈渠道

• GitHub 问题 — 在 Livepeer 文档仓库
• Discord — 在 Livepeer 社区 Discord 中分享反馈
• 电子邮件 — 直接联系文档团队

​

贡献文档

​

非技术贡献

​

选项 1：反馈表单

​

选项 2：内容建议

• 识别需要澄清的领域
• 建议新主题或指南
• 报告过时的信息
• 分享使用案例或示例

​

技术贡献（Git & Markdown）

​

拉取请求工作流程

​

逐步指南

​

1. 分叉仓库

1. 导航到 github.com/livepeer/docs
2. 点击右上角的“Fork”按钮
3. 这会创建该存储库的副本

​

2. 克隆您的副本

git clone https://github.com/YOUR_USERNAME/docs.git
cd docs

​

3. 设置远程跟踪

# Add the original repository as upstream
git remote add upstream https://github.com/livepeer/docs.git

# Verify remotes
git remote -v

​

4. 创建一个分支

# Make sure you're on the latest version
git checkout docs-v2-preview
git pull upstream docs-v2-preview

# Create a new branch with a descriptive name
git checkout -b docs/fix-typo-quickstart-guide
# or
git checkout -b docs/add-api-example
# or
git checkout -b docs/update-component-docs

• docs/文档更改的前缀
• 使用描述性名称: docs/fix-typo-quickstart-guide
• 使用短横线命名法（小写带短横线）

​

5. 安装预提交钩子

# Install the pre-commit hook
./.githooks/install.sh

• 检查已弃用的 ThemeData 使用
• 警告硬编码的十六进制颜色
• 验证 MDX、JSON 和 JavaScript 语法
• 检查相对导入
• 验证绝对导入路径

​

6. 进行您的更改

• 主文档页面： v2/pages/（按部分组织）
• 组件： snippets/components/
• 数据文件： snippets/data/
• 资产: snippets/assets/

v2/pages/
├── home/          # Home tab content
├── about/         # About tab content
├── developers/    # Developers tab content
├── gateways/      # Gateways tab content
├── orchestrators/ # Orchestrators tab content
├── delegators/    # Delegators tab content
├── community/     # Community tab content
├── resources/     # Resources tab content
└── internal/      # Internal documentation

• 文件名使用短横线分隔格式: quickstart-guide.mdx
• 使用能反映内容的描述性名称
• 遵循每个部分中现有的结构

​

7. 本地测试

# Install Mintlify CLI (if not already installed)
npm i -g mintlify

# Run the development server
mint dev

• ✅ 页面正确渲染
• ✅ 控制台无错误
• ✅ 链接工作正常
• ✅ 组件显示正确
• ✅ 暗色和亮色模式均有效
• ✅ 移动端响应式设计

​

8. 提交您的更改

# Stage your changes
git add .

# Commit with a clear message
git commit -m "docs: fix typo in quickstart guide"

• 使用前缀：docs:, fix:, feat:, chore:
• 保持描述性：“docs: 添加 API 身份验证示例”
• 引用问题：“docs: 更新网关设置 (修复 #123)”

git commit -m "Update .allowlist" --trailer "allowlist-edit=true"

git commit -m "Remove obsolete files" --trailer "allow-deletions=true"

​

9. 推送到您的分支

git push origin docs/your-branch-name

​

10. 创建拉取请求

1. 导航到github.com/livepeer/docs
2. 您应该会看到一个横幅，建议从您最近的推送创建一个PR
3. 点击“比较并创建拉取请求”
4. 填写PR模板：
   • 标题: 清晰、描述性的标题
   • 描述: 解释做了什么以及为什么这么做
   • 相关问题: 链接到任何相关的问题
   • 类型: 标记为文档更改
   • 测试: 描述您的测试方法

## Description
Brief description of changes

## Type of Change
- [ ] Bug fix (typo, broken link, incorrect information)
- [ ] New content (guide, tutorial, example)
- [ ] Content improvement (clarification, better examples)
- [ ] Component or styling update

## Related Issues
Fixes #123

## Testing
- [ ] Tested locally with `mint dev`
- [ ] Checked light and dark modes
- [ ] Verified all links work
- [ ] No console errors

​

11. 处理评审反馈

• 回复评论
• 进行所需更改
• 将更新推送到同一分支（它们将自动出现在 PR 中）
• 完成时将对话标记为已解决

​

12. 合并和清理

• 删除本地的分支：git branch -d docs/your-branch-name
• 在 GitHub 上删除你的分支（合并后可用选项）
• 更新你的 fork：git checkout docs-v2-preview && git pull upstream docs-v2-preview

​

开发设置

​

先决条件

• Node.js（建议使用 v18 或更高版本）
• Git
• GitHub 账户

​

安装

# Clone the repository
git clone https://github.com/livepeer/docs.git
cd docs

# Install Mintlify CLI globally
npm i -g mintlify

# Install pre-commit hooks
./.githooks/install.sh

​

本地运行

# Start development server
mint dev

# Server runs on http://localhost:3000 by default

​

项目结构

docs/
├── v2/pages/              # Main documentation pages (MDX)
├── snippets/              # Reusable components and data
│   ├── components/        # React/JSX components
│   ├── data/             # Data files (JSX)
│   ├── assets/           # Images, logos, media
│   └── scripts/          # Automation scripts
├── .github/              # GitHub Actions workflows
├── .githooks/            # Pre-commit hooks
├── docs.json             # Mintlify navigation config
└── style.css             # Global CSS variables

​

贡献指南

​

风格指南

• ✅ 仅使用 CSS 自定义属性 (var(--accent))
• ❌ 永远不要使用ThemeData 或硬编码颜色
• ✅ 使用绝对导入: /snippets/components/...
• ❌ 不要为代码片段使用相对导入
• ✅ 在浅色和深色模式下进行测试

​

组件用法

• 从 组件库
• 在创建新组件之前，请查看组件文档
• 遵循现有的模式和惯例

​

内容指南

• 清晰简洁 — 为你受众写作
• 使用示例 — 展示，而不仅仅是说明
• 保持内容更新 — 移除过时的信息
• 适当链接 — 使用内部链接指向相关内容
• 添加关键词 — 帮助提高可发现性

​

代码示例

• 使用正确的语法高亮
• 尽可能包含完整且可运行的示例
• 解释代码的功能
• 在相关情况下显示预期输出

​

测试要求

• 所有页面无错误渲染
• 浏览器中无控制台错误
• 链接正常工作
• 组件显示正常
• 在浅色和深色模式下均有效
• 移动响应式
• 预提交钩子通过

​

审查流程

​

谁审查什么

• 开发者部分： 开发者关系团队
• 网关部分: 网关团队
• 协调器部分: 协调器团队
• 委托人部分: 委托人团队
• 资源部分: 文档团队
• ** 通用/跨领域:** 文档团队

​

审阅时间表

• ** 小改动**（拼写错误，损坏的链接）：通常在24小时内审核
• 中等更改（内容更新，示例）：48-72小时
• 大型更改（新指南，重大重组）：可能需要更长时间，先在问题中讨论

​

审核标准

• ✅ 准确性和正确性
• ✅ 符合风格指南
• ✅ 正确使用组件
• ✅ 有效的链接和示例
• ✅ 适当的语气和清晰度
• ✅ SEO 和可发现性

​

处理反馈

• 回复所有评论
• 对所有请求的更改作出回应或解释为何不进行
• 将更新推送到同一分支
• 将对话标记为已解决
• 准备就绪时请求重新审核

​

可以贡献什么

​

内容改进

• 修复拼写和语法错误
• 澄清模糊的解释
• 更新过时的信息
• 改进代码示例
• 添加缺失的信息

​

新内容

• 教程和指南
• 新功能的快速入门
• API 文档
• 代码示例和片段
• 组件示例

​

技术改进

• 组件增强
• 样式改进
• 自动化脚本
• 文档工具

​

翻译

• 帮助翻译内容（当多语言支持就绪时）
• 改进现有翻译

​

文件结构指南

​

在哪里编辑不同类型的内容

​

章节组织

v2/
├── home/                 # Home tab
│   ├── mission-control.mdx
│   ├── introduction/
│   └── project-showcase/
├── about/             # About tab
│   ├── about-portal.mdx
│   └── core-concepts/
├── developers/            # Developers tab
│   ├── building-on-livepeer/
│   ├── guides-and-resources/
│   └── builder-opportunities/
├── gateways/          # Gateways tab
│   ├── gateway-portal.mdx
│   ├── run/
│   └── build/
├── orchestrators/     # Orchestrators tab
│   ├── orchestrator-portal.mdx
│   └── run/
├── delegators/        # Delegators tab
│   └── delegator-portal.mdx
└── resources/         # Resources tab
    ├── resources-portal.mdx
    └── documentation-guide/

​

贡献者资源

​

贡献工作流程摘要

​

对于小改动（拼写错误，损坏的链接）

1. 分叉并创建分支
2. 进行修复
3. 本地测试
4. 提交 PR
5. 处理任何反馈

​

对于 Medium 更改（内容更新、示例）

1. 打开一个问题进行讨论（可选但推荐）
2. 分叉并创建分支
3. 做出更改
4. 彻底测试
5. 提交带有清晰描述的PR
6. 根据反馈进行迭代

​

对于大型更改（新指南、重大重构）

1. 总是先进行讨论 — 打开一个问题或讨论
2. 在开始之前获取反馈和批准
3. 创建详细计划
4. 分叉并创建分支
5. 逐步工作（考虑草稿PR）
6. 提交带有全面描述的PR
7. 基于广泛反馈进行迭代

​

认可

​

有问题吗？

• 查看文档指南 用于结构和约定
• 查看 样式指南 以了解样式指南
• 查看 组件库用于组件使用
• 查看CODEOWNERS以了解谁负责审查什么
• 打开 GitHub 问题或讨论
• 在 Livepeer Discord 社区提问

​

非技术性贡献提案

​

当前选项

1. GitHub 网页编辑器 — 直接在浏览器中编辑文件
2. 反馈表单 — 通过表单提交建议
3. 问题报告 — 通过内容建议打开 GitHub 问题

​

建议的工作流程

​

选项 1: Mintlify Web 编辑器集成

1. 点击任何文档页面上的 “编辑此页面” 按钮
2. 打开 Mintlify 网页编辑器（需要身份验证）
3. 以可视化或 Markdown 模式进行编辑
4. 提交更改以自动创建 GitHub PR

• Mintlify 网络编辑器访问权限
• GitHub 身份验证
• 自动 PR 创建

​

选项 2：基于表单的提交系统

1. 用户填写表单，包含：

• 页面 URL 或部分
• 更改类型（拼写错误、澄清、新内容）
• 当前文本（如适用）
• 建议文本
• 更改原因

2. 表单提交创建 GitHub 问题
3. 维护者审查并执行以下操作之一：
   • 实施更改
   • 转换为用户PR模板
   • 请求更多信息

• 表单创建（Google Forms、Typeform 或自定义）
• GitHub API 集成
• 问题模板自动化

​

选项 3: “编辑此页面” 按钮与 PR 模板

1. 点击 “编辑此页面” 按钮
2. 打开该文件的 GitHub 网页编辑器
3. 用户进行更改
4. GitHub 会提示创建带有模板的 PR
5. 用户填写 PR 描述
6. 创建 PR 以供审查

• 在所有页面上添加 “编辑此页面” 按钮
• 创建 PR 模板
• 使用正确分支链接到 GitHub 网络编辑器

​

选项 4：外部 CMS 集成

1. 非技术人员在 CMS 中编辑内容
2. CMS 网络钩子触发 GitHub Actions
3. 更改会自动提交并创建 PR
4. 维护者审查 PR

• CMS 设置和配置
• GitHub Actions 工作流
• 内容同步
• 认证和权限

​

推荐的实施顺序

1. 阶段 1（快速胜利）： 添加“编辑此页面”按钮，链接到 GitHub 网络编辑器
2. 阶段 2（中等努力）： 创建基于表单的提交系统，实现 GitHub 问题自动化
3. 阶段 3（长期）： 评估 Mintlify 网络编辑器集成或 CMS 解决方案

​

欢迎反馈

• 在 GitHub 上打开一个议题提出您的建议
• 在 Livepeer Discord 中讨论
• 联系文档团队