Smart documentation organization - generates themed navigation indexes for large folders. Works seamlessly with Docusaurus preview.
Generates themed navigation indexes for large documentation folders by detecting themes like sync, hooks, and testing. Use this when folders exceed 30+ files to organize content without moving files or breaking URLs.
/plugin marketplace add anton-abyzov/specweave/plugin install sw-alternatives@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-docs:organize
# Analyze specific folder only
/sw-docs:organize --folder architecture/adr
# Preview without generating files
/sw-docs:organize --dry-run
# Force regeneration even if under threshold
/sw-docs:organize --force
# Set custom threshold (default: 30)
/sw-docs:organize --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(`\nGenerated ${generatedFiles.length} index files`);
}
_categories.md)Main navigation hub with:
_index-{theme}.md)Per-theme navigation with:
The organizer automatically detects these themes:
| Icon | Theme | Keywords |
|---|---|---|
| 🔄 | Synchronization | sync, integration, bidirectional |
| 🐙 | GitHub | github, issue, actions |
| 🪝 | Hooks | hook, event, trigger |
| 🔌 | External Tools | jira, ado, area-path |
| 🧪 | Testing | test, fixture, coverage |
| 🏗️ | Brownfield | brownfield, migration, legacy |
| ⚡ | Performance | cache, pagination, batch |
| 🔒 | Security | permission, auth, token |
| 📦 | Increments | increment, status, lifecycle |
| ⚙️ | Configuration | config, env, setup |
| 📚 | Documentation | doc, 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/sw-docs:health - Documentation health report