Skip to content

Instantly share code, notes, and snippets.

@katrinafyi
Last active January 1, 2026 05:26
Show Gist options
  • Select an option

  • Save katrinafyi/60eadd4211943f62451c064fdbd52044 to your computer and use it in GitHub Desktop.

Select an option

Save katrinafyi/60eadd4211943f62451c064fdbd52044 to your computer and use it in GitHub Desktop.
RFC: local-to-remote mapping with --base-url + --root-dir

Background:

  • Using --base-url and --root-dir together is surprising. The root-dir (which is a filesystem path) gets prefixed onto the base URL (which is a URL). This happens to build a valid URL on Unix, but it will almost always be a broken link. On Windows, it will put C:\ inside the URL which is surely wrong. Discussed in lycheeverse/lychee#1912 (comment)
  • Using --base-url with local files can be surprising, because the local folder structure is not considered when making the URLs - the local folder path is dropped entirely. lycheeverse/lychee#1296 was a similar issue (now fixed) for remote URLs. This problem is similar but for local URLs instead.
  • Using --root-dir surprisingly (and negatively) affects / links in remote HTML files lycheeverse/lychee#1964

Proposal:

Questions:

  • How to communicate this change to users? Should the current behaviour be kept accessible?
    • Maybe if --base-url is used without --root-dir, it can keep its old behaviour?
    • I don't think that keeping the old --root-dir + --base-url behaviour is worthwhile.

See:

idk what you want.
started with opposition because of hypothetical burden
ou suggest local-to-remote by default with possible flag?
but do you really want this?
repeatedly said that you don't use the feature and can't imagine a use case for it.
I want to discuss the merits of keeping "local-to-remote".
if you care about burden, burden is significantly higher if nobody knows the use case.
nobody knows how it "should" work and nobody is actively using it to make sure it keeps working.
I don't believe that appealing to the original intent is a worthwhile thing to do.
atm, the options have diverged so much from the original intent, and for so long,
that no user is using them the way they're origin ally intended.
so there's an opportunity to make a change, and change in both directions would be equally disruptive
basically, I want to ask: what do you _want_?
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment