Canonical URL rendering in HTML as the full path to a .md file in translated content

[kattni]

Hello!

I want to preface this with the fact that my current workflow is a bit complicated. I have updated the mkdocs-mdpo-plugin to get it to work with Python 3.13 and an updated version Translate Toolkit md2po tool. (The md2po tool makes better, more accurate .po files. Further, Weblate needs the PO template files, and the plugin doesn't generate them.) So this may be an artifact of some other variable in this setup.

I am currently able to build multiple languages successfully, with translations from the .po files, from mkdocs serve and mkdocs build. However, I noticed that in the translated files, the "canonical URL" is showing up as a full path to a Markdown file (e.g. <link rel="canonical" href="https://docs.beeware.org/fr/index.md"> in the French translated HTML file, versus <link rel="canonical" href="https://docs.beeware.org/"> in the English version).

I read up on how that link is generated, i.e. from the page.canonical_url when the base.html template is rendered, IIRC. So, it seems like it would make sense for it to have the language code appended to it, however, the index.md will ultimately 404 because it won't exist. I have absolutely no idea where to start with figuring out where the full path is coming from, as it doesn't appear to have a configuration option anywhere. I have no idea, though, whether the various things in my workflow could be affecting it.

Let me know if further specific information from my config files, etc, would be helpful here. I didn't want to overload this post if it turned out to be something obvious without needing that information.

I also have no idea what that canonical link is used for, so it may not actually matter. I'm ok with that as well.

[alexvoss]

The canonical_url should come from MkDocs itself, I think. Maybe this already helps solve your problem.

If not, I think I would need some info on how you build things. I have not used the PO plugin before, so not sure what the workflow is with this but I am about to look into all the different ways to generate translations. Would love to learn about how you are doing things so we can ensure we meet your needs in the future. If you can share more about the workflow here that would be great but you can also reach out by email, see my profile.

[kamilkrzyskow]

After having a quick look at the plugin it does orchestrate multi-lingual docs build on its own. Similar to the i18n plugin. In general that's a never ending battle with the plugin ecosystem and event loop, because every external plugin / extension that has its own "build engine" inside becomes a bug fix hell to orchestrate.

Comments from the mdpo-plugin developer:

• Add support to mkdocs-macros plugin mondeja/mkdocs-mdpo-plugin#63 (comment)
• This project is temporary abandoned mondeja/mkdocs-mdpo-plugin#65 (comment)

From my perspective development on the i18n plugin has been mostly abandoned as well, it still doesn't support the Blog plugin, I did add a hack for it to at least display the default language instead of a blank page here, and it required me to temporarily delete the documentation pages from the MkDocs internal objects.

[Side note: I had a full fix in mind for the Blog, but then the work on GMC has died down (the blog has been still not released), and later on it has been decided that at GMC we will opt out of translations, as it adds too much overhead, and no new wannabe translator came around in the last 2 years, so in our case it's better to leave the translation to automated tooling]

As for the canonical URL, every such plugin that orchestrates the build process, needs to handle the management of the canonical URL themselves as well. same for the Blog plugin :)
A bad canonical URL could have an impact on SEO rankings, but I'm not sure how serious this is.

mkdocs-material/src/plugins/blog/plugin.py

Line 426 in b2d235e

post._set_canonical_url(config.site_url)

---

So instead of using orchestrator plugins, the current "recommended" way is to develop separate standalone languages.
Then add your own custom orchestration to make it work for your needs. Like the i18n generates a sitemap.xml with alt languages, and this would have to be done with a custom solution.

• Setting up multi-language installations #2346

There is the projects plugin, which could make things simpler, but it also isn't actively developed due to MkDocs limitations iirc.