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](#overview)
- [Tools](#tools)
- [Setup](#setup)
- [Usage](#usage)
- [CI/CD Integration](#cicd-integration)
- [Best Practices](#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**:
```bash
npm install -g markdown-link-check
```

**Usage**:
```bash
# 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**:
```bash
# Using cargo
cargo install lychee

# Or using homebrew
brew install lychee
```

**Usage**:
```bash
# Check all links
lychee docs/

# Check with caching
lychee --cache docs/
```

### Option 3: markdownlint (Linting + Links)

**Installation**:
```bash
npm install -g markdownlint-cli
npm install -g markdownlint-cli2
```

**Usage**:
```bash
# Lint and check links
markdownlint docs/**/*.md
```

## Usage

### Basic Link Checking

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

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

### Advanced Options

```bash
# 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`:

```bash
#!/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

```yaml
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`:

```bash
#!/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`:

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

### lychee

Create `lychee.toml`:

```toml
[output]
format = "markdown"

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

## Related Documentation

- [Documentation Style Guide](../governance/DOCUMENTATION_STYLE_GUIDE.md)
- [Documentation Review Schedule](../governance/DOCUMENTATION_REVIEW_SCHEDULE.md)
- [Master Documentation Index](../MASTER_DOCUMENTATION_INDEX.md)

---

**Last Updated**: 2025-01-27