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 --><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 "$(pwd)/public" "**/*.html"
lychee will look for:
./public/about.html
./public/docs/guide.html
When Do You Need —root-dir?
You need --root-dir
when:
- Your HTML contains links starting with
/
- You want to check these links against files on your computer
Common scenarios:
- Static site builds in a
public
ordist
directory - Documentation sites with absolute links
- Any project where links start with
/
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:
# Convert relative path to absolute firstlychee --root-dir "$(pwd)/public" "public/**/*.html"
Documentation Site
Many documentation sites use absolute paths for links:
<!-- 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 rootlychee --root-dir "$(pwd)" "docs/**/*.html"
The Difference Between —root-dir and —base
These parameters serve different purposes:
-
--root-dir
is for finding files on your computer- Only affects links that start with
/
- Must be an absolute filesystem path
- Used when checking local files
- Only affects links that start with
-
--base
is for resolving URLs- Must be a URL (like
https://example.com/docs/
) - Used when checking how links will work once deployed
- Affects relative links (like
./guide.html
)
- Must be a URL (like
Using Both Together
Sometimes you need both:
lychee \ --root-dir "$(pwd)/public" \ --base https://example.com/ \ "public/**/*.html"
This tells lychee:
- Look for
/
-prefixed files in./public/
- Resolve relative links against
https://example.com/
Troubleshooting
If your links aren’t being found:
- Make sure you’re using an absolute path:
# Get absolute path in bashfull_path="$(pwd)/public"lychee --root-dir "$full_path" "**/*.html"
- Check that the files exist in the location you expect:
# Example debugging stepsls -la ./public/about.htmlls -la ./public/docs/guide.html
- Use
--verbose
to see how lychee is resolving paths:
lychee --root-dir "$(pwd)/public" --verbose "**/*.html"