This week's tip of the week is Lychee
You know what’s fun? Clicking a link in a README or documentation and landing on a 404. Actually, no. It’s not fun. It makes your docs feel stale, your project feel abandoned.
Lychee is a fast link checker written in Rust that can scan Markdown, HTML, reStructuredText, websites, and more. It finds broken links and email addresses before someone opens an issue with “hey, this link is dead.”
Install on macOS with Homebrew:
brew install lycheeon Windows:
winget install --id lycheeverse.lycheeon Linux:
snap install lycheeand for other Linux and other install options, see their installation docs.
Once installed, run it against a project:
lychee .Or check specific files:
lychee README.md docs/**/*.mdOr check a website. Here it is in action on my own site:
❯ lychee https://nickyt.co
32/32 ━━━━━━━━━━━━━━━━━━━━ Finished extracting links 🔍 32 Total (in 4s 646ms) 🔗 28 Unique ✅ 32 OK 🚫 0 Errors 🔀 27 Redirects
Hint: Followed 27 redirects. You might want to consider replacing redirecting URLs with the resolved URLs. Use verbose mode (`-v`/`-vv`) to see redirection details.That’s already useful locally, but the real win is putting it in continuous integration (CI) so broken links fail before they ship. Check out the official GitHub Action.
Here’s a tiny GitHub Actions example:
name: Links
on:
repository_dispatch:
workflow_dispatch:
schedule:
- cron: "00 18 * * *"
jobs:
linkChecker:
runs-on: ubuntu-latest
permissions:
issues: write # required for peter-evans/create-issue-from-file
steps:
- uses: actions/checkout@v5
- name: Link Checker
id: lychee
uses: lycheeverse/lychee-action@v2
with:
fail: false
- name: Create Issue From File
if: steps.lychee.outputs.exit_code != 0
uses: peter-evans/create-issue-from-file@v5
with:
title: Link Checker Report
content-filepath: ./lychee/out.md
labels: report, automated issueYou can also add a .lycheeignore file for links you know are weird, temporary, private, or blocked by some site that hates bots. The internet is held together with duct tape and redirects, so this matters.
I like this because it’s boring in the best way. It catches the stuff you probably won’t notice during a docs update, blog migration, repo cleanup, or release.
And honestly, I would rather have a robot tell me a link is broken than have a reader discover it first. Ready to add it? Drop it in your CI today.
That's it! Short and sweet. Until the next one!
