Automating Link Verification in Documentation

Broken links in documentation are more than an annoyance; they erode user trust and can send potential contributors to dead ends. A 404 error in a README or a link to a deprecated API can create friction for developers trying to adopt a project. Recognizing this, developer Hsensmira built urldn-link-check, an open-source GitHub Action and Command Line Interface (CLI) tool designed to automatically verify links within Markdown and MDX files during the Continuous Integration (CI) process.

The core idea is simple: catch these issues before they are merged into the main branch and subsequently reach production environments. This proactive approach saves development teams time and prevents user frustration by ensuring that all links in public-facing documentation are functional and secure.

urldn-link-check offers a suite of features aimed at comprehensive link auditing:

  • Broken Link Detection: Identifies standard HTTP errors like 404 (Not Found) and 500 (Internal Server Error).
  • Redirect Chain Analysis: Detects excessively long sequences of redirects, which can impact performance and indicate potential issues with link management.
  • Insecure Link Identification: Flags links using HTTP instead of HTTPS, promoting the adoption of secure communication protocols.
  • URL Length Check: Finds overly long URLs, which can sometimes cause issues with older systems or certain email clients.
  • File Support: Scans both standard Markdown (.md) and Markdown with JSX (.mdx) files.
  • Performance: Utilizes fast, concurrent scanning to minimize CI pipeline wait times.
  • Integration: Provides summaries directly within GitHub Pull Requests (PRs) for immediate feedback.
  • Reporting: Generates reports in both JSON and Markdown formats for detailed analysis and integration with other tools.

The tool's installation is straightforward, available via npm or npx:

npm install -D urldn-link-check

Or, to run directly without a global installation:

npx urldn-link-check .

For integration into a GitHub workflow, the setup is minimal. Adding the following to a workflow file enables automatic checks on every push or pull request:

# .github/workflows/link-check.yml
name: Link Check

on: [push, pull_request]

jobs:
  link-check:
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v3
      - uses: urldn/link-check@v1
        with:
          # Optional: specify the path to scan
          # path: 'docs/'
          # Optional: specify the token for private repos
          # token: ${{ secrets.GITHUB_TOKEN }}

This configuration ensures that the urldn-link-check action runs automatically, scanning the specified path (or the root directory by default) for link issues. The action leverages the GitHub Actions environment, making it a seamless addition to existing CI/CD pipelines.

GitHub Actions workflow snippet demonstrating urldn-link-check setup.

The Problem of Link Rot

Link rot, the phenomenon of hyperlinks becoming broken over time, is a pervasive issue on the internet. Studies have shown that a significant percentage of links in academic papers and web pages become inactive within a decade. For software projects, this problem is amplified. Documentation is the primary gateway for new users and contributors. When links within README files, contribution guides, or API references fail, it creates a poor first impression and can actively prevent engagement.

Consider a scenario where a project links to an external library or an example repository. If that link breaks, a developer trying to follow the instructions might be unable to reproduce the example or integrate the necessary dependency. This is akin to a cookbook having a page with a missing ingredient list or a recipe that calls for a nonexistent utensil. The entire process grinds to a halt.

urldn-link-check directly addresses this by acting as an automated proofreader for hyperlinks. It doesn't just check for 404s; it also flags redirect chains. While redirects are a legitimate tool for managing URL changes, excessively long chains can be a symptom of poor URL management or can lead to significant delays in loading resources. The tool's ability to detect these chains helps maintain not only correctness but also performance.

Furthermore, the check for insecure HTTP links is crucial in today's security-conscious environment. Many services now require or strongly prefer HTTPS. A project that inadvertently links to an HTTP resource might be directing users to a less secure connection, potentially exposing data or leading to warnings from browsers. By flagging these, urldn-link-check encourages the use of secure, modern web standards.

Beyond Basic Checks: What urldn-link-check Offers

The inclusion of an