Smart documentation organization - generates themed navigation indexes for large folders. Works seamlessly with Docusaurus preview.
Automatically organizes large documentation folders by detecting themes and generating navigable category indexes without moving files. Use when folders have 30+ files and navigation becomes painful.
/plugin marketplace add anton-abyzov/specweave/plugin install sw@specweaveAutomatically organize large documentation folders by detecting themes and generating navigable category indexes.
When folders grow beyond 30+ files, navigation becomes painful:
Solution: Generate themed category indexes WITHOUT moving files (preserves URLs).
# Analyze and organize all internal docs
/sw:organize-docs
# Analyze specific folder only
/sw:organize-docs --folder architecture/adr
# Preview without generating files
/sw:organize-docs --dry-run
# Force regeneration even if under threshold
/sw:organize-docs --force
# Set custom threshold (default: 30)
/sw:organize-docs --threshold 20
Execute the smart documentation organizer:
import { SmartDocOrganizer, organizeDocumentation } from '../../src/living-docs/smart-doc-organizer.js';
import * as path from 'path';
const projectPath = process.cwd();
// Option 1: Quick organize all internal docs
const result = await organizeDocumentation(projectPath, {
dryRun: false, // Set true to preview
thresholdForOrganization: 30,
});
console.log(result.summary);
// Option 2: Analyze specific folder
const organizer = new SmartDocOrganizer({
projectPath,
thresholdForOrganization: 30,
generateIndexes: true,
dryRun: false,
});
const adrPath = path.join(projectPath, '.specweave/docs/internal/architecture/adr');
const plan = await organizer.analyzeFolder(adrPath);
console.log(`
๐ DOCUMENTATION ANALYSIS
โโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโ
Folder: ${plan.folder}
Total Files: ${plan.totalFiles}
Needs Organization: ${plan.needsOrganization ? 'โ
Yes' : 'โ No'}
Theme Categories:
${plan.themeCategories
.filter(c => c.count >= 3)
.map(c => ` ${c.theme.icon} ${c.theme.name}: ${c.count} files`)
.join('\n')}
Uncategorized: ${plan.uncategorized.length} files
`);
// Generate indexes if needed
if (plan.needsOrganization) {
const generatedFiles = await organizer.generateCategoryIndexes(plan);
console.log(`\nโ
Generated ${generatedFiles.length} index files`);
}
_categories.md)Main navigation hub with:
_index-{theme}.md)Per-theme navigation with:
The organizer automatically detects these themes:
| Theme | Keywords | Icon |
|---|---|---|
| Synchronization | sync, integration, bidirectional | ๐ |
| Hooks & Events | hook, event, trigger, callback | ๐ช |
| GitHub | github, issue, pull-request, actions | ๐ |
| External Tools | jira, ado, azure-devops, area-path | ๐ |
| Testing | test, fixture, mock, coverage, tdd | ๐งช |
| Brownfield | brownfield, migration, legacy | ๐๏ธ |
| Architecture | pattern, factory, abstraction | ๐๏ธ |
| Performance | cache, pagination, batch, lazy | โก |
| Security | permission, auth, token, secret | ๐ |
| Increments | increment, status, lifecycle | ๐ฆ |
| Configuration | config, env, setup, init | โ๏ธ |
| Documentation | doc, living, spec, naming | ๐ |
๐ DOCUMENTATION ANALYSIS
โโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโ
Folder: architecture/adr
Total Files: 147
Needs Organization: โ
Yes
Theme Categories:
๐ Synchronization & Integration: 23 files
๐ GitHub Integration: 18 files
๐ช Hooks & Events: 15 files
๐งช Testing & Quality: 12 files
๐ External Tools (ADO, JIRA): 11 files
๐ฆ Increment Lifecycle: 10 files
โก Performance & Optimization: 9 files
โ๏ธ Configuration & Setup: 8 files
Uncategorized: 14 files
โ
Generated 9 index files:
- _categories.md
- _index-sync.md
- _index-github.md
- _index-hooks.md
- _index-testing.md
- _index-external-tools.md
- _index-increments.md
- _index-performance.md
- _index-config.md
After running this command, use:
/sw-docs:view
The generated indexes will appear in the sidebar:
/sw-docs:view - View documentation with Docusaurus/sw-docs:build - Build static documentation site