Update --base-url recipe docs, and add warning box

[katrinafyi]

The goal is to add more detail where I can, and to remove information which I think is no longer correct. I think this page was originally written when --base-url behaved quite differently (before --root-dir?).

I've left all of the examples even though I think they will not work. The examples are all very brief so I don't know what they're intended to show. I've left them to be safe.

The statements which I've removed or changed because I think they're no longer correct are:

Even though your site isn't deployed yet, lychee can verify that the
files your links point to exist in your project.

The --base-url parameter works similarly to other tools you might know:

--base-url: Use it when you care about your site's final URL structure

Also don't recommend using both --root-dir and --base-url.

[mre]

The "other" suggests that we check a file in the first place. It could be an online URL, though, so it's slightly confusing.

Suggested change

	- Your relative links should resolve to other local files based on their folder structure.
	- Your relative links should resolve to local files based on your folder structure.

[mre]

That bit about resolving absolute links is also a bit confusing.
I think we need to be super clear with our wording here as I already caused too much trouble by being imprecise in the past. 😉

Unfortunately, I don't know how to phrase it better.

Suggested change

	[--root-dir](/recipes/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.
	[--root-dir](/recipes/root-dir/) may be useful instead. If you set a root
	directory, absolute links will be resolved (what should we put here?), and relative links will be
	resolved based on a local file's path relative to the root directory.

[mre]

What do you think about reordering this a bit?

Suggested change

	:::caution[Important]
	lychee's `--base-url` option applies the same base URL to _all_ local files.
	This can cause problems when local files have relative links to other local files based
	on their filesystem structure, as `--base-url` does not consider the folder structure.
	:::
	:::caution[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, as `--base-url` applies the same base URL to _all_ local files.
	:::

But as a user I would ask: "What's the problem with that? What are the edge-cases that arise by applying the same base-url to all local files? Isn't that the expected behavior?"

Maybe that helps find a better way to phrase this part.

[katrinafyi]

do you think " --base-url causes lychee to assume that all local files have the same base URL. This can cause problems when resolving relative links that expect a certain folder structure." would be enough? does the first paragraph teach the reader enough about base url to know why this is bad?

[mre]

I don't know yet, but it's better. Maybe we could also mention that this behavior can be counterintuitive. And maybe we could also add an example for the folder structure and how this could cause problems to really bring the point home, although I could understand if that's outside the scope of this PR.

[mre]

Suggested change

	- Applies to links with absolute paths (links beginning with `/`) in local files.
	- Only applies to links with absolute paths (e.g. links beginning with `/` on Unix or `C:\` on Windows) in local files.

[katrinafyi]

this is using the URL notion of absolute links, so it's those beginning with /. I should avoid the word "path" to avoid confusion.

[mre]

Since this can be a bit counterintuitive ("why doesn't it just check /foo and instead prefixes it with a 'root directory'?"), maybe we should add an example here.

Suggested change

	- Resolves absolute links to files within the given root directory.
	- Resolves absolute links to files within the given root directory.
	For example, if lychee finds a link to `/contact` in your input and the root directory is set to `/usr/lychee/site`, then it will check `/usr/lychee/site/contact`.

[mre]

Apart from some minor changes (see the comments), I don't see any blockers for merging this. But I'd be fine to merge it as-is as well. @katrinafyi, let me know your preference. 😉

[katrinafyi]

I did mean to address the comments and I'd still like to.

It's just been low priority because it's documenting something which i think is a bit broken.

[mre]

Ah yeah, all good. And yes, it's quite broken indeed. 😅 Somehow I wish I never introduced root-dir and base-url at all, or at least did so after doing a lot more research. Too late now, but here's hoping that we can fix some of the more gnarly edge cases in the future.