False positive `relative_to_docs` absolute path validation warning about mkdocs

[oprypin]

It is expected that a link ending with / or .html will always be wrong (unless you've actually put a .html document into docs). Links need to be always to .md files that exist in docs dir.

See previously https://github.com/mkdocs/mkdocs/releases/tag/1.5.0#expanded-validation-of-links "Validated links in Markdown" - and the same applies to the newly enabled absolute links

[Blacksmoke16]

Okay, but it seems no matter what I use, it produces the same warning. I can see the file in site/Framework/Events/Request/index.html. So that should map to /Framework/Events/Request/index.md; but seems only URL that actually works is /Framework/Events/Request with or without a trailing /.

NOTE: I changed something in the sub-project to make the url have a capitalized Framework in the URL, but that didn't change anything.

EDIT: /Framework/Events/Request/index.html actually does work, but still produces the error:

WARNING -  Doc file 'architecture.md' contains a link '/Framework/Events/Request/index.html', but the target is not found
           among documentation files.

[Blacksmoke16]

@oprypin Seems this is a https://squidfunk.github.io/mkdocs-material/plugins/projects/ specific thing. Only seems to happen when pointing to a file a part of a sub-project. Imma close and open an issue over there.

[oprypin]

Just from that plugin's concept, I guess the whole point is to split up sites into sub-sites, and validation is not really possible to implement fully correctly without running some part of the build process of MkDocs (files get added dynamically) for the other sites. So the correct mode for that plugin may be absolute_links: ignore 😬

[OmarTawfik]

@oprypin I'm seeing the same issue, but for a different use case (without plugins):

Doc file 'user-guide/index.md' contains an unrecognized relative link './foo/', it was left as is. Did you mean './foo/index.md'?

We have use_directory_urls: true, and we want to keep using ./foo/, instead of ./foo/index.md. The links are actually compiled correctly, and the resulting site works! so I'm not sure if the warning is useful here.

Since mkdocs already works correctly with this input, I do believe it is a false positive indeed. This validation is very useful otherwise.

[pawamoy]

I believe the rationale is that it's easier for MkDocs to detect and validate links when they use /index.md. That also makes validation more robust against configuration changes, like switching from directory URLs to non-directory ones.

[OmarTawfik]

like switching from directory URLs to non-directory ones.

In that case, the warning should be conditional on that flag use_directory_urls IMO. This is a valid user scenario, and is already supported and working correctly in the compiled site. It is only validation that is incorrectly flagging the link as broken.

[pawamoy]

I think I remember there were technical reasons why it's better to use /index.md but I can't seem to find them. I think it's good that MkDocs pushes you to use the best approach for writing links, while allowing you to discard (debug) or disarm (info) the warnings with configuration options.

EDIT: ah, one of the reason might be that using /index.md plays nicer with other tools like editors which are then able to see you're linking to an existing file.