DC005: BrokenLinksCheck

Overview

Property	Value
ID	DC005
Name	BrokenLinksCheck
Group	documentation
Severity	WARNING

Description

Verifies that URLs in documentation files are reachable.

Broken links in documentation frustrate users and damage trust in your project. This check scans README and docs for URLs and verifies they return successful HTTP responses.

What it checks

The check scans markdown files in:

README.md in the project root
All .md files in the docs/ directory

For each URL found, it makes an HTTP HEAD request (falling back to GET if needed) to verify the link is reachable:

PASSED: All URLs return successful responses (2xx or 3xx)
FAILED: One or more URLs are broken (4xx, 5xx, timeout, or connection error)
NOT_APPLICABLE: No markdown files found, or no URLs found in documentation

How to fix

Fix or update broken URLs

<!-- Before - broken link -->
See the [old documentation](https://example.com/old-docs) for details.

<!-- After - updated link -->
See the [new documentation](https://example.com/docs/v2) for details.

Remove outdated links

<!-- Before - link to deprecated service -->
Use our [old API](https://api.old.example.com) for integration.

<!-- After - removed outdated reference -->
Use our [current API](https://api.example.com/v2) for integration.

Fix typos in URLs

<!-- Before - typo -->
Visit [GitHub](https://githbu.com/example/repo).

<!-- After - corrected -->
Visit [GitHub](https://github.com/example/repo).

Use relative links for internal docs

<!-- Before - absolute link that may break -->
See [installation](https://myproject.readthedocs.io/en/latest/installation.html).

<!-- After - relative link -->
See [installation](installation.md) for setup instructions.

Configuration

Skip specific domains

Skip checking URLs from domains that may rate-limit or require authentication:

[tool.pycmdcheck.checks.DC005]
skip_domains = [
    "internal.company.com",
    "localhost",
    "example.com",
]

Adjust timeout

[tool.pycmdcheck.checks.DC005]
timeout = 15.0  # Seconds

Limit number of URLs checked

For large documentation sites:

[tool.pycmdcheck.checks.DC005]
max_urls = 100  # Check at most 100 URLs

Skip this check

[tool.pycmdcheck]
skip = ["DC005"]

CLI

pycmdcheck --skip DC005

Default skipped domains

The following patterns are skipped by default to avoid rate limiting and false positives:

localhost and 127.0.0.1
example.com (placeholder domain)
GitHub actions/issues/pulls URLs (rate limited)

Caching

URL check results are cached within a single pycmdcheck run to avoid redundant requests. If the same URL appears in multiple files, it will only be checked once.

Rate limiting considerations

This check respects servers by:

Using HEAD requests first (less data transfer)
Falling back to GET only if HEAD returns 405
Including a user-agent string identifying the request source
Respecting the max_urls limit