Skip to content

MkDocs Link Fixer - Enhancement Proposal

Overview

The current fix-links-simple.sh script provides a foundation for a potentially valuable tool for the broader MkDocs community. This document outlines a proposal to enhance and extend this script into a full-featured solution for maintaining documentation cross-references during reorganizations.

Problem Statement

Documentation reorganizations frequently lead to broken cross-references, especially in large projects. When files are moved, renamed, or restructured (particularly when transitioning from flat structures to nested ones), maintaining correct internal links becomes challenging. This is a common pain point across the MkDocs ecosystem.

Current Solution

Our current fix-links-simple.sh script provides:

  • Detection and fixing of standard Markdown links
  • Support for directory-style links (with trailing slashes)
  • Mapping-based approach for link transformations
  • Detailed metrics and reporting
  • Support for dry-run preview

Enhancement Vision

Core Functionality Improvements

  1. MkDocs Configuration Integration
  2. Parse mkdocs.yml to understand the navigation structure
  3. Auto-generate mappings based on the navigation hierarchy

  4. Support navigation structure changes between versions

  5. Dynamic Mapping Generation

  6. Detect common patterns (like dir.md → dir/index.md) automatically
  7. Generate mappings by scanning directory structure

  8. Option to auto-detect moved files using git history

  9. Extensible Path Strategies

  10. Support different link path strategies (relative vs. absolute)
  11. Handle MkDocs' specific URL handling and path normalization

  12. Support various permalink styles

  13. Enhanced Reporting

  14. Generate HTML reports with clickable links
  15. Provide visualization of link changes

  16. Integration with MkDocs build process (as a plugin)

  17. Cross-Repository Support

  18. Handle documentation spread across multiple repositories

  19. Support for versioned documentation

  20. Interactive Mode

  21. Prompt for confirmation on complex changes

  22. Suggest fixes for ambiguous cases

  23. Advanced Features

  24. Link validity checking against live site
  25. Support for API documentation integration
  26. Support for multiple documentation formats (Markdown, reStructuredText)

Technical Implementation Options

  1. Standalone Tool
  2. Create a proper Python package installable via pip
  3. Add proper command-line interface with argparse

  4. Include comprehensive documentation

  5. MkDocs Plugin

  6. Create a plugin that runs during the build process
  7. Add hooks for pre-build and post-build phases

  8. Integrate with MkDocs' internal link processing

  9. CI/CD Integration

  10. Package as a GitHub Action for CI/CD workflows
  11. Automate documentation maintenance in PRs

Implementation Roadmap

Phase 1: Foundation (1-2 months)

  • Rewrite script in Python for better maintainability and cross-platform support
  • Implement proper command-line interface
  • Add unit tests for core functionality
  • Create basic documentation

Phase 2: Advanced Features (2-3 months)

  • Add MkDocs configuration parsing
  • Implement dynamic mapping generation
  • Add interactive mode
  • Enhance reporting with HTML output

Phase 3: Integration (1-2 months)

  • Develop MkDocs plugin version
  • Create GitHub Action
  • Add CI/CD integration examples

Phase 4: Community Engagement (Ongoing)

  • Submit to MkDocs community resources
  • Share on documentation forums
  • Create a dedicated repository with contribution guidelines
  • Collect and implement community feedback

Resource Requirements

  • Development time: 4-7 months (part-time)
  • Testing environments for various MkDocs configurations
  • Documentation hosting

Benefits

  • Reduce maintenance burden for documentation reorganizations
  • Improve documentation quality by maintaining correct cross-references
  • Enhance MkDocs ecosystem with specialized tooling
  • Potential to become a standard tool in documentation maintenance workflows

Next Steps

  1. Seek feedback on this proposal from the team
  2. Evaluate resource availability for initial development
  3. Create a prototype Python implementation
  4. Test with our existing documentation to validate approach

References