Link to this sectionDocumentation Workflow 📚#

This guide covers writing, building, and maintaining documentation for Ultralytics projects.

Link to this sectionDocumentation Structure 🗂️#

Link to this sectionMain Documentation Sites#

• docs.ultralytics.com - YOLO technical documentation
• handbook.ultralytics.com - Company handbook (this site)

Link to this sectionRepository Structure#

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 sectionWriting Documentation ✍️#

Link to this sectionStyle Guide#

• Clear and concise: Get to the point quickly
• Active voice: "Train the model" not "The model is trained"
• Code examples: Show working code for every concept
• Visual aids: Use images/diagrams where helpful
• Consistent formatting: Follow existing page structures

Link to this sectionMarkdown Format#

---
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 sectionImages and Media#

Store in repository or use CDN:

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

Keep image sizes reasonable (<500KB when possible).

Link to this sectionBuilding Documentation 🔨#

Link to this sectionLocal Development#

Install dependencies:

pip install -e ".[docs]"

Build and serve locally:

mkdocs serve

Visit http://127.0.0.1:8000 to preview.

Link to this sectionMkDocs Configuration#

Main config in mkdocs.yml:

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

Link to this sectionAPI Documentation 📖#

API reference is auto-generated from docstrings. See the complete API reference for all modules:

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

Key elements:

• Brief description: One-line summary
• Args: Parameter descriptions with types
• Returns: Return value description
• Examples: Working code example

Link to this sectionAdding New Pages 📄#

Link to this section1. Create Markdown File#

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

Link to this section2. Update Navigation#

Edit mkdocs.yml:

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

Link to this section3. Write Content#

Follow style guide and include examples.

Link to this section4. Test Build#

mkdocs serve

Link to this section5. Submit PR#

Follow development workflow for PR process.

Link to this sectionTranslations 🌐#

Link to this sectionAdding Translations#

1. Copy English version to language directory:

cp docs/en/page.md docs/zh/page.md

2. Translate content, keep code examples in English

3. Update mkdocs.yml alternate links

Link to this sectionTranslation Guidelines#

• Keep technical terms in English (YOLO, mAP, FPS)
• Translate descriptions and explanations
• Maintain same structure as English version
• Update translations when English version changes

Link to this sectionDocumentation CI 🤖#

CI automatically:

• Builds documentation on every PR
• Checks for broken links
• Validates markdown formatting
• Deploys to production on merge to main

Link to this sectionFixing Build Errors#

Common issues:

• Broken links: Fix or remove invalid links
• Missing images: Add images or update paths
• Invalid YAML: Fix frontmatter syntax
• Plugin errors: Check plugin configuration

Link to this sectionBest Practices ✅#

Link to this sectionContent Organization#

• Logical structure: Group related content
• Progressive disclosure: Simple → advanced
• Cross-linking: Link to related pages
• Search optimization: Use clear titles and descriptions

Link to this sectionMaintenance#

• Keep current: Update for new features
• Remove outdated: Delete deprecated content
• Check links: Fix broken links regularly
• User feedback: Address common questions

Link to this sectionAccessibility#

• Alt text: Describe images for screen readers
• Clear headings: Use proper heading hierarchy
• Plain language: Avoid jargon when possible
• Code contrast: Ensure code blocks are readable

Link to this sectionResources 📚#

• MkDocs Documentation - Static site generator
• Material Theme - Theme documentation
• Markdown Guide - Markdown syntax reference
• Ultralytics Blog - Documentation examples and tutorials
• Ultralytics Glossary - AI and computer vision terminology