Skip to main content

Home

The linkrot Quarto extension that automatically checks for broken external links in your documents during rendering.

Installation

To install the linkrot Quarto extension, follow these steps:

  1. Open your terminal.
  2. Execute the following command:
quarto add coatless-quarto/linkrot

This command will download and install the Quarto extension under the _extensions subdirectory of your Quarto project. If you are using version control, ensure that you include this directory in your repository.

Requirements

  • Quarto >= 1.7.0
  • curl command-line tool:
    • Linux/macOS: Usually pre-installed
    • Windows: Built-in on Windows 10 (1803+) and Windows 11
    • Older Windows: Install curl for Windows or use Git Bash which includes curl

Usage

Add the extension to your document’s YAML header:

---
title: "My Document"
filters:
  - linkrot
---

The extension will automatically check all external HTTP/HTTPS links during rendering and report any broken links.

Configuration

You can configure linkrot’s behavior in your document’s YAML using the extensions.linkrot key:

---
title: "My Document"
filters:
  - linkrot
extensions:
  linkrot:
    fail-on-error: false      # Set to true to fail the build if broken links are found
    timeout: 10               # Timeout in seconds for each URL check
    user-agent: "Quarto-Linkrot/1.0"  # User agent string for requests
    cache-results: true       # Cache results to avoid checking the same URL multiple times
    debug: false              # Enable debug logging
    output-file: "linkrot-report.txt" # Write results to a file
    skip-patterns:            # List of regex patterns to skip
      - "example\\.com"
      - "localhost"
---

Configuration Options

fail-on-error** (default: false)

  • If set to true, the build will fail if any broken links are detected. Useful for CI/CD pipelines.

timeout (default: 10)

  • Maximum time in seconds to wait for each URL to respond.

user-agent (default: "Quarto-Linkrot/1.0")

  • User agent string sent with HTTP requests.

cache-results (default: true)

  • Cache URL check results to avoid repeatedly checking the same URL in a document.

debug (default: false)

  • Enable debug logging to see detailed information about what linkrot is doing.

output-file (default: null)

  • Path to a file where results will be written. If not specified, results are only shown in the console.

skip-patterns

  • List of regex patterns. URLs matching any pattern will be skipped (not checked).

Example Output

When the extension runs, you’ll see output like this in the console:

=== Linkrot Results ===
Total external links checked: 15
Broken links found: 2

Broken links:
  1. [Example Link] https://example.com/broken-page (Status: 404)
  2. [Another Link] https://nonexistent-site-xyz123.com (Status: timeout/error)

You can also specify an output file to save the results.