GreatDocs.check_links()

Check all links in source code and documentation for broken links.

Usage

Source

GreatDocs.check_links(
    include_source=True,
    include_docs=True,
    timeout=10.0,
    ignore_patterns=None,
    verbose=False
)

Note

In practice, you would normally use the great-docs check-links CLI command rather than calling this method directly. See the CLI reference for details.

This method scans Python source files and documentation files (.qmd, .md) for URLs and checks their HTTP status. It reports broken links (404s) and warns about redirects.

The following content is automatically excluded from link checking:

• Python comments: URLs in lines starting with #
• Code blocks: URLs inside fenced code blocks (...)
• Inline code: URLs inside backticks (`...`)
• Marked URLs: URLs followed by {.gd-no-link} in .qmd/.md files

For documentation, the checker scans the source user_guide/ directory rather than the generated docs/ directory to avoid checking transient files.

In .qmd files, you can exclude specific URLs from checking by adding {.gd-no-link} immediately after the URL:

Visit http://example.com{.gd-no-link} for an example.
Also works with inline code: `http://example.com`{.gd-no-link}

Parameters

include_source: bool = True

If True, scan Python source files in the package directory for URLs. Default is True.

include_docs: bool = True

If True, scan documentation files (.qmd, .md) for URLs. Default is True.

timeout: float = 10.0

Timeout in seconds for each HTTP request. Default is 10.0.

ignore_patterns: list[str] | None = None

List of URL patterns (strings or regex) to ignore. URLs matching any pattern will be skipped. Default is None.

verbose: bool = False

If True, print detailed progress information. Default is False.

Returns

dict

A dictionary containing:

• total: total number of unique links checked
• ok: list of links that returned 2xx status
• redirects: list of dicts with url, status, location for 3xx responses
• broken: list of dicts with url, status, error for 4xx/5xx or errors
• skipped: list of URLs that were skipped (matched ignore patterns)
• by_file: dict mapping file paths to lists of links found in each file

Examples

Check all links in a project:

from great_docs import GreatDocs

docs = GreatDocs()
results = docs.check_links()

print(f"Checked {results['total']} links")
print(f"Broken: {len(results['broken'])}")
print(f"Redirects: {len(results['redirects'])}")

Check only documentation files with custom timeout:

results = docs.check_links(
    include_source=False,
    timeout=5.0,
    ignore_patterns=["localhost", "127.0.0.1", "example.com"]
)