Check for broken links

[AtrusRiven]

I haven't yet found the possibility/feature to check for broken links, i.e. for links that worked once but are eventually now broken due to changes in the structure and filenames of markdown files that have not been corrected in all links.

Before opening a change request:

• Is there such a possibility/feature?
• Is such a feature planned or already decided against?
• Is there a workaround others use for this use case? (I presume, like me there are people who can't always have all places in mind you have to refactor when changing a filename.)

Thanks a lot for hints and tips!

[alexvoss]

Internal links are checked by MkDocs itself. By default it spits out a warning when a link target is not found. If you want the build to fail you can use strict mode.

For external links you would need to use a plugin. mkdocs-linkcheck is one such plugin. I have not used it yet but now that I have come across it, might as well give it a spin...

[AtrusRiven]

Thanks for these very helpful answers. Unfortunately, I have a persistent problems I want to discuss here:

• I use the i18n plugin and mark the English pages with en.md. The links in these pages have to be set as if the pages are already structured like the final result (in en sub-folders). But this results in the compiler display an error for every link because the en sub-folder is only created after the checks. How do you solve this issue?

Thanks again!

[kamilkrzyskow]

Umm, the Markdown links you create in the .md files should only point to .md files or internal # tags files according to the file system structure, not the actual generated HTML pages.

Also the i18n should manage the suffixes by itself, unless you try to link between languages there should be no issues, so simply use filename.md when linking to it, no need to linking to filename.en.md 🤔

Also the blog plugin is currently incompatible with the i18n plugin, so I'm surprised that you use both of them 👀

[AtrusRiven]

Thanks again for you answer (I delete my second question to the blog plugin categories; links to these categories work if you link to a non-existing MD file which after building exists as a HTML file; so that works).

Actually, I don't use both the blog and the i18n plugin on the same project but in two projects.

I link in the English pages to PDF files (I don't link between languages; the MD links in a language work without problems). Here, I have to set the relative link as if the final en sub-folder already existed. Then the final links to these PDF files work fine. But the compiler gives a warning. Is there a solution?

[kamilkrzyskow]

I assume that the file is in some docs/assets/pdfs/filename.pdf path, so in a file docs/x/y/filename.md you'd link to the image via ../../assets/pdfs/filename.pdf or use an absolute link /assets/pdfs/filename.pdf and adjust the validation mentioned above so absolute links don't produces errors.

[alexvoss]

One possible solution would be to use absolute links for the PDFs and ask MkDocs to ignore them using the validation settings @kamilkrzyskow linked to above? edit: argh, you beat me to it!

[AtrusRiven]

Thanks a lot, @kamilkrzyskow and @alexvoss, for you help. That should do the trick! :-)