Mono Docs

Appearance

Phase 1 Implementation Complete ​

What Was Built ​

Core Library Components ​

lib/markdown-parser.ts

  • Parses markdown files to extract links (both wikilinks [[file]] and markdown links [text](file.md))
  • Respects code blocks (doesn't parse links inside triple backticks)
  • Updates links in markdown files with replacements
  • Preserves anchors when updating links (e.g., file.md#section)
  • Handles link deletion (when replacement is null)

lib/link-finder.ts

  • Searches repository for files by filename
  • Returns all matches with full paths
  • Handles multiple matches (prompts user or skips - currently skips for automation)
  • Skips common directories (node_modules, .git, dist, build, .vitepress)

lib/config-updater.ts

  • Parses VitePress config.mts files
  • Updates sidebar link entries
  • Removes entries for deleted files
  • Normalizes file paths to VitePress link format (/notes/path/file without .md)

Main Tool ​

fix-links.ts

  • Reads broken links from vitepress.build.txt (or test fixture)
  • Groups links by target to avoid duplicate searches
  • For each broken link target:
    • Searches repo for matching filename
    • If found: updates all references
    • If not found: deletes all references
    • If multiple matches: marks as unfixable (needs user intervention)
  • Updates all markdown files in /notes
  • Updates VitePress config
  • Provides summary: fixed, deleted, unfixable counts
  • Supports --test flag for test mode
  • Supports -v flag for verbose output
  • Exit codes: 0 (success), 1 (error), 2 (warning/unfixable)

Test Fixtures Created ​

Location: /notes/work/test-fixtures/

Files:

  • index.md - Contains various test links (wikilinks, markdown links, links with anchors, links in code blocks)
  • advanced/test-moved.md - File that was "moved" from guides/ to advanced/
  • vitepress.build.txt - Simulates VitePress broken link report
  • config.mts - Test VitePress config with sidebar entries

Test Scenario:

  • index.md has links to guides/test-moved.md (which exists at advanced/test-moved.md)
  • index.md has links to guides/test-deleted.md (which doesn't exist)
  • vitepress.build.txt reports both as broken

Expected Behavior:

  • Links to test-moved.md should update to notes/work/test-fixtures/advanced/test-moved.md
  • Links to test-deleted.md should be deleted
  • Links in code blocks should NOT be modified
  • Anchors should be preserved (e.g., #section-one)
  • Config sidebar entries should be updated/removed accordingly

How to Test ​

Option 1: Run with npx (if ts-node works) ​

bash
cd /Users/sand/GitHub/webseriously
npx ts-node --esm notes/tools/fix-links.ts --test -v

Option 2: Compile to JavaScript first ​

bash
cd /Users/sand/GitHub/webseriously
npx tsc notes/tools/**/*.ts --outDir notes/tools/dist --module es2020 --target es2020
node notes/tools/dist/fix-links.js --test -v

Option 3: Use the test runner ​

bash
cd /Users/sand/GitHub/webseriously
node notes/tools/test-runner.mjs

What to Verify ​

After running the tool in test mode, check:

  1. index.md - Links should be updated:

    • [[./fixtures/advanced/test-moved]] → [[./fixtures/advanced/test-moved]]
    • [Link to moved file](./fixtures/advanced/test-moved.md) → [Link to moved file](./fixtures/advanced/test-moved.md)
    • [Link with anchor](./fixtures/advanced/test-moved.md#section-one) → [Link with anchor](./fixtures/advanced/test-moved.md#section-one)
    • Links to test-deleted.md should be GONE
    • Links in code block should be UNCHANGED

  2. config.mts - Sidebar should be updated:

    • test-moved link should point to new location
    • test-deleted entry should be removed

  3. Console output - Should show:

    • Fixed: 6 (3 wikilinks + 3 markdown links to test-moved)
    • Deleted: 2 (links to test-deleted)
    • Unfixable: 0

Next Steps ​

Once testing confirms Phase 1 works:

  • [ ] Update CLAUDE.MD update docs command to run fix-links.ts
  • [ ] Mark Phase 1 tasks as complete in redox.md
  • [ ] Begin Phase 2 (merge-files.ts)