mkdocs: Links should be file system paths rather than relative URL paths

[nullun]

Since mkdocs version 1.5.0, they have expanded their validation of links within Markdown files. This has resulted in a large number of warnings to be shown when running mkdocs. Some files such as the CLI docs are auto-generated, so the script will likely need modifying to conform to the expected format. Fortunately it still appears to build for now so the docs still appear to work as is, but it's worth fixing nevertheless.

Validated links in Markdown
As you may know, within Markdown, MkDocs really only recognizes relative links that lead to another physical *.md document (or media file). This is a good convention to follow because then the source pages are also freely browsable without MkDocs, for example on GitHub. MkDocs knows that in the output it should turn those *.md links into *.html as appropriate, and it would also always tell you if such a link doesn't actually lead to an existing file.

However, the checks for links were really loose and had many concessions. For example, links that started with / ("absolute") and links that ended with / were left as is and no warning was shown, which allowed such very fragile links to sneak into site sources: links that happen to work right now but get no validation and links that confusingly need an extra level of .. with use_directory_urls enabled.

Now, in addition to validating relative links, MkDocs will print INFO messages for unrecognized types of links (including absolute links). They look like this:

INFO - Doc file 'example.md' contains an absolute link '/foo/bar/', it was left as is. Did you mean 'foo/bar.md'?

Alternatively we can just ignore it as described in the mkdocs 1.5.0 changelog, but I'm not keen on this approach:

If you don't want any changes, not even the INFO messages, and wish to revert to the silence from MkDocs 1.4, add the following configs to mkdocs.yml (not recommended):

validation:
 absolute_links: ignore
 unrecognized_links: ignore