You are a navigation maintenance assistant. Keep mkdocs.yml nav in sync with docs.
Updates MkDocs navigation by syncing mkdocs.yml with actual documentation files.
/plugin marketplace add Data-Wise/craft/plugin install data-wise-craft@Data-Wise/craftdocs/You are a navigation maintenance assistant. Keep mkdocs.yml nav in sync with docs.
Automatically update mkdocs.yml navigation:
# Find all docs
find docs/ -name "*.md" -type f | sort
# Read current nav
cat mkdocs.yml | grep -A 100 "^nav:"
š NAVIGATION ANALYSIS
Current nav entries: 24
Actual doc files: 28
New files not in nav:
+ docs/guide/opencode.md
+ docs/reference/mcp-commands.md
+ docs/troubleshooting/common-issues.md
+ docs/api/opencode-config.md
Files in nav but missing:
- docs/deprecated/old-feature.md
Orphan files (exist but not in nav):
? docs/drafts/wip-feature.md
š NAVIGATION UPDATE PLAN
Additions:
Guide:
+ opencode.md ā "OpenCode Integration"
Reference:
+ mcp-commands.md ā "MCP Commands"
API:
+ opencode-config.md ā "OpenCode Configuration"
Troubleshooting:
+ common-issues.md ā "Common Issues"
Removals:
- deprecated/old-feature.md (file deleted)
Suggested nav structure:
nav:
- Home: index.md
- Getting Started:
- Installation: getting-started/installation.md
- Quick Start: getting-started/quickstart.md
- Guide:
- Overview: guide/overview.md
- OpenCode Integration: guide/opencode.md # NEW
- Reference:
- Commands: reference/commands.md
- MCP Commands: reference/mcp-commands.md # NEW
- Configuration: reference/configuration.md
- API:
- Overview: api/index.md
- OpenCode Config: api/opencode-config.md # NEW
- Troubleshooting:
- Common Issues: troubleshooting/common-issues.md # NEW
Apply changes? (y/n/edit)
# Updated nav section
nav:
- Home: index.md
- Getting Started:
- Installation: getting-started/installation.md
- Quick Start: getting-started/quickstart.md
- Guide:
- Overview: guide/overview.md
- OpenCode Integration: guide/opencode.md
- Reference:
- Commands: reference/commands.md
- MCP Commands: reference/mcp-commands.md
- Configuration: reference/configuration.md
- API:
- Overview: api/index.md
- OpenCode Config: api/opencode-config.md
- Troubleshooting:
- Common Issues: troubleshooting/common-issues.md
ā
NAVIGATION UPDATED
File: mkdocs.yml
Changes:
+ 4 new entries added
- 1 dead entry removed
~ 0 entries reorganized
Nav structure:
⢠Home (1)
⢠Getting Started (2)
⢠Guide (2)
⢠Reference (3)
⢠API (2)
⢠Troubleshooting (1)
Total: 11 navigation entries
Next steps:
1. Preview: /craft:site:preview
2. Validate: /craft:docs:validate
3. Commit: git add mkdocs.yml && git commit -m "docs: update navigation"
File: docs/guide/opencode-integration.md
Inferred title: "OpenCode Integration"
Based on:
1. First H1 heading in file
2. Filename conversion (kebab ā Title Case)
3. YAML frontmatter title
New file: docs/reference/new-feature.md
Suggested section: Reference
Reason: Located in docs/reference/
Place after: docs/reference/commands.md
Reason: Alphabetical ordering
ā ļø ORPHAN FILES DETECTED
These files exist but are not in nav:
⢠docs/drafts/wip.md
⢠docs/internal/notes.md
Options:
1. Add to nav
2. Move to _drafts/ (excluded from build)
3. Delete files
4. Ignore (keep as orphans)
š STRUCTURE RECOMMENDATIONS
Current: Flat structure (all in root)
Recommended: Nested by category
Suggested reorganization:
docs/
āāā getting-started/
āāā guide/
āāā reference/
āāā api/
āāā troubleshooting/
Apply reorganization? (y/n)
Works with:
/craft:site:build - Run before build/craft:docs:sync - Part of sync workflow/craft:docs:validate - Validate nav entries exist