Back to Details

documentation-structure

Compare original and translation side by side

🇺🇸

Original

English
🇨🇳

Translation

Chinese

Documentation Structure

文档结构

This skill defines how documentation is organized and maintained in this repository.
本Skill定义了本仓库中文档的组织和维护方式。

Core Principles

核心原则

PrincipleDescription
Separation of ConcernsREADME (landing), docs/ (reference), CONTRIBUTING (dev workflow)
Single Source of TruthDefine once, link everywhere. Never duplicate content.
Hub-and-Spoke
docs/README.md
is the central navigation hub
Vendor IsolationEach AI platform gets its own directory in docs/
原则描述
关注点分离README（首页）、docs/（参考文档）、CONTRIBUTING（开发工作流）
单一数据源内容仅定义一次，各处通过链接引用。绝不重复内容。
中心辐射模式
docs/README.md
是中央导航枢纽
供应商隔离每个AI平台在docs/目录下拥有独立的子目录

Document Responsibilities

文档职责

User vs Developer Content Separation

用户与开发者内容分离

CRITICAL RULE: User documentation must ONLY contain fully automated installation methods. All manual setup belongs in developer documentation.
Content TypeUser DocsDeveloper Docs
Marketplace install✓✓
One-command GitHub install✓✓
git clone✗✓
--plugin-dir✗✓
extensions link✗✓
JSON config editing✗✓
Local path setup✗✓
mcp_settings.json✗✓
关键规则： 用户文档只能包含完全自动化的安装方法。所有手动设置内容均属于开发者文档。
内容类型用户文档开发者文档
应用市场安装✓✓
一键GitHub安装✓✓
git clone✗✓
--plugin-dir✗✓
扩展链接✗✓
JSON配置编辑✗✓
本地路径设置✗✓
mcp_settings.json✗✓

