Local File Checking with --root-dir

What Does --root-dir Do?

The --root-dir parameter tells lychee where to look for files that start with /. Let’s see an example:

index.html

<!-- index.html -->
<a href="/about.html">About</a>
<a href="/docs/guide.html">Guide</a>

These links start with /, meaning they’re absolute paths.

If the site is built in a public directory, the files will be in public/about.html and public/docs/guide.html. To check these links, you’d run:

lychee --root-dir ./public "**/*.html"

lychee will look for:

• ./public/about.html
• ./public/docs/guide.html

When Do You Need --root-dir?

You need --root-dir when:

1. Your HTML contains links starting with /
2. You want to check these links against files on your computer

Common scenarios:

• Static site builds in a public or dist directory
• Documentation sites with absolute links
• Any project where links start with /

Note

--root-dir can be an absolute or a relative path. Relative paths are taken relative to the current working directory.

Examples

Static Site Builder

If you use Hugo, Jekyll, or similar tools, they often generate sites in a public directory:

my-site/
├── public/           # Generated files live here
│   ├── about.html
│   └── docs/
│       └── guide.html
└── content/          # Source files
    └── index.md

To check the links:

lychee --root-dir public "public/**/*.html"

For GitHub Actions, the working directory can be accessed with ${{ github.workspace }}.

Documentation Site

Many documentation sites use absolute paths for links:

docs/index.html

<!-- docs/index.html -->
<a href="/api/v1.html">API</a>
<a href="/guide/start.html">Get Started</a>

To check these links:

# Assuming you're in the project root
lychee --root-dir . "docs/**/*.html"

The Difference Between --root-dir and --base-url

These parameters serve different purposes:

• --root-dir is for finding files on your computer

  • Only affects links that start with /
  • Must be a filesystem path
  • Used when checking local files

• --base-url is for resolving URLs

  • Must be a URL (like https://example.com/docs/)
  • Used when checking how links will work once deployed
  • Affects all relative links (like ./guide.html)

Troubleshooting

If your links aren’t being found:

1. Check that the files exist in the location you expect:

   # Example debugging steps
   ls -la ./public/about.html
   ls -la ./public/docs/guide.html

2. Use --verbose to see how lychee is resolving paths:

   lychee --root-dir "$(pwd)/public" --verbose "**/*.html"