Redirect fails in Material for MkDocs

[andrewfullard]

Using Material for MkDocs (https://squidfunk.github.io/mkdocs-material/), adding the redirect plugin fails to result in successful redirects for any internal documentation links to the redirected page, as well as the nav bar.

Configuration setting used:

plugins:
  redirects:
    redirect_maps:
      "old.md": "new.md"

This produces the following warnings:

WARNING  -  A relative path to 'old.md' is included in the 'nav' configuration, which is not found in the documentation files
WARNING  -  Documentation file 'Frequently_Asked_Questions_FAQ_.md' contains a link to 'old.md' which is not found in the documentation files.
WARNING  -  Documentation file 'More_docs.md' contains a link to 'old.md' which is not found in the documentation files.

and trying to open the links with the WARNING message opens the 404 page of the docs.

Is there a specific incompatibility with Material for MkDocs?

[DominikaK]

@andrewfullard we are using this plugin successfully with Material for Mkdocs, see for reference: https://github.com/ezsystems/developer-documentation/blob/master/plugins.yml Are you sure your configuration isn't missing hyphens in from of the keys?

[andrewfullard]

Sadly that did not solve the problem. I still see the WARNING pop up and the redirect does not function, even though it creates an index.html in the appropriate place in the sites directory.

The links created in the HTML end up being e.g. Frequently_Asked_Questions_FAQ_/old.md instead of directly old or new

[kamilkrzyskow]

@andrewfullard The only time when I get such warning:

WARNING  -  A relative path to 'old.md' is included in the 'nav' configuration, which is not found in the documentation files

is when I explicitly add old.md into the nav while it doesn't really exist:

nav:
  - old.md

This mkdocs-redirects plugin doesn't affect the nav at all, it manages the file paths without it.

Provide some minimal example ZIP archive where this error occurs, if you have private data in your files then you can make them empty 🤷

You could also try out my automatic solution here https://github.com/mkdocs/mkdocs/discussions/3134 Maybe it will help you out.

[andrewfullard]

Thanks for taking a look! Here's an extremely minimal example with 3 files. Conda environment too. Still gets the same error with only new.md in the nav. I will take a look at your solution. mkdocs-test.zip

[kamilkrzyskow]

Thanks for the minimal example. This is the log I get:

INFO     -  Building documentation...
INFO     -  Cleaning site directory
WARNING  -  Documentation file 'index.md' contains a link to 'old.md' which is not found in the documentation files.
INFO     -  Documentation built in 0.19 seconds

There is no A relative path to 'old.md' is included in the 'nav' warning because there is no old.md in the nav. ✔️ The warning seen above is caused by the [Test link](old.md) link. The old.md doesn't exist and therefore MkDocs warns you about it. ✔️

The idea behind mkdocs-redirects is to assure correct page lookup after it was moved. However, you, as the developer of your docs can (and should) change the link to point to new.md. If a frequent user of your docs visits the yourdocs.com/old/ URL they will be redirected to yourdocs.com/new/, but if they click on the Test link they should be pointed directly to the yourdocs.com/new/ without the need for redirection.

So ultimately this is the expected behavior. To remove that warning, modify the link in the index.md to point to the correct existing file OR create an empty old.md file and the mkdocs-redirects will just overwrite the output HTML. The second option is worse because it will add an INFO "warning".

If you don't want to manage the links inside .md files, maybe the mkdocs-autolinks-plugin could help you 🤔, but you'd still have to create redirections manually (or use my hook idea posted in the previous message).

[andrewfullard]

Thank you so much for the detailed explanation. It seems that I had a fundamental misunderstanding of what mkdocs-redirects actually does. I'll investigate your other suggestions.