Mono Docs

Appearance

Phase 1 Complete & Tested ✅ ​

Summary ​

The fix-links tool is production-ready and fully tested.

What It Does ​

Automatically fixes broken links detected by VitePress:

  1. Reads vitepress.build.txt for broken link reports
  2. Searches repository for moved files by filename
  3. Updates all references in markdown files and VitePress config
  4. Deletes links to truly missing files (cleanly)
  5. Preserves anchors, respects code blocks, handles both wikilinks and markdown links

Test Results - All Passing ✅ ​

Test scenario:

  • 2 broken links: one to a moved file, one to a deleted file
  • Multiple link types: wikilinks, markdown links, links with anchors
  • Links in code blocks to ensure they're not modified

Results:

  • ✅ All moved file references updated correctly
  • ✅ All deleted file references removed cleanly (no leftover bullets)
  • ✅ Anchors preserved (#section-one)
  • ✅ Code block links unchanged
  • ✅ VitePress config updated (moved link corrected, deleted entry removed)

Files Created ​

notes/tools/
  ├── fix-links.ts              # Main tool
  ├── test.sh                   # Test runner script
  ├── tsconfig.json             # TypeScript config
  ├── lib/
  │   ├── markdown-parser.ts    # Parse & update markdown
  │   ├── link-finder.ts        # Search for files
  │   └── config-updater.ts     # Update VitePress config
  └── dist/                     # Compiled JavaScript (generated)

Usage ​

Compile:

bash
cd /Users/sand/GitHub/webseriously/notes/tools
npx tsc

Run on test fixtures:

bash
cd /Users/sand/GitHub/webseriously
node notes/tools/dist/fix-links.js --test -v

Run on production:

bash
cd /Users/sand/GitHub/webseriously
node notes/tools/dist/fix-links.js -v

Next Steps ​

  1. Update CLAUDE.MD - Add fix-links to update docs workflow
  2. Test on real docs - Run on actual documentation (not just fixtures)
  3. Move to Phase 2 - Begin implementing merge-files.ts

Integration for CLAUDE.MD ​

Add this after yarn docs:build:

bash
# Compile and run fix-links
cd notes/tools && npx tsc && cd ../..
node notes/tools/dist/fix-links.js
if [ $? -ne 0 ]; then
  echo "❌ Link fixing failed, check logs"
  exit 1
fi
echo "✅ Links fixed successfully"

Or simpler (requires tsx):

bash
npx tsx notes/tools/fix-links.ts

Status: READY FOR PRODUCTION 🚀