Applying a Base URL with --base-url

What Is the Base URL?

In HTML, a base URL is used when resolving relative links; relative links will be resolved relative to the base URL. For example, a link to page.html with a base URL of https://example.com/help/ would resolve to https://example.com/help/page.html.

For most published sites, the base URL of a page is just the normal URL of the page. The <base> HTML element can be used to override the base URL for a particular HTML page, but this is rare.

Do You Need To Set a Base URL?

Most of the time, you don’t!

Skip --base-url if:

• You’re only checking fully-qualified URLs.
• Your site runs at a root domain like example.com.
• Your relative links in local files should resolve to other local files based on their folder structure.

If your use case falls into the second or third case, --root-dir may be useful instead. Setting a root directory can help to resolve absolute links, and relative links will be resolved based on a local file’s path.

An Example

Let’s look at an example:

docs/guide.html

<a href="./getting-started.html">Get Started</a>
<a href="../about.html">About Us</a>

Say this page will be deployed to example.com/docs/guide.html. Those relative links should resolve to:

• example.com/docs/getting-started.html
• example.com/about.html

To check if these links are valid, tell lychee where the site will be hosted:

lychee --base-url https://example.com/docs/ "**/*.html"

Important

lychee’s --base-url does not consider the folder structure. This can cause problems when local files have relative links to other local files based on their filesystem structure. --base-url applies the same base URL to all local files and may break these links.

How Does It Work?

When you set --base-url, lychee will:

1. Find all links in your HTML files.
2. Convert relative links to full URLs using the given base URL.
3. Check if the full URLs are valid and reachable.

Here’s what happens to different types of links:

Link Resolution Example

<!-- Original links -->
<a href="./guide.php">Guide</a>
<a href="../about.php">About</a>
<a href="https://example.com">Absolute</a>

<!-- After --base-url https://example.com/docs/ -->

<a href="https://example.com/docs/guide.php">Guide</a>
<a href="https://example.com/about.php">About</a>
<a href="https://example.com">Absolute</a>

Common Use Cases

Documentation Sites

Running your docs locally? Tell lychee to check against your dev server:

lychee --base-url http://localhost:3000/docs/ "docs/**/*.html"

Want to verify links before deploying? lychee can check if files exist in your project:

lychee --base-url https://example.com/docs/ "docs/**/*.html"

GitHub Pages

If your site will be on GitHub Pages:

# For a project site
lychee --base-url https://username.github.io/project/ "**/*.html"

# For local development
lychee --base-url http://localhost:4000/project/ "**/*.html"

Blogging Platforms

Using WordPress, Ghost, or Jekyll with a blog at example.com/blog/? Here’s how to check those links:

lychee --base-url https://example.com/blog/ "content/**/*.html"

Local Development

You can use file:// URLs to check files without running a server:

lychee --base-url file:///absolute/path/to/site/ "**/*.html"

This is helpful when you want to verify links exist on your filesystem.

Important Details

Let me explain the technical necessity of the trailing slash:

Add A Trailing Slash If It’s A Directory

When in doubt about whether to include the trailing slash, include it. It’s almost always what you want when working with static sites and documentation.

Trailing Slash Example

# ✅ Good - links will resolve correctly
lychee --base-url https://example.com/docs/
# ❌ Bad - links will break
lychee --base-url https://example.com/docs

The trailing slash is crucial because it tells lychee whether /docs is a file or a directory. This follows standard URL resolution rules:

• https://example.com/docs/ (with slash) means “docs” is a directory

  • ./guide.html resolves to /docs/guide.html
  • ../about.html resolves to /about.html

• https://example.com/docs (no slash) means “docs” could be a file

  • ./guide.html resolves to /guide.html (goes up one level!)
  • ../about.html resolves to /about.html

lychee can’t automatically add the slash because both forms are valid - they just mean different things. For example, https://example.com/docs might be a single page, while https://example.com/docs/ is its directory version. This distinction is part of how URLs work on the web.

--base-url vs --root-dir

These solve different problems, and using both together is generally not recommended.

• --base-url requires a URL (like https://example.com/docs/), and it:

  • Applies to all relative links in local files.
  • Resolves all relative links relative to the given base URL.

• --root-dir requires a local folder path (like ./public/), and it:

  • Only applies to absolute links (links beginning with /) in local files.
  • Resolves absolute links to files within the given root directory.

Troubleshooting

If links aren’t being checked correctly:

1. Verify your base URL has a trailing slash
2. For local development, ensure your server is running
3. Use --verbose to see how lychee resolves links