Automatically Check Obsidian for Broken Links with lychee

Description and use

Automatically check Obsidian vault links with lychee using relative Markdown links, pre‑commit hooks, and GitHub Actions.

Problem

Renaming or deleting notes in Obsidian can leave broken links that are hard to detect manually.

Outcome

The vault is automatically scanned for broken links, with failures reported in the terminal, pre‑commit aborts commits, and CI prevents PR merges until links are fixed.

Workflow

• Configure Obsidian to use relative Markdown links
• Install lychee via Homebrew or curl
• Create a .lycheeignore or lychee.toml to exclude non‑vault files
• Run lychee --offline vault/ to scan locally
• Set up a pre‑commit hook with pre‑commit to run lychee on every commit
• Add a GitHub Actions workflow to run lychee in CI

Evidence

When you manage notes in Obsidian, renaming or deleting notes can leave broken links behind.

Source

Obsidian's default wiki-link format [[note]] is not supported. To check links with lychee, you need to use standard Markdown link syntax.

Source

lychee --offline vault/

Source

Now the link check runs automatically on every commit, and the commit will be aborted if any broken links are found.

Source

Running the link check in CI catches problems before a PR is merged.

Source