Rename sitemapBaseUrl to hostedBaseUrl

Also add canonical link to index.html when set.

Resolves #2550

CHANGELOG.md

@@ -7,6 +7,7 @@
     This means that any projects setting `markedOptions` needs to be updated to use `markdownItOptions`.
     Unlike `marked@4`, `markdown-it` pushes lots of functionality to plugins. To use plugins, a JavaScript config file must be used with the `markdownItLoader` option.
 -   Updated Shiki from 0.14 to 1.3. This should mostly be a transparent update which adds another 23 supported languages and 13 supported themes.
+-   Renamed `--sitemapBaseUrl` to `--hostedBaseUrl` to reflect that it can be used for more than just the sitemap.
 -   Removed deprecated `navigation.fullTree` option.
 -   API: `MapOptionDeclaration.mapError` has been removed.
 -   API: Deprecated `BindOption` decorator has been removed.
@@ -17,6 +18,7 @@
 
 -   TypeDoc now has the architecture in place to support localization. No languages besides English
     are currently shipped in the package, but it is now possible to add support for additional languages, #2475.
+-   `--hostedBaseUrl` will now be used to generate a `<link rel="canonical">` element in the project root page, #2550.
 
 ### Bug Fixes
 

src/lib/internationalization/translatable.ts

@@ -251,8 +251,8 @@ export const translatable = {
         "Specifies that source links should be treated as external links to be opened in a new tab.",
     help_githubPages:
         "Generate a .nojekyll file to prevent 404 errors in GitHub Pages. Defaults to `true`.",
-    help_sitemapBaseUrl:
-        "Specify a base URL to be used in generating a sitemap.xml in our output folder. If not specified, no sitemap will be generated.",
+    help_hostedBaseUrl:
+        "Specify a base URL to be used in generating a sitemap.xml in our output folder and canonical links. If not specified, no sitemap will be generated.",
     help_gaID:
         "Set the Google Analytics tracking ID and activate tracking code.",
     help_hideGenerator: "Do not print the TypeDoc link at the end of the page.",
@@ -346,8 +346,8 @@ export const translatable = {
     external_symbol_link_mappings_must_be_object:
         "externalSymbolLinkMappings must be a Record<package name, Record<symbol name, link>>",
     highlight_theme_0_must_be_one_of_1: "{0} must be one of the following: {1}",
-    sitemap_must_start_with_http:
-        "sitemapBaseUrl must start with http:// or https://",
+    hostedBaseUrl_must_start_with_http:
+        "hostedBaseUrl must start with http:// or https://",
     option_0_must_be_an_object: "The '{0}' option must be a non-array object.",
     option_0_must_be_a_function: "The '{0}' option must be a function.",
     option_0_must_be_object_with_urls: `{0} must be an object with string labels as keys and URL values.`,

src/lib/output/plugins/SitemapPlugin.ts

@@ -4,11 +4,12 @@ import { RendererEvent } from "../events";
 import { DefaultTheme } from "../themes/default/DefaultTheme";
 import { Option, writeFile } from "../../utils";
 import { escapeHtml } from "../../utils/html";
+import { Fragment } from "../../utils/jsx";
 
 @Component({ name: "sitemap" })
 export class SitemapPlugin extends RendererComponent {
-    @Option("sitemapBaseUrl")
-    accessor sitemapBaseUrl!: string;
+    @Option("hostedBaseUrl")
+    accessor hostedBaseUrl!: string;
 
     override initialize() {
         this.listenTo(this.owner, RendererEvent.BEGIN, this.onRendererBegin);
@@ -18,10 +19,21 @@ export class SitemapPlugin extends RendererComponent {
         if (!(this.owner.theme instanceof DefaultTheme)) {
             return;
         }
-        if (event.isDefaultPrevented || !this.sitemapBaseUrl) {
+        if (event.isDefaultPrevented || !this.hostedBaseUrl) {
             return;
         }
 
+        this.owner.hooks.on("head.begin", (context) => {
+            if (context.page.url === "index.html") {
+                return {
+                    tag: "link",
+                    props: { rel: "canonical", href: this.hostedBaseUrl },
+                    children: [],
+                };
+            }
+            return { tag: Fragment, props: null, children: [] };
+        });
+
         this.owner.preRenderAsyncJobs.push((event) => this.buildSitemap(event));
     }
 
@@ -39,7 +51,7 @@ export class SitemapPlugin extends RendererComponent {
                             tag: "loc",
                             children: new URL(
                                 url.url,
-                                this.sitemapBaseUrl,
+                                this.hostedBaseUrl,
                             ).toString(),
                         },
                         {

src/lib/utils/options/declaration.ts

@@ -156,7 +156,7 @@ export interface TypeDocOptionMap {
     basePath: string;
     cname: string;
     githubPages: boolean;
-    sitemapBaseUrl: string;
+    hostedBaseUrl: string;
     cacheBust: boolean;
     gaID: string;
     hideGenerator: boolean;

src/lib/utils/options/sources/typedoc.ts

@@ -429,11 +429,11 @@ export function addTypeDocOptions(options: Pick<Options, "addDeclaration">) {
         defaultValue: true,
     });
     options.addDeclaration({
-        name: "sitemapBaseUrl",
-        help: (i18n) => i18n.help_sitemapBaseUrl(),
+        name: "hostedBaseUrl",
+        help: (i18n) => i18n.help_hostedBaseUrl(),
         validate(value, i18n) {
             if (!/https?:\/\//.test(value)) {
-                throw new Error(i18n.sitemap_must_start_with_http());
+                throw new Error(i18n.hostedBaseUrl_must_start_with_http());
             }
         },
     });