Meet YOLO26: next-gen vision AI.

Link to this section文档工作流 📚#

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

Link to this section文档结构 🗂️#

Link to this section主要文档站点#

Link to this section仓库结构#

docs/
├── en/              # English docs
│   ├── index.md     # Homepage
│   ├── guides/      # User guides
│   ├── tasks/       # Task-specific docs
│   ├── models/      # Model documentation
│   └── reference/   # API reference
├── zh/              # Chinese translations
└── overrides/       # Theme customizations

Link to this section文档编写 ✍️#

Link to this section风格指南#

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

Link to this sectionMarkdown 格式#

---
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)
```

Link to this section图片与媒体#

存储在仓库中或使用 CDN:

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

保持图片大小合理(尽可能 <500KB)。

Link to this section构建文档 🔨#

Link to this section本地开发#

安装依赖:

pip install -e ".[docs]"

在本地构建并服务:

mkdocs serve

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

Link to this sectionMkDocs 配置#

主要配置文件 mkdocs.yml

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

Link to this sectionAPI 文档 📖#

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(示例):可运行的代码示例

Link to this section添加新页面 📄#

Link to this section创建 Markdown 文件#

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

Link to this section更新导航#

编辑 mkdocs.yml

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

Link to this section编写内容#

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

Link to this section测试构建#

mkdocs serve

Link to this section提交 PR#

遵循 开发工作流 进行 PR 处理。

Link to this section翻译 🌐#

Link to this section添加翻译#

  1. 将英文版本复制到对应的语言目录:
cp docs/en/page.md docs/zh/page.md
  1. 翻译内容,保持代码示例为英文

  2. 更新 mkdocs.yml 中的备选链接

Link to this section翻译准则#

  • 保留技术术语为英文(YOLO, mAP, FPS)
  • 翻译描述和解释
  • 保持与英文版本相同的结构
  • 当英文版本变更时更新翻译

Link to this section文档 CI 🤖#

CI 自动执行:

  • 在每个 PR 上构建文档
  • 检查失效链接
  • 验证 Markdown 格式
  • 合并至主分支时部署到生产环境

Link to this section修复构建错误#

常见问题:

  • 失效链接:修复或移除无效链接
  • 图片缺失:添加图片或更新路径
  • 无效 YAML:修复 frontmatter 语法
  • 插件错误:检查插件配置

Link to this section最佳实践 ✅#

Link to this section内容组织#

  • 逻辑结构:将相关内容分组
  • 渐进式呈现:简单 → 高级
  • 交叉链接:链接到相关页面
  • 搜索优化:使用清晰的标题和描述

Link to this section维护#

  • 保持最新:针对新功能进行更新
  • 移除过时内容:删除弃用的内容
  • 检查链接:定期修复失效链接
  • 用户反馈:解决常见问题

Link to this section无障碍访问#

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

Link to this section资源 📚#