87 lines
2.8 KiB
Markdown
87 lines
2.8 KiB
Markdown
# 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
|
||
|
||
1. **Phase 1**: Create new `docs/` directory structure
|
||
2. **Phase 2**: Split EXTERNAL-TOOLS.md (easier, 547 lines)
|
||
3. **Phase 3**: Split registry.md (larger, 1,089 lines)
|
||
4. **Phase 4**: Update main index files with @imports
|
||
5. **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`:
|
||
```markdown
|
||
# 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
|
||
```
|