Summary

Add support for automatically refactoring heading links when headings are modified in markdown files.

Problem

Currently, markmv can track and update markdown links when files are moved, but it doesn't handle cases where heading content is modified. When headings change:

• Internal anchor links pointing to those headings become broken
• Links using heading-based slugs need manual updating
• Cross-file references to specific sections break silently

Current Capabilities

The codebase already has good foundation for this feature:

• TocGenerator (src/utils/toc-generator.ts) extracts headings and generates slugs
• LinkParser (src/core/link-parser.ts) identifies anchor links (#heading-slug)
• LinkRefactorer (src/core/link-refactorer.ts) updates link paths
• Comprehensive link tracking and validation infrastructure

Proposed Solution

Add a new command and capability:

CLI Interface

# Refactor headings in a file
markmv refactor-headings file.md --old-heading "Original Heading" --new-heading "Updated Heading"

# Refactor headings across multiple files
markmv refactor-headings docs/ --old-heading "API Reference" --new-heading "API Documentation" --recursive

Implementation Approach

1. Heading Detection: Use existing TocGenerator to extract current headings
2. Link Analysis: Use existing LinkParser to find anchor links
3. Slug Matching: Match old heading slugs to anchor links across files
4. Link Updates: Use existing LinkRefactorer patterns to update references
5. Validation: Ensure all heading references are updated consistently

Features

• Detect heading changes and find affected anchor links
• Update internal anchor links (#old-heading → #new-heading)
• Update cross-file heading references
• Support custom slug generation (align with existing TocGenerator.slugify)
• Dry-run mode for preview (consistent with other commands)
• Rollback support via existing TransactionManager
• Validation of heading link integrity after changes

Example Use Cases

1. Documentation Reorganization: Renaming sections and updating all references
2. Content Migration: Moving headings between files while preserving links
3. Consistency Enforcement: Standardizing heading formats across documentation
4. Refactoring Support: Updating technical documentation when code structure changes

Benefits

• Maintains link integrity during content reorganization
• Reduces manual effort in large documentation projects
• Leverages existing markmv infrastructure and patterns
• Provides safe operations with dry-run and rollback capabilities

Related Files

• src/utils/toc-generator.ts - Heading extraction and slug generation
• src/core/link-parser.ts - Link parsing and anchor detection
• src/core/link-refactorer.ts - Link updating infrastructure
• src/commands/ - Command structure patterns

This feature would extend markmv's excellent file movement capabilities to heading-level refactoring while maintaining the same quality standards and safety features.