smom-dbis-138/docs/guides/AUTOMATED_LINK_CHECKING.md

Automated Link Checking Guide

Last Updated: 2025-01-27
Status: Active

This guide explains how to set up and use automated link checking for documentation.

Table of Contents

• Overview
• Tools
• Setup
• Usage
• CI/CD Integration
• Best Practices

Overview

Automated link checking helps maintain documentation quality by:

• Detecting broken internal links
• Detecting broken external links
• Finding orphaned files
• Ensuring link consistency

Tools

Recommended Tools

1. markdown-link-check - Fast markdown link checker
2. lychee - Fast link checker with caching
3. linkchecker - Comprehensive link checker
4. markdownlint - Markdown linter with link checking

Tool Comparison

Tool	Speed	Features	CI/CD Support
markdown-link-check	Fast	Basic	✅ Yes
lychee	Very Fast	Advanced	✅ Yes
linkchecker	Slow	Comprehensive	⚠️ Limited
markdownlint	Fast	Linting + Links	✅ Yes

Setup

Option 1: markdown-link-check (Recommended)

Installation:

npm install -g markdown-link-check

Usage:

# Check single file
markdown-link-check docs/README.md

# Check all markdown files
find docs -name "*.md" -exec markdown-link-check {} \;

Option 2: lychee (Fast Alternative)

Installation:

# Using cargo
cargo install lychee

# Or using homebrew
brew install lychee

Usage:

# Check all links
lychee docs/

# Check with caching
lychee --cache docs/

Option 3: markdownlint (Linting + Links)

Installation:

npm install -g markdownlint-cli
npm install -g markdownlint-cli2

Usage:

# Lint and check links
markdownlint docs/**/*.md

Usage

Basic Link Checking

# Check all documentation
markdown-link-check docs/**/*.md

# Check specific directory
markdown-link-check docs/guides/*.md

Advanced Options

# Ignore external links
markdown-link-check --quiet docs/README.md

# Include external links
markdown-link-check docs/README.md

# Verbose output
markdown-link-check --verbose docs/README.md

Script for All Files

Create scripts/automation/check-doc-links.sh:

#!/bin/bash
# Check all documentation links

set -e

echo "Checking documentation links..."

# Find all markdown files
find docs -name "*.md" -type f | while read file; do
    echo "Checking $file..."
    markdown-link-check "$file" || true
done

echo "Link check complete"

CI/CD Integration

GitHub Actions

name: Check Documentation Links

on:
  push:
    paths:
      - 'docs/**'
  pull_request:
    paths:
      - 'docs/**'

jobs:
  check-links:
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v3
      
      - name: Install markdown-link-check
        run: npm install -g markdown-link-check
      
      - name: Check links
        run: |
          find docs -name "*.md" -type f | while read file; do
            markdown-link-check "$file" || true
          done

Pre-commit Hook

Create .git/hooks/pre-commit:

#!/bin/bash
# Pre-commit hook to check documentation links

# Check only staged markdown files
git diff --cached --name-only --diff-filter=ACM | grep '\.md$' | while read file; do
    if [ -f "$file" ]; then
        echo "Checking links in $file..."
        markdown-link-check "$file" || exit 1
    fi
done

Best Practices

1. Regular Checks

• Run link checks before commits
• Run in CI/CD pipeline
• Schedule periodic checks

2. Fix Broken Links Promptly

• Fix broken links immediately
• Update outdated links
• Remove dead links

3. Use Relative Links

• Prefer relative links for internal docs
• Use absolute paths only when necessary
• Test links after moving files

4. Validate External Links

• Check external links periodically
• Update or remove broken external links
• Document external link dependencies

5. Handle False Positives

• Some links may be false positives
• Document exceptions
• Use ignore patterns when appropriate

Ignore Patterns

markdown-link-check

Create .markdown-link-check.json:

{
  "ignorePatterns": [
    {
      "pattern": "^http://localhost"
    },
    {
      "pattern": "^https://example.com"
    }
  ]
}

lychee

Create lychee.toml:

[output]
format = "markdown"

[exclude]
domains = ["localhost", "example.com"]

Related Documentation

• Documentation Style Guide
• Documentation Review Schedule
• Master Documentation Index

---

Last Updated: 2025-01-27