Specify a custom canonical URL for each page

[day-jeff]

Is there a way to specify a custom canonical URL for each page?

Here's my scenario:

• Most of our site is hosted on a stand-alone web site, but we have published a subset of our pages to a higher profile site.
• We want both copies of the pages to work within the context of their local site. This assures that users on both sites have a seamless experience.
• We want search indexers to treat the new site as the canonical site. Thus we want to specify a custom canonical URL for the pages on the old site.
• site_url doesn't help because it applies to all pages on our site.
• The URL paths are not exactly the same on each site, so we can't use a generic base path as the canonical path for the duplicate pages.
• Thus, I am hoping to be able to manually specify a custom canonical URL for each page in its front matter or in some other way.

All help appreciated!

[kamilkrzyskow]

Hello @day-jeff,
the base.html template uses the page.canonical_url property to render the canonical metadata:

mkdocs-material/src/templates/base.html

Lines 48 to 51 in 39507ac

	<!-- Canonical -->
	{% if page.canonical_url %}
	<link rel="canonical" href="{{ page.canonical_url }}" />
	{% endif %}

and it's set to site_url during Page object initialization: https://github.com/mkdocs/mkdocs/blob/d6fcc56a3e2b287a2dc0310a7472ba4cdb177854/mkdocs/structure/pages.py#L49

So the only solution I see, is to change the page.canonical_url before the base.html template is rendered.
To do that you can make a hook and use an event that has both access to the page's front matter and is run before it's rendered. So e.g. on_page_markdown would do just fine.

def on_page_markdown(markdown, *, page, config, files):
    
    # Get key from front matter
    canonical_url = page.meta.get("canonical_url")
    
    # Skip processing page when key not found
    if canonical_url is None:
        return
        
    # Assign the custom url to the page
    page.canonical_url = canonical_url

Code is untested 🤞 I hope it works

Also you could make it more dynamic perhaps, you said that some sites should have the changed canonical_url, so maybe they're in a directory or have some other matching pattern. You could use that pattern instead of adding front matter keys to them.

[day-jeff]

@kamilkrzyskow: Thank you so much for such a great response! It worked perfectly on the first run.

I'm not a mkdocs expert by any means, and I thought I might need to create a custom plugin to enable this. But this hook is much simpler and just works.

[day-jeff]

The path and file names are the same on the new site, but only a subset of pages are published there. So I use your code as is to retrieve front matter value indicating whether the page is published to the new site, and I rewrite page.canonical_url when it is. So simple now that I understand how hooks and mkdocs events work.

[kamilkrzyskow]

but only a subset of pages are published there

Yes, I understood it from the OP, just maybe that subset of published pages is in a specific directory or has some naming pattern or whatever. Therefore you could skip modifying each page with the custom front matter and just use a conditional to detect that shared pattern and modify the page.canonical_url based on this criteria.

If you're gonna stick to manual setting of the canonical_url front matter, then perhaps consider adding some validation to the hook.
Add a logger to the hook, and log.warning("Invalid canonical_url") when the URL is not valid, has a typo etc.

Just some food for thought ✌️

[day-jeff]

Ah! You and I are aligned. We already use custom front matter to specify which pages are published to the new site. Thus, I wrote code that looks at this existing value and automatically generates the correct canonical URL if needed. Thus, no need to edit the pages. Everything happens in the hook.