| name | ai-docs-information-architecture |
| description | Use when planning ai-docs sections, routes, page hierarchy, navigation, sidebar grouping, redirects, indexes, or documentation taxonomy before writing pages |
AI Docs Information Architecture
Overview
信息架构（Information Architecture，组织内容让读者可找到、可理解、可行动的方法）决定文档是否可维护。Theme Hope 的结构化侧边栏让文件树和 frontmatter 成为目录系统的事实来源，因此新内容必须先确定栏目、路由、索引页和排序。
When to Use
- Adding a new section, directory, landing page, or top-level documentation category.
- Moving pages, splitting long pages, merging duplicated pages, or changing sidebar/navbar.
- Deciding where a new AI workflow, reference, tutorial, troubleshooting page, or configuration page belongs.
- Designing docs for a new product area before writing content.
Do not use for single-paragraph copyedits that do not affect structure.
Current Project Model
| Element | Current State |
|---|
| Docs root | src |
| Home route | src/README.md -> / |
| Main section | src/getting-started/ -> /getting-started/ |
| Navbar | / and 快速入门 in src/.vuepress/navbar.ts |
| Sidebar | Root sidebar with getting-started/ group and children: "structure" |
| Ordering | Page frontmatter order; folder groups use dir.order in README.md |
Do not manually list every page in the sidebar while children: "structure" is the chosen convention.
Route Rules
| File | Route |
|---|
src/README.md | / |
src/foo.md | /foo.html |
src/foo/README.md | /foo/ |
src/foo/bar.md | /foo/bar.html |
Use README.md for every directory that needs a landing page. Avoid orphan pages that are not linked from a section index or sidebar.
Placement Decision
| Content Type | Preferred Location |
|---|
| First-run setup, commands, platform basics | Existing src/getting-started/ |
| Repeatable AI coding workflow | A workflow page under the most relevant section |
| Configuration reference | A reference/config page, not buried in tutorial prose |
| Troubleshooting | A symptom-driven troubleshooting page |
| Quick lookup | A quick-reference page or table inside an existing reference page |
| Opinionated best practice | Best-practices page with scope and tradeoffs |
| One-off announcement | Usually not a durable doc; avoid adding unless explicitly requested |
If content has more than one natural home, choose the reader's first question, then cross-link from secondary locations.
Section Design Checklist
Before creating or moving pages:
- Define the primary reader and task.
- List the pages needed for a minimal complete section.
- Choose
README.md content: overview, page map, recommended reading path, and links.
- Assign route-friendly file names in English kebab-case, e.g.
project-setup.md.
- Assign stable
order values with gaps, e.g. 10, 20, 30, so future pages can fit between.
- Choose one category name per section unless the page clearly belongs to multiple categories.
- Decide whether the top-level section needs navbar exposure.
- Decide whether sidebar should be structure-generated or manually curated.
Navbar Strategy
- Top-level navbar is for primary reader journeys only.
- Keep labels short and Chinese.
- Use object format when page title is too long or icon needs override.
- Use dropdowns for secondary collections instead of crowding the top bar.
- Use root-relative links such as
/getting-started/.
Sidebar Strategy
- Use
children: "structure" for file-tree-owned sections.
- Use frontmatter
order for page order.
- Use frontmatter
index: false to exclude pages from sidebar/catalog.
- Use directory
README.md frontmatter dir for group metadata:
---
title: 工作流
icon: route
dir:
order: 20
text: 工作流
icon: route
collapsible: true
expanded: false
---
- Put more specific sidebar object keys before fallback
/ when using multiple sidebars.
Page Splitting Rules
Split a page when:
- It serves two different reader intents.
- It has more than one independent workflow.
- It mixes reference tables with tutorial steps and becomes hard to scan.
- It needs different validation or troubleshooting sections.
- It would force deep heading nesting beyond
###.
Keep a page together when:
- The sections are sequential steps in one workflow.
- Splitting would create tiny pages with no independent purpose.
- The page is a quick reference intentionally designed as a compact index.
Common Mistakes
| Mistake | Fix |
|---|
| Adding content to the first plausible page | Check reader task and section map first. |
Creating a directory without README.md | Add a landing page or use a single .md page instead. |
| Duplicating navbar and sidebar responsibilities | Navbar chooses journeys; sidebar exposes local hierarchy. |
Using order without gaps | Use increments such as 10 to leave insertion space. |
| Moving pages without fixing links | Search old paths and update relative links. |
Treating generated dist routes as source | Edit src and rebuild. |
Official Anchors
