Skip to content

root-dir: allow root-dir that doesn't exist#2127

Open
katrinafyi wants to merge 2 commits intolycheeverse:masterfrom
rina-forks:root-dir-nocheck
Open

root-dir: allow root-dir that doesn't exist#2127
katrinafyi wants to merge 2 commits intolycheeverse:masterfrom
rina-forks:root-dir-nocheck

Conversation

@katrinafyi
Copy link
Copy Markdown
Member

the existence check wasn't super helpful, i think. with an invalid root-dir, links will now fail in the link checking phase, but i think it is fairly obvious and not confusing.

removing the check makes some use-cases easier. for example, you can intentionally use a non-existing root-dir to validate that no root-relative links are used. also makes it easier for the use-case of #2125 .

maybe we could print a warning if the root-dir is found to be invalid? but i think it's okay without.

as an alternative to this pr, we could only validate relative root-dirs and allow non-existing absolute root-dirs. but i worried that would be confusing and inconsistent.

the existence check wasn't super helpful, i think. with an invalid
root-dir, links will now fail in the link checking phase, but i think it
is fairly obvious and not confusing.

removing the check makes some use-cases easier. for example, you can
intentionally use a non-existing root-dir to validate that *no*
root-relative links are used.

maybe we could print a warning if the root-dir is found to be invalid?
but i think it's okay without.
@mre
Copy link
Copy Markdown
Member

mre commented Apr 4, 2026

To be honest, I liked that we validate the root-directory. After all, isn't that the only place where we have a chance to detect typos and invalid paths? Without that, I'm afraid that the number of misconfigurations could go up, which can be frustrating to users.

Can you think of use-cases other than #2125, where this can be useful? 🤔 I think it's a clever workaround to specify a non-existent root-dir to exclude root-relative links, but it sounds a bit hacky. The alternative suggested was to add a flag like --ignore-unresolvable, which sounds promising.

Printing a warning for invalid root-dirs sounds like a good middle-ground, but it could go unnoticed.

@katrinafyi
Copy link
Copy Markdown
Member Author

I think that the UX impact of this change is not too big. The link checking error displays the URL with root-dir at the beginning, so users will naturally investigate that URL and see that root-dir is being applied. Having the source line:col also makes this easier, as users can go to that file location and see the root-relative link.

$ cargo run rel.md --root-dir /tmp/nowhere
[rel.md]:
 [ERROR] file:///tmp/nowhere/root (at 1:1) | File not found. Check if file exists and path is correct

To exclude root-relative links, I think --root-dir + --exclude is not at a hack at all. To me, it seems like a very natural way to do this: you use --root-dir to specify where root-relative links will go, and you combine this with --exclude to exclude links matching a certain pattern.

I wouldn't like --ignore-unresolvable because what does "unreasolvable" mean? As a solution to #2125, it is also suboptimal because it could ignore more links than just root-relative links.

@mre
Copy link
Copy Markdown
Member

mre commented Apr 4, 2026

All good points, thanks. Let's go ahead with it then.

@mre
Copy link
Copy Markdown
Member

mre commented Apr 13, 2026

Feel free to merge when ready. 😊

Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Labels

None yet

Projects

None yet

Development

Successfully merging this pull request may close these issues.

2 participants