This handy tool helps you maintain the integrity of your Markdown files by identifying broken links. It scans your files and detects:

Here's what it does:

• Missing webpages: Links that no longer exist on the internet.
• Incorrect file links: Links that point to the wrong file in your project.
• Non-existent fragments (anchors): Links to specific sections that don't exist, e.g. README.md#no-fragment.

Example of output for fail.md

File: tests/test_md_files/fail.md:3 • Link: https://github.com/AlexanderDokuchaev/FAILED • Error: 404: Not Found
File: tests/test_md_files/fail.md:4 • Link: https://not_exist_github.githubcom/ • Error: 500: Internal Server Error
File: tests/test_md_files/fail.md:8 • Link: /test/fail.md1 • Error: Path not found
File: tests/test_md_files/fail.md:9 • Link: fail.md1 • Error: Path not found
File: tests/test_md_files/fail.md:13 • Link: /tests/test_md_files/fail.md#fail • Error: Fragment not found
File: tests/test_md_files/fail.md:15 • Link: not_exist_dir • Error: Path not found
❌ Found 6 dead links 🙀

Add Github Action config to .github/workflow/

jobs:
  md-dead-link-check:
    runs-on: ubuntu-22.04
    steps:
      - uses: actions/checkout@v4
      - uses: AlexanderDokuchaev/[email protected]

Adding to your .pre-commit-config.yaml to integrate in pre-commit tool

  - repo: https://github.com/AlexanderDokuchaev/md-dead-link-check
    rev: "v0.9"
    hooks:
      - id: md-dead-link-check

# .github/workflows/nightly.yaml
name: nightly
on:
  workflow_dispatch:
  schedule:
    - cron: '0 0 * * *'
jobs:
  md-dead-link-check:
    runs-on: ubuntu-22.04
    steps:
      - uses: actions/checkout@v4
      - uses: AlexanderDokuchaev/[email protected]

# .github/workflows/pull_request.yaml
name: pull_request
on:
  pull_request:
    types:
      - opened
      - reopened
      - synchronize
jobs:
  md-dead-link-check:
    runs-on: ubuntu-22.04
    steps:
      - uses: actions/checkout@v4
      - uses: AlexanderDokuchaev/[email protected]

For direct use, install with pip and run:

pip install md-dead-link-check
md-dead-link-check

This tool utilizes asynchronous API calls and avoids downloading full web pages, enabling it to process thousands links in several seconds.

This tool leverages your system's existing HTTP and HTTPS proxy configuration. It achieves this by trusting the environment variables that your operating system utilizes to define proxy settings. This functionality is enabled by the aiohttp.ClientSession(trust_env=True) option. For further technical details, you can refer to the aiohttp documentation.

This tool seamlessly integrates with your project's pyproject.toml file for configuration. To leverage a different file, invoke the --config option during execution.

• timeout: Specifies the maximum time (in seconds) to wait for web link responses. Default: 5 seconds.
• catch_response_codes: List of HTTP response codes to consider as failures. If empty, all codes greater than 400 will be marked as failures. Default: [404, 410, 500].
• exclude_links: List of links to exclude from checks. Default: [].
• exclude_files: List of files to exclude from checks. Default: [].
• force_get_requests_for_links: List of links for which the tool will use GET requests during checks. Default: [].
• check_web_links: Toggle web link checks on or off. Default: true.
• validate_ssl: Toggles whether to validate SSL certificates when checking web links. Default: true.

[tool.md_dead_link_check]
timeout = 5
exclude_links = ["https://github.com/", "https://github.com/*"]
exclude_files = ["tests/test_md_files/fail.md", "tests/*"]
check_web_links = true
catch_response_codes = [404, 410, 500]
force_get_requests_for_links = []
validate_ssl = true