DEV Community

kohei_wada
kohei_wada

Posted on Originally published at wada-dev.com

Automatically Check Obsidian for Broken Links with lychee

#automation #cli #markdown #tools

When you manage notes in Obsidian, renaming or deleting notes can leave broken links behind. In this post, I'll show you how to detect them automatically using lychee, a fast link checker written in Rust.

What is lychee?

lychee is a fast link checker written in Rust.

Highlights:

  • Fast checks thanks to async processing
  • Native support for Markdown files
  • The --offline option lets you check only local links
  • Easy to plug into GitHub Actions

Prerequisite: Obsidian link formats

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

If you set Obsidian's "New link format" option to "Relative path", new links will be created in the standard format automatically.

Obsidian settings: change link format to relative path

Format Example lychee support
Wiki link [[note]] ❌ Not supported
Standard Markdown [note](./note.md) ✅ Supported

To convert existing wiki links, plugins like obsidian-link-converter come in handy.

Installation

macOS (Homebrew) 

brew install lychee
Enter fullscreen mode Exit fullscreen mode

Linux 

curl -sSfL https://github.com/lycheeverse/lychee/releases/latest/download/lychee-x86_64-unknown-linux-gnu.tar.gz | tar xzf - -C /usr/local/bin
Enter fullscreen mode Exit fullscreen mode

Basic usage

To check the internal links in an Obsidian vault, use the --offline option:

lychee --offline vault/
Enter fullscreen mode Exit fullscreen mode

Sample output

When broken links exist, you'll see output like this:

Terminal output showing lychee detecting broken links

When all links are healthy:

Terminal output showing lychee with no broken links

How to write standard Markdown links

Using relative paths lets lychee detect broken links accurately.

[関連ノート](../03_PermanentNotes/related-note.md)
![画像](../97_Assets/image.png)
Enter fullscreen mode Exit fullscreen mode

Tips:

  • Use relative paths (../folder/file.md)
  • Avoid URL encoding (%20, etc.)

Excluding files

In practice, there will always be files or directories you want to exclude from the check.

Excluding from the command line 

# Exclude a specific path
lychee --offline --exclude-path "vault/99_Archive" vault/

# Exclude multiple paths
lychee --offline \
  --exclude-path "vault/99_Archive" \
  --exclude-path "vault/.obsidian" \
  vault/
Enter fullscreen mode Exit fullscreen mode

Excluding via .lycheeignore

You can create a .lycheeignore file at the project root and list exclusion patterns there:

# Exclude archive
vault/99_Archive/

# Exclude templates
vault/98_Templates/

# Exclude files matching a pattern
**/draft-*.md
Enter fullscreen mode Exit fullscreen mode

Managing settings with lychee.toml

Keeping your settings in a config file is convenient:

# lychee.toml
exclude_path = [
  "vault/99_Archive",
  "vault/.obsidian"
]

# Timeout (for external URL checks)
timeout = 10

# Concurrency
max_concurrency = 32
Enter fullscreen mode Exit fullscreen mode

You can point to the config file when running the command.

lychee --offline --config lychee.toml vault/
Enter fullscreen mode Exit fullscreen mode

Auto-check with a pre-commit hook

To run a link check automatically on commit, set up pre-commit.

.pre-commit-config.YAML 

repos:
  - repo: local
    hooks:
      - id: lychee-link-checker
        name: Check links with lychee
        entry: lychee --offline --config lychee.toml vault/
        language: system
        files: '\.md'
        pass_filenames: false
Enter fullscreen mode Exit fullscreen mode

Installing and enabling pre-commit 

pip install pre-commit
pre-commit install
Enter fullscreen mode Exit fullscreen mode

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

Continuous checking with GitHub Actions

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

.GitHub/workflows/ci.yml 

name: CI

on:
  push:
    branches: [main]
  pull_request:
    branches: [main]

jobs:
  link-check:
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v4

      - name: Install lychee
        run: |
          curl -sSfL https://GitHub.com/lycheeverse/lychee/releases/latest/download/lychee-x86_64-unknown-linux-gnu.tar.gz | tar xzf - -C /usr/local/bin

      - name: Run link checker
        run: lychee --offline --config lychee.toml vault/
Enter fullscreen mode Exit fullscreen mode

Running from a Makefile

It's handy to wrap commands you use often in a Makefile:

VAULT_PATH := vault

.PHONY: check-links
check-links:  ## Check for broken links using lychee
 lychee --offline --config lychee.toml $(VAULT_PATH)/
Enter fullscreen mode Exit fullscreen mode 
make check-links
Enter fullscreen mode Exit fullscreen mode

Wrapping up

With lychee, you can check an Obsidian vault for broken links quickly and automatically.

Scenario Command
Manual local check lychee --offline vault/
At commit time Automatic check via a pre-commit hook
CI Continuous checks via GitHub Actions

One thing to keep in mind: lychee only supports standard Markdown links. If you're using wiki links [[note]], you'll need to convert them to the standard format first.

Keep your knowledge base healthy and free of broken links.

References

This post was written with AI assistance and reviewed by the author.

Top comments (0)