Skip to content

Link Maintenance Guide

This guide documents the processes and tools for maintaining link health across the Ultimate MkDocs documentation site.

Overview

Link maintenance is critical for user experience and SEO. This guide covers:

  • Automated link checking via pre-commit hooks
  • Manual link validation processes
  • Common link issues and their solutions
  • Best practices for creating maintainable links

Pre-commit Hook Integration

The project uses automated link checking through pre-commit hooks to catch broken links before they reach production.

Configuration location: .pre-commit-config.yaml

- repo: local
  hooks:
    - id: link-check
      name: Internal link validation
      entry: python
      language: system
      args: [tests/test_links.py, --check-internal-only]
      files: \.md$
      pass_filenames: false

Location: tests/test_links.py

The link checker validates: - Internal markdown links - Asset references (images, files) - Navigation references - Anchor links within pages

Exclusions (automatically skipped): - HTML-encoded email addresses - Template placeholders [VARIABLE] - Intentional demo broken links - External URLs (optional flag)

# Via pre-commit (runs on git commit)
git commit -m "Your changes"

# Manual pre-commit run
pre-commit run link-check --all-files

Manual Validation

# Check internal links only
python tests/test_links.py --check-internal-only

# Build site first if needed
mkdocs build --clean
python tests/test_links.py --check-internal-only

CI/CD Integration

The link checker is configured to skip in CI environments to avoid timeouts: 

ci:
  skip: [mkdocs-build-check, link-check]

1. Missing Asset Files

Problem: References to non-existent images or files 

Error: Broken link in features/diagrams.md: ../assets/images/missing-diagram.png

Solutions: - Create the missing asset file - Update the reference to point to an existing file - Remove the reference if no longer needed

2. Broken Internal Navigation

Problem: Links to missing documentation pages 

Error: Broken link in api/calculator.md: ../features/missing-page.md

Solutions: - Create the missing page with appropriate content - Update the link to point to the correct existing page - Use relative paths correctly (../ for parent directory)

3. Incorrect Anchor References

Problem: Links to non-existent page sections 

Error: Broken link in getting-started/index.md: configuration.md#missing-section

Solutions: - Verify the target page has the referenced section - Update the anchor to match the actual section heading - Use the correct anchor format (lowercase, hyphens for spaces)

4. Template Placeholder Issues

Problem: Unresolved template variables in links 

Error: Broken link in brand/templates/guide.md: {{ site.url }}/example

Solutions: - Replace template variables with actual values - Add exclusion pattern for legitimate template files - Move template files to appropriate template directories

Use relative paths: 

✅ Good: [Configuration](../getting-started/configuration.md)
❌ Avoid: [Configuration](/getting-started/configuration.md)

Include file extensions: 

✅ Good: [API Reference](api/calculator.md)
❌ Avoid: [API Reference](api/calculator)

Use descriptive anchor text: 

✅ Good: [MkDocs configuration guide](configuration.md)
❌ Avoid: [Click here](configuration.md)

Asset References

Use consistent paths: 

✅ Good: <img loading="lazy" src="../assets/images/architecture.svg" alt="Diagram">
❌ Avoid: <img loading="lazy" src="../../docs/assets/images/architecture.svg" alt="Diagram">

Provide alt text: 

✅ Good: <img loading="lazy" src="../assets/images/architecture.svg" alt="System architecture diagram">
❌ Avoid: <img loading="lazy" src="../assets/images/architecture.svg" alt="">

Keep directory structure logical: 

docs/
├── getting-started/
│   ├── index.md
│   └── configuration.md
├── features/
│   ├── index.md
│   └── advanced-features.md
└── api/
    ├── index.md
    └── reference.md

Maintenance Workflow

Weekly Maintenance

  1. Run full link check: 

    mkdocs build --clean
python tests/test_links.py

  2. Review any new broken links

  3. Update or fix broken references
  4. Commit fixes with descriptive messages

After Content Updates

  1. Test locally before committing: 

    mkdocs serve
# Verify links work in browser

  2. Run pre-commit hooks: 

    pre-commit run --all-files

  3. Address any link failures before merging

Monthly Audits

  1. Check external link health (if enabled)
  2. Review link patterns for consistency
  3. Update documentation as needed
  4. Optimize asset organization if needed

Troubleshooting

If the link checker reports valid links as broken:

  1. Check file existence: 

    ls -la docs/path/to/file.md

  2. Verify link syntax:

  3. No spaces in file names
  4. Correct file extension

  5. Proper relative path construction

  6. Update exclusion patterns if needed in tests/test_links.py

Performance Issues

If link checking is slow:

  1. Use build caching: 

    mkdocs build  # Don't use --clean every time

  2. Skip in CI (already configured)

  3. Reduce scope to specific directories: 

    python tests/test_links.py --path=docs/specific-section/

Build Integration Issues

If pre-commit hooks fail consistently:

  1. Check dependencies: 

    pip install -r requirements.txt

  2. Update pre-commit: 

    pre-commit autoupdate

  3. Skip specific checks temporarily: 

    git commit --no-verify -m "Emergency fix"

Tools and Configuration

Essential Files

  • .pre-commit-config.yaml - Hook configuration
  • tests/test_links.py - Link validation script
  • mkdocs.yml - Site configuration
  • This guide (docs/team/link-maintenance-guide.md)

Useful Commands

# Quick link check
python tests/test_links.py --check-internal-only

# Full validation with external links
python tests/test_links.py

# Build and validate
mkdocs build --clean && python tests/test_links.py

# Pre-commit specific hook
pre-commit run link-check

# Fix common formatting issues
pre-commit run --all-files

Integration with Development Workflow

For Contributors

  1. Before making changes: Understand the link structure
  2. When adding content: Follow link best practices
  3. Before committing: Ensure pre-commit hooks pass
  4. In pull requests: Check that no new broken links are introduced

For Maintainers

  1. Regular audits: Monthly link health checks
  2. Update patterns: Keep exclusion patterns current
  3. Performance monitoring: Watch for link checker slowdowns
  4. Documentation updates: Keep this guide current

Success Metrics

Based on the Task #66 implementation:

  • Reduced broken links: From 83 to 33 (60% improvement)
  • Enhanced detection: Added filters for false positives
  • Automated fixing: Pre-commit hooks handle formatting
  • Comprehensive coverage: All link types validated

Future Enhancements

Consider implementing:

  1. External link validation (with rate limiting)
  2. Link health dashboards for monitoring
  3. Automated link fixing for common patterns
  4. Integration with CI/CD for blocking deployments
  5. Performance optimizations for large sites

This guide ensures consistent link quality and helps maintain the professional standard of the Ultimate MkDocs documentation platform.