Add useHostedBaseUrlForAbsoluteLinks option

Closes #940

CHANGELOG.md

@@ -5,7 +5,7 @@
 -   Update website docs - consider if reworking website to just be a TypeDoc generated site is a good idea
     `@license`, `@import`, `@hideGroups` `@hideCategories` sitemapBaseUrl, markedOptions -> markdownItOptions, markdownItLoader, navigation
     sort - documents-first, documents-last, alphabetical-ignoring-documents
-    searchInDocuments
+    searchInDocuments, useHostedBaseUrlForAbsoluteLinks
 -   #2147, add `referencedProperties` to a `ReferenceType` which is a set of name/comment pairs
 
 ### Breaking Changes
@@ -50,6 +50,7 @@
 -   TypeDoc will now warn if mutually exclusive modifier tags are specified for a comment (e.g. both `@alpha` and `@beta`), #2056.
 -   Added support for JSDoc `@hideconstructor` tag.
     This tag should only be used to work around TypeScript#58653, prefer the more general `@hidden`/`@ignore` tag to hide members normally, #2577.
+-   Added `--useHostedBaseUrlForAbsoluteLinks` option to use the `--hostedBaseUrl` option to produce absolute links to pages on a site, #940.
 -   Fixed an issue where the "On This Page" section would include markdown if the page contained headings contained markdown.
 -   TypeDoc will now warn if a block tag is used which is not defined by the `--blockTags` option.
 -   Added three new sort strategies `documents-first`, `documents-last`, and `alphabetical-ignoring-documents` to order markdown documents.

src/lib/application.ts

@@ -267,6 +267,16 @@ export class Application extends ChildableComponent<
                 "You can define/override local locales with the `locales` option, or contribute them to TypeDoc!" as TranslatedString,
             );
         }
+
+        if (
+            this.options.getValue("useHostedBaseUrlForAbsoluteLinks") &&
+            !this.options.getValue("hostedBaseUrl")
+        ) {
+            this.logger.warn(
+                this.i18n.useHostedBaseUrlForAbsoluteLinks_requires_hostedBaseUrl(),
+            );
+            this.options.setValue("useHostedBaseUrlForAbsoluteLinks", false);
+        }
     }
 
     private setOptions(options: Partial<TypeDocOptions>, reportErrors = true) {

src/lib/internationalization/translatable.ts

@@ -260,6 +260,8 @@ export const translatable = {
         "Generate a .nojekyll file to prevent 404 errors in GitHub Pages. Defaults to `true`.",
     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_useHostedBaseUrlForAbsoluteLinks:
+        "If set, TypeDoc will produce absolute links to pages on your site using the hostedBaseUrl option.",
     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.",
@@ -362,6 +364,8 @@ export const translatable = {
         "highlightLanguages contains invalid languages: {0}, run typedoc --help for a list of supported languages.",
     hostedBaseUrl_must_start_with_http:
         "hostedBaseUrl must start with http:// or https://",
+    useHostedBaseUrlForAbsoluteLinks_requires_hostedBaseUrl:
+        "The useHostedBaseUrlForAbsoluteLinks option requires that hostedBaseUrl be set",
     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/components.ts

@@ -7,6 +7,7 @@ import type {
 } from "../models/reflections/index";
 import type { Renderer } from "./renderer";
 import { RendererEvent, PageEvent } from "./events";
+import { Option } from "../utils";
 
 export { Component };
 
@@ -39,6 +40,14 @@ export abstract class ContextAwareRendererComponent extends RendererComponent {
      */
     protected urlPrefix = /^(http|ftp)s?:\/\//;
 
+    private get hostedBaseUrl() {
+        const url = this.application.options.getValue("hostedBaseUrl");
+        return !url || url.endsWith("/") ? url : url + "/";
+    }
+
+    @Option("useHostedBaseUrlForAbsoluteLinks")
+    private accessor useHostedBaseUrlForAbsoluteLinks!: boolean;
+
     /**
      * Create a new ContextAwareRendererPlugin instance.
      *
@@ -67,7 +76,13 @@ export abstract class ContextAwareRendererComponent extends RendererComponent {
             const key = `${this.location}:${absolute}`;
             let path = this.absoluteToRelativePathMap.get(key);
             if (path) return path;
-            path = Path.posix.relative(this.location, absolute) || ".";
+
+            if (this.useHostedBaseUrlForAbsoluteLinks) {
+                path = new URL(absolute, this.hostedBaseUrl).toString();
+            } else {
+                path = Path.posix.relative(this.location, absolute) || ".";
+            }
+
             this.absoluteToRelativePathMap.set(key, path);
             return path;
         }

src/lib/output/themes/default/assets/typedoc/Navigation.ts

@@ -34,7 +34,8 @@ async function buildNav() {
         .pipeThrough(new DecompressionStream("gzip"));
     const nav: NavigationElement[] = await new Response(json).json();
 
-    BASE_URL = container.dataset.base + "/";
+    BASE_URL = container.dataset.base!;
+    if (!BASE_URL.endsWith("/")) BASE_URL += "/";
     container.innerHTML = "";
     for (const el of nav) {
         buildNavElement(el, container, []);

src/lib/utils/options/declaration.ts

@@ -163,6 +163,7 @@ export interface TypeDocOptionMap {
     cname: string;
     githubPages: boolean;
     hostedBaseUrl: string;
+    useHostedBaseUrlForAbsoluteLinks: boolean;
     cacheBust: boolean;
     gaID: string;
     hideGenerator: boolean;

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

@@ -483,6 +483,11 @@ export function addTypeDocOptions(options: Pick<Options, "addDeclaration">) {
             }
         },
     });
+    options.addDeclaration({
+        name: "useHostedBaseUrlForAbsoluteLinks",
+        help: (i18n) => i18n.help_useHostedBaseUrlForAbsoluteLinks(),
+        type: ParameterType.Boolean,
+    });
     options.addDeclaration({
         name: "gaID",
         help: (i18n) => i18n.help_gaID(),