YOLO Vision 2026：

文档工作流 📚#

本指南涵盖了为 Ultralytics 项目编写、构建和维护文档的内容。

文档结构 🗂️#

主要文档站点#

仓库结构#

内容所有权和页面系列因仓库而异。请遵循现有的层级结构和导航清单，而不是假定固定的文件夹集合。一个典型的源码树结构始于：

docs/
└── en/              # Source content

编写文档 ✍️#

风格指南#

  • 清晰且简洁：快速切入重点
  • 主动语态：使用“Train the model”，而不是“The model is trained”
  • 代码示例：为每个概念提供可运行的代码
  • 视觉辅助：在有帮助的地方使用图片/图表
  • 格式一致：遵循现有的页面结构

Markdown 格式#

---
description: Brief page description for SEO
keywords: relevant, keywords, for, search
---

# Page Title

Brief introduction explaining what this page covers.

## Section Heading

Content with examples:

```python
from ultralytics import YOLO

# Load pretrained model
model = YOLO("yolo26n.pt")
results = model("image.jpg")
```

### Key points:

- Use bullet points for lists
- Keep paragraphs short
- Include links to related pages

### Code Examples

- **Minimal**: Show only relevant code
- **Runnable**: Examples should work copy-paste (test with actual [YOLO models](https://docs.ultralytics.com/models))
- **Commented**: Explain non-obvious parts
- **Tested**: Verify examples work with current version

```python
from ultralytics import YOLO

# Load pretrained model
model = YOLO("yolo26n.pt")

# Train on custom data
results = model.train(data="coco8.yaml", epochs=3)
```

图片与媒体#

存储在仓库中或使用 CDN：

![Alt text](https://path/to/image.png)

保持合理的图片大小（条件允许时 <500KB）。

构建文档 🔨#

本地开发#

每个仓库都会记录其自身的环​​境设置。对于本 Handbook 仓库，请使用以下命令安装依赖：

uv pip install -r requirements.txt

在本地构建并运行服务：

zensical serve

访问 http://127.0.0.1:8000 进行预览。

Zensical 配置#

各个仓库目前使用的是兼容 Zensical 的过渡性 mkdocs.yml 清单：

site_name: Ultralytics Docs
theme:
    name: material
    palette:
        - scheme: slate
plugins:
    - search
    - ultralytics

API 文档 📖#

API 参考文档是从文档字符串（docstrings）自动生成的。请查阅完整 API 参考了解所有模块：

def train(self, data, epochs=100, batch=16):
    """
    Train the model on a dataset.

    Args:
        data (str): Path to data YAML file
        epochs (int): Number of training epochs
        batch (int): Batch size

    Returns:
        (Results): Training results

    Examples:
        ```python
        model = YOLO("yolo26n.pt")
        results = model.train(data="coco8.yaml", epochs=100)
        ```
    """

核心要素：

  • 简短描述：单行总结
  • 参数 (Args)：带类型的参数描述
  • 返回值 (Returns)：返回值描述
  • 示例 (Examples)：可运行的代码示例

添加新页面 📄#

1. 创建 Markdown 文件#

# Create new guide
touch docs/en/guides/new-guide.md

2. 更新导航#

编辑 mkdocs.yml：

nav:
    - Home: index.md
    - Guides:
          - New Guide: guides/new-guide.md

3. 编写内容#

遵循风格指南并包含示例。

4. 测试构建#

zensical build --strict

5. 提交 PR#

遵循开发工作流了解 PR 流程。

翻译 🌐#

翻译是在集中式生产构建过程中根据英文内容生成的。请勿手动添加翻译后的源目录。

翻译指南#

  • 保持技术术语为英文（如 YOLO、mAP、FPS）
  • 翻译描述和解释
  • 保持与英文版本相同的结构
  • 当英文版本更改时更新翻译

文档 CI 🤖#

CI 会自动执行以下操作：

  • 在每个 PR 上运行 zensical build --strict
  • 检查断开的链接
  • 验证 markdown 格式
  • 在合并到 main 后触发集中式生产构建

修复构建错误#

常见问题：

  • 断开的链接：修复或移除无效链接
  • 缺少图片：添加图片或更新路径
  • 无效的 YAML：修复 frontmatter 语法
  • 配置错误：检查兼容 Zensical 的清单

最佳实践 ✅#

内容组织#

  • 逻辑结构：对相关内容进行分组
  • 渐进式披露：从简单到高级
  • 交叉链接：链接到相关页面
  • 搜索优化：使用清晰的标题和描述

维护#

  • 保持最新：根据新功能进行更新
  • 移除过时内容：删除已弃用的内容
  • 检查链接：定期修复损坏的链接
  • 用户反馈：解答常见问题

无障碍访问#

  • 替代文本 (Alt text)：为屏幕阅读器描述图片
  • 清晰的标题：使用适当的标题层级
  • 通俗易懂的语言：尽可能避免行话
  • 代码对比度：确保代码块清晰可读

资源 📚#

贡献者
GLglenn-jocher6