Documentation Restructuring Plan

Problem

Two documentation files are too large:

registry.md: 1,089 lines
EXTERNAL-TOOLS.md: 547 lines

Solution

Split into smaller, focused files using @path/to/file.md import feature discovered from deepwiki.

New Structure

EXTERNAL-TOOLS.md → Split (547 lines)

Main index: EXTERNAL-TOOLS.md (with @imports)

docs/external-tools/
├── 00-index.md                 # Overview & TOC
├── essential/                  # 基础必备（7个工具）
│   ├── fzf.md                 # 模糊查找
│   ├── eza.md                 # 文件列表
│   ├── zoxide.md              # 目录导航
│   ├── fd.md                  # 文件搜索
│   ├── bat.md                 # 文件查看
│   ├── ripgrep.md             # 代码搜索
│   └── starship.md            # Shell提示符
├── advanced/                   # 进阶推荐（3个工具）
│   ├── jq.md                  # JSON处理
│   ├── zellij.md              # 终端复用
│   └── procs.md               # 进程查看
└── expert/                     # 专家级（2个工具）
    ├── just.md                # 任务运行器
    └── hyperfine.md           # 性能测试

registry.md → Split (1,089 lines)

Main index: registry.md (with @imports)

docs/registry/
├── 00-overview.md              # Philosophy & concepts
├── 01-quickstart.md            # Quick start guide
├── 02-tool-categories.md       # Category explanations
├── 03-external-integration.md  # External tools philosophy
├── 04-creating-tools.md        # How to create tools
├── TOC.md                      # Table of contents
└── internal-tools/             # Individual tool docs
    ├── service-checker.md
    ├── dependency-analyzer.md
    ├── code-stats.md
    └── api-tester.md

Implementation Strategy

Phase 1: Create new docs/ directory structure
Phase 2: Split EXTERNAL-TOOLS.md (easier, 547 lines)
Phase 3: Split registry.md (larger, 1,089 lines)
Phase 4: Update main index files with @imports
Phase 5: Test and verify

Key Benefits

✅ Better maintainability - Each tool/file is self-contained ✅ Faster loading - AI assistant can load only needed sections ✅ Easier updates - Modify individual tools without affecting others ✅ Clear organization - Hierarchical structure by category ✅ Reusable - Individual tool docs can be referenced elsewhere

Import Usage Example

New EXTERNAL-TOOLS.md:

# External Tools

@docs/external-tools/00-index.md

## Essential Tools

@docs/external-tools/essential/fzf.md
@docs/external-tools/essential/eza.md
@docs/external-tools/essential/zoxide.md
# ...etc

2.8 KiB Raw Permalink Blame History Unescape Escape