User Documentation (README.md, docs/*/overview.md)

用户文档（README.md、docs/*/overview.md）

  • Installation must be copy-paste simple
  • Single command or UI-only steps
  • Link to dev docs for manual alternatives
  • 安装步骤必须简单到可直接复制粘贴
  • 仅包含单命令或纯UI操作步骤
  • 手动替代方案请链接至开发者文档

Developer Documentation (CONTRIBUTING.md, docs//-development.md)

开发者文档（CONTRIBUTING.md、docs//-development.md）

  • All manual setup workflows
  • Local testing procedures
  • Configuration file editing
  • Environment setup
  • 包含所有手动设置工作流
  • 本地测试流程
  • 配置文件编辑方法
  • 环境搭建步骤

README.md (Landing Page)

README.md（首页）

Purpose: First impression. Get users started quickly.
Must include:
  • One-line description
  • Quick Start (4 steps: Choose → Install → Authenticate → Try)
  • Capability tables (what users can do)
  • Links to docs/ for details
Must NOT include:
  • Full API reference (→ docs/mcp/)
  • Development workflows (→ CONTRIBUTING.md)
  • Detailed architecture (→ docs/)
用途： 给用户的第一印象，帮助用户快速上手。
必须包含：
  • 一句话描述
  • 快速开始（4步：选择 → 安装 → 认证 → 试用）
  • 功能能力表格（用户可实现的操作）
  • 指向docs/目录的详情链接
禁止包含：
  • 完整API参考（→ docs/mcp/）
  • 开发工作流（→ CONTRIBUTING.md）
  • 详细架构说明（→ docs/）

docs/ (Reference Documentation)

docs/（参考文档）

Purpose: Complete reference for users and developers.
Structure:
docs/
├── README.md              # Navigation hub
├── troubleshooting.md     # Cross-platform issues
├── getting-started/       # Entry points
│   ├── mcp-setup.md       # Generic MCP config
│   └── enterprise.md      # Admin requirements
├── claude-code/           # Vendor: Claude Code
├── kiro/                  # Vendor: Kiro
├── gemini-cli/            # Vendor: Gemini CLI
└── mcp/                   # Protocol reference
    ├── tools-reference.md
    └── tutorials.md
用途： 面向用户和开发者的完整参考资料。
结构：
docs/
├── README.md              # 导航枢纽
├── troubleshooting.md     # 跨平台问题排查
├── getting-started/       # 入门指南
│   ├── mcp-setup.md       # 通用MCP配置
│   └── enterprise.md      # 管理员要求
├── claude-code/           # 供应商：Claude Code
├── kiro/                  # 供应商：Kiro
├── gemini-cli/            # 供应商：Gemini CLI
└── mcp/                   # 协议参考
    ├── tools-reference.md
    └── tutorials.md

CONTRIBUTING.md (Development Workflow)

CONTRIBUTING.md（开发工作流）

Purpose: How to modify THIS repository.
Must include:
  • Clone and local dev setup
  • How to test changes locally (
    --plugin-dir
    , etc.)
  • Validation checklists
  • PR process
Must NOT include:
  • Full plugin/power architecture (→ docs/)
  • User-facing tutorials (→ docs/)
用途： 说明如何修改本仓库。
必须包含：
  • 克隆与本地开发环境搭建
  • 如何在本地测试变更（
    --plugin-dir
    等）
  • 验证检查清单
  • PR流程
禁止包含：
  • 完整插件/能力架构（→ docs/）
  • 面向用户的教程（→ docs/）

Vendor Documentation Standards

供应商文档标准

Each vendor directory in 
docs/
follows this pattern:
docs/目录下的每个供应商子目录需遵循以下模式：

Required Files

必填文件

FilePurpose
overview.md
What is this integration, why use it, installation
*-development.md
How to build new plugins/powers/extensions
Individual component docsOne file per plugin/power
文件用途
overview.md
该集成是什么、为何使用它、安装方法
*-development.md
如何构建新插件/能力/扩展
独立组件文档每个插件/能力对应一个文件

Standard Sections in overview.md

overview.md中的标准章节

markdown
undefined
markdown
undefined

What are [Plugins/Powers/Extensions]?

什么是[插件/能力/扩展]？

Why Use [Plugins/Powers] vs Direct MCP?

为何使用[插件/能力]而非直接MCP？

Available [Plugins/Powers]

可用[插件/能力]列表

Installation

安装方法

Authentication

认证方式

Related

相关链接

undefined
undefined

Vendor-Specific Metadata

供应商特定元数据

VendorConfig FormatLocation
Claude Code
plugin.json
.claude-plugin/plugin.json
KiroPOWER.md frontmatter
POWER.md
Gemini CLIJSON extension
gemini-extension.json
供应商配置格式位置
Claude Code
plugin.json
.claude-plugin/plugin.json
KiroPOWER.md 前置元数据
POWER.md
Gemini CLIJSON扩展
gemini-extension.json

Cross-Reference Patterns

交叉引用模式

Link Format

链接格式

  • Within docs/: Use relative paths 
    [text](../mcp/tools-reference.md)
  • From README to docs/: Use 
    docs/
    prefix 
    [text](docs/claude-code/overview.md)
  • External links: Full URLs 
    [text](https://developers.miro.com)
  • docs/目录内部： 使用相对路径 
    [text](../mcp/tools-reference.md)
  • 从README到docs/： 使用
    docs/
    前缀 
    [text](docs/claude-code/overview.md)
  • 外部链接： 使用完整URL 
    [text](https://developers.miro.com)

Required "Related" Section

必填的“相关链接”章节

Every doc file should end with a Related section:
markdown
undefined
每个文档文件末尾应包含“相关链接”章节：
markdown
undefined

Related

相关链接

  • Overview - Introduction to this integration
  • Tools Reference - MCP tool documentation
undefined
  • 概述 - 本集成介绍
  • 工具参考 - MCP工具文档
undefined

Reciprocal Links

双向链接

If doc A links to doc B, doc B should link back to doc A in its Related section.
如果文档A链接到文档B，文档B的“相关链接”章节中也应链接回文档A。

Validation Guidelines

验证指南

Before committing documentation changes:
提交文档变更前，请进行以下检查：

Content Checks

内容检查

  • No duplicated content (link instead)
  • Correct document owns the content (README vs docs/ vs CONTRIBUTING)
  • All sections present per vendor standards
  • 无重复内容（应使用链接替代）
  • 内容归属正确的文档（README vs docs/ vs CONTRIBUTING）
  • 符合供应商标准的所有章节均已包含

Link Checks

链接检查

  • All internal links resolve
  • Related sections have reciprocal links
  • External links use HTTPS
  • 所有内部链接可正常访问
  • 相关链接章节包含双向链接
  • 外部链接使用HTTPS

Format Checks

格式检查

  • Code blocks have language specified
  • Tables have consistent formatting
  • Collapsibles have matching tags
  • 代码块已指定语言
  • 表格格式一致
  • 可折叠区块标签匹配

See Also

另请参阅

  • references/patterns.md
    - Formatting patterns (tables, collapsibles, code blocks)
  • references/patterns.md
    - 格式规范（表格、可折叠区块、代码块）