Add canonical-site-url setting

[roberth]

Hi 👋

This implements the suggestion by markhildreth to implement such a setting, based on the conversation in #1238.
<link rel="canonical"> plays an important role in avoiding an SEO penalty when users deploy multiple versions of their site.

I've additionally infixed -site- to highlight the relationship with the site-url, and to distinguish it from the canonical URL as it occurs in a page.

This is a more user-friendly alternative to #2415 as it's an "end to end" solution with documentation. (It may have usages beyond this use case though)

Let me know if there's anything I should improve.
When this is done, I'd like to implement a setting for opting in to clean URLs without the .html suffix so that we can close the whole issue.

Changelog suggestion (not included due to repeated conflicts...)

- Added [`canonical-site-url`](https://rust-lang.github.io/mdBook/format/configuration/renderers.html?highlight=canonical-site-url#html-renderer-options) setting, to set `<link rel="canonical">` in the HTML output of each page.

[pinage404]

I tested locally, it works great

I hope a solution will be merged

[whitequark]

I'd really like to have this functionality; is there a way I can help advance this PR? I want it for #1238.

[roberth]

I've rebased and put my suggestion for a changelog entry in the PR description, because it kept causing conflicts.

Let us know if there's anything else we can do!

[rustbot]

This PR was rebased onto a different master commit. Here's a range-diff highlighting what actually changed.

Rebasing is a normal part of keeping PRs up to date, so no action is needed—this note is just to help reviewers.

[pinage404]

What do you think about adding also the Open Graph URL ?

<meta property="og:url" content="{{ canonical_url }}" />

[roberth]

In my use case where we have versioned copies of the docs and latest, we wouldn't want social media to rewrite the links to point to latest, making it impossible to share this kind of "permalink", so I don't think this is automatically desirable just based on the SEO oriented canonical URL.

IIUC you could add it in the custom html below if it makes sense for your use case.

I guess if you have more equivalent locations in terms of content, you may want social media to rewrite those?
Maybe if your content is published by others too in places where you can't get them to redirect or something, but you can control (a bit) the files that get published. (Sounds almost adversarial, but then it would be pointless to try. Maybe this can happen with some systems/ecosystems that cause duplicates of stuff to be published everywhere? idk - I'll stop speculating)

[roberth]

I guess the more interesting question is would you want to rewrite social media without also hinting the search engines?
If that's a use case, maybe we should only define canonical_url but leave the socials-vs-search decision up to the custom HTML template, to keep things simple for the mdBook implementation?
If we don't have such a use case, I'd like to keep this built-in behavior right here, because otherwise you have a weird setting without any effect unless you customize your theme. That seems like an step too much for me in terms of UX.
So right back at ya, I guess :)
What do you think of removing <link rel="canonical" .../>?