Docs Conventions

This file records the current documentation organization rules for this repository.

Top-level structure

Keep these top-level sections stable unless there is a strong reason to change them:

When reorganizing docs:

Prefer moving whole directories.
Keep child folders intact.
Avoid flattening directories or manually redistributing many files unless explicitly needed.

For docs-heavy changes, use:

make build

Do not rely only on bun run build after doc moves. make build runs bun run clear first, which clears:

This avoids stale route metadata after folder moves or _category_.json changes.

Use _category_.json conservatively.

Keep _category_.json for top-level sections.
Keep _category_.json for second-level grouped sections.
Keep _category_.json for necessary third-level topic groups.
Do not manually maintain _category_.json for fourth-level or deeper directories.
For depth >= 4, rely on Docusaurus autogenerated categories.

docs/technology is intentionally grouped into these 5 second-level buckets:

The preferred structure is:

level 1: docs/technology
level 2: one of the 5 buckets above
level 3: topic groups such as 算法, 编程语言, 大模型, 云厂商
level 4 and deeper: actual topics, notes, examples, attachments, and autogenerated categories

Do not expand technology back into many parallel second-level categories.

If a directory becomes a generic catch-all:

Prefer moving whole subdirectories into an existing third-level topic.
Avoid creating new miscellaneous buckets unless there is a clear long-term need.

Preserve attachments and relative references unless the task explicitly includes content cleanup.
After moving content, validate the affected docs with make build.
If a large binary is archived out of docs, update the referencing doc to point to the archive note or mark it as archived/unimplemented.