跳到主要内容

docs/ — 内容源

6 个业务模块，48 个 .md 文件（无 .mdx）。Sidebar 100% 由本目录树 + _category_.json 驱动。

STRUCTURE​

docs/
├── intro/         # position 1 快速入门（10 文件）
├── annotation/    # position 2 标注工作台（14 文件，最大）
├── training/      # position 3 训练管理（11 文件）
├── dataset/       # position 4 数据集与版本（11 文件）
├── concepts/      # position 5 概念说明（1 文件）
└── faq/           # position 6 常见问题（1 文件）

每个模块：_category_.json（控制 position/label）+ 一个 index.md（section landing，slug 形如 /intro）+ N 个子主题 .md。

WHERE TO LOOK​

Task做法
新增页面在对应模块目录建 .md，加 frontmatter（见下），自动入 sidebar
改页面顺序在 frontmatter 加 sidebar_position: <int>；index 用文件名
改 section 标签/顺序改该模块的 _category_.json（position / label）
加新 section新建子目录 + _category_.json，sidebar 自动识别
引用截图<Screenshot src="/img/<module>/<file>.png" alt="..." caption="..." />，文件名必须匹配 SCREENSHOTS.md

CONVENTIONS​

Frontmatter（所有文档页必须）​

---
slug: /<module>[/<topic>]        # 必填，绝对路径，不可重复
title: <中文标题>                 # 必填
description: <一句话摘要>         # 必填
sidebar_position: <int>          # 选填，非 index 页用；index 靠文件名
---
  • 没有 tags / authors / draft / date / 自定义字段。
  • slug 必须与路由一致（如 docs/training/parameters.md → slug: /training/parameters）。
  • 重复 slug 会导致 onBrokenLinks: 'throw' 之外的额外构建冲突。

MDX 导入样板（每个非 index 文档页）​

import { Steps, Step } from '@site/src/components/Steps';
import FieldTable from '@site/src/components/FieldTable';
import Callout from '@site/src/components/Callout';
import Screenshot from '@site/src/components/Screenshot';

4 行全部保留，即使本页没用某个组件（保持一致性，方便后续编辑）。组件 API 详见 src/components/AGENTS.md。

内容组织三段式（推荐）​

  1. 「这个功能解决什么问题」 —— 简短背景，回答 why
  2. 主体 —— <Steps> 操作流、<FieldTable> 参数表、<Callout> 注意事项
  3. 「常见问题」 —— <Callout type="warning"> 排错

参见 dataset/import-formats.md、training/parameters.md 为模板。

Callout 使用密度​

info 用最多，warning 次之，tip 用于建议，danger 极少用。type 必须是 'info' | 'warning' | 'danger' | 'success' | 'tip'，其它值静默回退 info。

ANTI-PATTERNS（内容写入禁区）​

  • 不要手改 sidebars.ts —— sidebar 全自动。
  • 不要给截图乱起名 —— <Screenshot> 占位回退会让构建通过但页面破，文件名必须匹配 SCREENSHOTS.md。
  • 不要在内容里写"删除项目唯一数据集"等违反平台约束的话 —— 见下表。
  • 不要混用任务类型的标注格式（detect/segment/obb/pose 互不兼容）。
  • 不要给非 detect 数据集推荐数据增强。

平台业务硬约束（写文档时不能违反）​

这些规则散落在多份文档里，被反复引用；改任何一句话前先确认影响范围：

约束出处
新训练任务必须绑定 status=ready 且非 archived 的数据集版本intro/create-training.md、training/dataset-version.md、dataset/overview.md、faq/index.md
数据增强仅适用于 detect 数据集；对 segment/obb/pose 会损坏标签dataset/augmentation.md、dataset/overview.md、faq/index.md
项目唯一数据集禁止独立删除dataset/index.md
同一数据集内检测/分割/OBB/Pose 标签格式不能混用dataset/import-formats.md
标签文件 class_id 必须严格对应 classes.txt 行号（从 0 开始）dataset/import-formats.md
标注合并导入无撤销，必须先做预校验annotation/merge.md
Pose 标注保存原子校验：bbox>0、关键点数量精确、visibility∈2、坐标在图像内annotation/pose.md
Ascend NPU：驱动/CANN/torch_npu/Python 版本必须匹配，不能跨大版本training/npu-training.md

NOTES​

  • MDX 在 .md 里也生效：classic preset 通过 MDX pipeline 解析 .md，所以 JSX import / 组件标签都能用，无需把文件改成 .mdx。
  • 占位框是构建安全网，不是发布阻塞 —— 但 PR 里新增的 <Screenshot> 若 24h 内不补图，要在 PR 描述里说明。
  • SCREENSHOTS.md 是契约：作者、截图人员、占位回退逻辑三方都依赖它的文件名清单；改文件名要三处同步。
  • section 内文档数不均：concepts/ 和 faq/ 当前各 1 个 index，预期会扩展。