Help us improve
Share bugs, ideas, or general feedback.
From lychee
This skill should be used when the user asks to "create lychee.toml", "configure lychee", "set up lychee config", "customize link checking", "exclude URLs from lychee", or needs to configure lychee link checking behavior.
npx claudepluginhub tarqd/skills --plugin lycheeHow this skill is triggered — by the user, by Claude, or both
Slash command
/lychee:configuring-lycheeThe summary Claude sees in its skill listing — used to decide when to auto-load this skill
Configure lychee behavior using `lychee.toml` files. Configuration files provide persistent settings for link checking, avoiding repetitive CLI flags and ensuring consistent checks across team members.
Mandates invoking relevant skills via tools before any response in coding sessions. Covers access, priorities, and adaptations for Claude Code, Copilot CLI, Gemini CLI.
Share bugs, ideas, or general feedback.
Configure lychee behavior using lychee.toml files. Configuration files provide persistent settings for link checking, avoiding repetitive CLI flags and ensuring consistent checks across team members.
Lychee automatically searches for lychee.toml in:
Custom location:
lychee --config path/to/custom.toml docs/
# lychee.toml
# Cache settings
cache = true
max_cache_age = "1d"
# Request behavior
timeout = 30
max_retries = 3
max_concurrency = 128
# Status code handling
accept = [200, 201, 202, 203, 204, 429]
# URL patterns
exclude = [
"https://example.com",
"localhost",
"127\\.0\\.0\\.1"
]
# Enable cache
cache = true
# Cache age (e.g., "1d", "2h", "30m")
max_cache_age = "1d"
# Exclude status codes from cache
cache_exclude_status = [429, 500]
# Timeout in seconds
timeout = 30
# Maximum redirects to follow
max_redirects = 5
# Retry configuration
max_retries = 3
retry_wait_time = 2
# Concurrency
max_concurrency = 128
# Accept specific codes
accept = [200, 201, 202, 203, 204, 429]
# Or use ranges (in CLI only, not TOML)
# --accept '200..=299,429'
Note: TOML format requires array notation, not ranges.
# Exclude URL patterns (regex)
exclude = [
"https://example\\.com/.*",
"localhost",
"127\\.0\\.0\\.1",
"^https://github\\.com/.*/edit/.*",
".*\\.example\\.org"
]
# Exclude file paths (regex)
exclude_path = [
"node_modules/.*",
"target/.*",
"\\.git/.*"
]
# Check only matching patterns
include = [
"^https://mysite\\.com/.*"
]
Note: Include patterns override excludes.
# Check only specific schemes
scheme = ["https"]
# Require HTTPS when available
require_https = true
# Custom user agent
user_agent = "Mozilla/5.0 (compatible; MyBot/1.0)"
# Custom headers for requests
headers = [
"Accept: text/html",
"Authorization: Bearer token123"
]
# Remap production URLs to local paths
[[remap]]
pattern = "https://example.com"
replacement = "file:///path/to/project/build"
Use case: Check locally built sites that reference production URLs.
# Resolve relative links as if hosted at base URL
base_url = "https://example.com/docs/"
# Resolve absolute links in local files
root_dir = "/path/to/build"
# Include verbatim sections
include_verbatim = true
# Include fragments (#anchors)
include_fragments = true
# Include email addresses
include_mail = true
# Skip hidden files
hidden = false
# GitHub API token (or use environment variable)
# github_token = "ghp_..." # Better: use GITHUB_TOKEN env var
Recommendation: Using environment variable GITHUB_TOKEN is preferred over hardcoding tokens.
# lychee.toml - Documentation project
cache = true
max_cache_age = "7d"
timeout = 30
max_retries = 3
max_concurrency = 100
accept = [200, 201, 202, 203, 204, 429]
exclude = [
"localhost",
"127\\.0\\.0\\.1",
"https://example\\.com", # Placeholder URLs
"https://.*\\.example\\.org"
]
exclude_path = [
"node_modules/.*",
"dist/.*",
"\\.git/.*"
]
include_verbatim = false
See examples/docs-site.toml for complete example.
# lychee.toml - mdBook configuration
cache = true
max_cache_age = "1d"
timeout = 20
max_retries = 5
accept = [200, 201, 202, 203, 204, 429]
# Common mdBook build artifacts to exclude
exclude_path = [
"book/.*",
"node_modules/.*"
]
exclude = [
"localhost",
"127\\.0\\.0\\.1"
]
# Check source files, not generated HTML
# Run: lychee --config lychee.toml src/
See examples/mdbook.toml for complete example.
# lychee.toml - GitHub repository
cache = true
max_cache_age = "1d"
timeout = 30
accept = [200, 201, 202, 203, 204, 429]
exclude = [
# Exclude edit URLs (requires auth)
"^https://github\\.com/.*/edit/.*",
# Exclude local development
"localhost",
"127\\.0\\.0\\.1",
# Placeholder domains
"example\\.com"
]
exclude_path = [
"node_modules/.*",
"target/.*",
"vendor/.*",
"\\.git/.*"
]
See examples/github-repo.toml for complete example.
# lychee.toml - Strict checking for production
cache = false # Always check fresh
timeout = 60
max_retries = 5
# Only accept success codes
accept = [200, 201, 202, 203, 204]
# Require HTTPS
require_https = true
scheme = ["https"]
# Check everything
include_verbatim = true
include_fragments = true
include_mail = true
exclude = [] # Check all links
See examples/strict.toml for complete example.
Remap allows checking locally built sites with production URLs:
[[remap]]
pattern = "https://example.com"
replacement = "file:///path/to/project/build"
[[remap]]
pattern = "https://cdn.example.com"
replacement = "file:///path/to/project/assets"
Multiple remaps: Use multiple [[remap]] sections.
Workflow:
--root-dir pointing to build directoryExample from field-guide project:
lychee --config lychee.toml \
--root-dir "$(pwd)/book/html/" \
--remap "https://example.com file://$(pwd)/book/html" \
book/html
Test configuration before committing:
# Dry run to see what would be checked
lychee --dump README.md
# See all inputs that would be processed
lychee --dump-inputs '**/*.md'
# Verbose output to verify settings
lychee --verbose README.md
Settings priority (highest to lowest):
lychee.toml configuration fileExample: If lychee.toml sets timeout = 30 but CLI uses --timeout 60, the CLI value (60) takes precedence.
Complete configuration examples in examples/:
examples/docs-site.toml - Documentation project configurationexamples/mdbook.toml - mdBook-specific configurationexamples/github-repo.toml - GitHub repository configurationexamples/strict.toml - Strict production checking--dump before running full checksAdd comments for temporary exclusions:
exclude = [
# TODO: Fix broken links (Issue #123)
"https://oldsite\\.example\\.com/.*",
# Temporarily down (2024-01-15)
"https://partner-api\\.example\\.org"
]
Use different configs for different environments:
# Local development (lenient)
lychee --config lychee.dev.toml docs/
# CI/Production (strict)
lychee --config lychee.prod.toml docs/
Start lenient, gradually tighten:
# Phase 1: Basic checking
accept = [200, 201, 202, 203, 204, 429, 500, 502, 503]
exclude = ["lots", "of", "patterns"]
# Phase 2: After fixing obvious issues
accept = [200, 201, 202, 203, 204, 429]
exclude = ["fewer", "patterns"]
# Phase 3: Strict (production ready)
accept = [200, 201, 202, 203, 204]
exclude = []
lychee.toml in project rootlychee-github-workflows skill)