Use basePath option for relative links

Gerrit0 · Gerrit0 · commit 3b84d2db017d · 2025-09-13T11:53:21.000-06:00
Resolves #3009
diff --git a/CHANGELOG.md b/CHANGELOG.md
@@ -4,6 +4,12 @@ title: Changelog
 
 ## Unreleased
 
+### Features
+
+- The `basePath` option now also affects relative link resolution, TypeDoc will also check for
+  paths relative to the provided base path. If you instead want TypeDoc to only change the rendered
+  base path for sources, use the `displayBasePath` option, #3009.
+
 ### Bug Fixes
 
 - Fixed bug introduced in 0.28.8 where TypeDoc could not render docs with some mixin classes, #3007.
diff --git a/index.html b/index.html
diff --git a/site/declaration-references.md b/site/declaration-references.md
@@ -4,10 +4,10 @@ title: Declaration References
 
 # Declaration References
 
-> [!note]
-> If [--useTsLinkResolution](options/comments.md#usetslinkresolution) is turned on (the default) this page likely
-> **does not apply** for your links. Declaration references are used only if that option is off or TypeScript
-> fails to resolve a link.
+> [!note] If [--useTsLinkResolution](options/comments.md#usetslinkresolution) is turned on (the default) this page
+> likely **does not apply** for your links within comments (though it will be used for
+> [external documents](./external-documents.md) and for the readme file). Declaration references are used only if that option is
+> off or TypeScript fails to resolve a link.
 
 Some tags like [`{@link}`](tags/link.md) and [`{@inheritDoc}`](tags/inheritDoc.md) can refer to other
 members of the documentation. These tags use declaration references to name another declaration.
diff --git a/site/options.md b/site/options.md
@@ -35,7 +35,7 @@ Options which control TypeDoc's HTML output.
 
 ## Comment Options
 
-Options which control how TypeDoc parses comments.
+Options which control how TypeDoc parses comments and documents.
 
 {@listOptions options/comments.md}
 
diff --git a/site/options/input.md b/site/options/input.md
@@ -35,7 +35,7 @@ If a `"typedoc"` [conditional export](https://nodejs.org/api/packages.html#condi
 TypeDoc will use it instead of the `"import"` export condition.
 
 The set of entry points provided to TypeDoc determines the names displayed in the documentation.
-By default, TypeDoc will derive a [basePath](output.md#basepath) based on your entry point
+By default, TypeDoc will derive a [displayBasePath](output.md#displaybasepath) based on your entry point
 paths to determine the displayed module name, but it can be also be set with the [`@module`](../tags/module.md) tag.
 
 ## entryPointStrategy
@@ -311,14 +311,24 @@ If you are updating documentation for a forked package, you probably want to pas
 typedoc --disableGit
 ```
 
-Prevents TypeDoc from using Git to try to determine if sources can be linked, with this enabled, sources will always be linked, even if not part of a git repo.
+Prevents TypeDoc from using Git to try to determine if sources can be linked, with this enabled, sources will always be
+linked, even if not part of a git repo.
 
 ## readme
 
 ```bash
 typedoc --readme <path/to/readme|none>
 ```
 
-Path to the readme file that should be displayed on the index page. If set to
-`none`, or no readme file is automatically discovered, the index page will be
-disabled.
+Path to the readme file that should be displayed on the index page. If set to `none`, or no readme file is automatically
+discovered, the index page will be disabled.
+
+## basePath
+
+```bash
+typedoc --basePath ./
+```
+
+Path to a directory containing asset files which will be checked when resolving relative paths of links and images
+within documentation comments and external documents. If specified, this will also be used for the default value of
+the [displayBasePath](output.md#displaybasepath) option.
diff --git a/site/options/output.md b/site/options/output.md
@@ -318,14 +318,15 @@ export default {
 };
 ```
 
-## basePath
+## displayBasePath
 
 ```bash
-$ typedoc --basePath ./ --entryPoints src/index.ts
+$ typedoc --displayBasePath ./ --entryPoints src/index.ts
 ```
 
 Specifies the base path to be used when displaying file paths. If not set, TypeDoc will guess by taking the lowest
-common directory to all source files. In the above example, TypeDoc would display links to `index.ts` rather than `src/index.ts`.
+common directory to all source files. In the above example, TypeDoc would display links to `index.ts` rather than `src/index.ts`
+if `displayBasePath` was not specified. Defaults to the value of [basePath](input.md#basepath)
 
 > [!note]
 > This option only affects displayed paths. It _does not_ affect where TypeDoc will create links to.
diff --git a/site/options/package-options.md b/site/options/package-options.md
@@ -53,6 +53,7 @@ at the root level. The following tables indicate where an option should be set.
 | [`gitRemote`](input.md#gitremote)                                       | Package  |                                                                                                           |
 | [`disableGit`](input.md#disablegit)                                     | Package  |                                                                                                           |
 | [`readme`](input.md#readme)                                             | Both     | Root: Site readme, Package: Package readme                                                                |
+| [`basePath`](input.md#basepath)                                         | Both     | Root: Site readme, documents, Package: Package readme, documentation comments, documents                  |
 
 ## Output Options
 
@@ -77,7 +78,7 @@ at the root level. The following tables indicate where an option should be set.
 | [`customFooterHtmlDisableWrapper`](output.md#customfooterhtmldisablewrapper)           | Root     |                                                            |
 | [`markdownItOptions`](output.md#markdownitoptions)                                     | Root     |                                                            |
 | [`markdownItLoader`](output.md#markdownitloader)                                       | Root     |                                                            |
-| [`basePath`](output.md#basepath)                                                       | Both     | Used to determine file names of entry points and documents |
+| [`displayBasePath`](output.md#displaybasepath)                                         | Both     | Used to determine file names of entry points and documents |
 | [`cname`](output.md#cname)                                                             | Root     |                                                            |
 | [`favicon`](output.md#favicon)                                                         | Root     |                                                            |
 | [`sourceLinkExternal`](output.md#sourcelinkexternal)                                   | Root     |                                                            |
diff --git a/src/lib/application.ts b/src/lib/application.ts
@@ -148,6 +148,10 @@ export class Application extends AbstractComponent<
 
     options = new Options();
 
+    /**
+     * Due for deprecation in 0.29, use the reference to this on {@link ProjectReflection},
+     * this was the wrong place for this member to live.
+     */
     files: FileRegistry = new ValidatingFileRegistry();
 
     /** @internal */
@@ -273,6 +277,10 @@ export class Application extends AbstractComponent<
             this.logger.level = this.options.getValue("logLevel");
         }
 
+        if (this.files instanceof ValidatingFileRegistry) {
+            this.files.basePath = this.options.getValue("basePath");
+        }
+
         for (
             const [lang, locales] of Object.entries(
                 this.options.getValue("locales"),
@@ -827,7 +835,7 @@ export class Application extends AbstractComponent<
         for (const { dir, options } of projectsToConvert) {
             this.logger.info(i18n.converting_project_at_0(nicePath(dir)));
             this.options = options;
-            this.files = new ValidatingFileRegistry();
+            this.files = new ValidatingFileRegistry(options.getValue("basePath"));
             let project = await this.convert();
             if (project) {
                 this.validate(project);
diff --git a/src/lib/converter/plugins/SourcePlugin.ts b/src/lib/converter/plugins/SourcePlugin.ts
@@ -10,7 +10,7 @@ import { SourceReference } from "../../models/index.js";
 import { gitIsInstalled, RepositoryManager } from "../utils/repository.js";
 import { ConverterEvents } from "../converter-events.js";
 import type { Converter } from "../converter.js";
-import { i18n, type NormalizedPath } from "#utils";
+import { i18n } from "#utils";
 
 /**
  * A handler that attaches source file information to reflections.
@@ -31,8 +31,9 @@ export class SourcePlugin extends ConverterComponent {
     @Option("sourceLinkTemplate")
     accessor sourceLinkTemplate!: string;
 
-    @Option("basePath")
-    accessor basePath!: NormalizedPath;
+    get displayBasePath() {
+        return this.application.options.getValue("displayBasePath") || this.application.options.getValue("basePath");
+    }
 
     /**
      * All file names to find the base path from.
@@ -157,7 +158,7 @@ export class SourcePlugin extends ConverterComponent {
             );
         }
 
-        const basePath = this.basePath || getCommonDirectory([...this.fileNames]);
+        const basePath = this.displayBasePath || getCommonDirectory([...this.fileNames]);
         this.repositories ||= new RepositoryManager(
             basePath,
             this.gitRevision,
diff --git a/src/lib/internationalization/locales/en.cts b/src/lib/internationalization/locales/en.cts
@@ -311,12 +311,14 @@ export = {
         "Use the specified remote for linking to GitHub/Bitbucket source files. Has no effect if disableGit or disableSources is set",
     help_disableGit:
         "Assume that all can be linked to with the sourceLinkTemplate, sourceLinkTemplate must be set if this is enabled. {path} will be rooted at basePath",
-    help_basePath: "Specifies the base path to be used when displaying file paths",
+    help_displayBasePath:
+        "Specifies the base path to be used when displaying file paths. If not specified, basePath is used.",
     help_excludeTags: "Remove the listed block/modifier tags from doc comments",
     help_notRenderedTags: "Tags which will be preserved in doc comments, but not rendered when creating output",
     help_cascadedModifierTags: "Modifier tags which should be copied to all children of the parent reflection",
     help_readme:
         "Path to the readme file that should be displayed on the index page. Pass `none` to disable the index page and start the documentation on the globals page",
+    help_basePath: "Specifies a path which links may be resolved relative to.",
     help_cname: "Set the CNAME file text, it's useful for custom domains on GitHub Pages",
     help_favicon: "Path to favicon to include as the site icon",
     help_sourceLinkExternal:
diff --git a/src/lib/utils/ValidatingFileRegistry.ts b/src/lib/utils/ValidatingFileRegistry.ts
@@ -4,17 +4,33 @@ import { i18n, type NormalizedPath, NormalizedPathUtils } from "#utils";
 import { existsSync } from "fs";
 
 export class ValidatingFileRegistry extends FileRegistry {
+    basePath: NormalizedPath;
+
+    constructor(basePath: NormalizedPath = "") {
+        super();
+        this.basePath = basePath;
+    }
+
     override register(
         sourcePath: NormalizedPath,
         relativePath: NormalizedPath,
     ): { target: FileId; anchor: string | undefined } | undefined {
-        const absolute = NormalizedPathUtils.resolve(NormalizedPathUtils.dirname(sourcePath), relativePath);
-        const absoluteWithoutAnchor = absolute.replace(/#.*/, "");
+        let absolute = NormalizedPathUtils.resolve(NormalizedPathUtils.dirname(sourcePath), relativePath);
+        let absoluteWithoutAnchor = absolute.replace(/#.*/, "");
         // Note: We allow paths to directories to be registered here, but the AssetsPlugin will not
         // copy them to the output path. This is so that we can link to directories and associate them
         // with reflections in packages mode.
         if (!existsSync(absoluteWithoutAnchor)) {
-            return;
+            // If the relative path didn't exist normally, also check the path relative to the assetBasePath option
+            if (this.basePath != "") {
+                absolute = NormalizedPathUtils.resolve(this.basePath, relativePath);
+                absoluteWithoutAnchor = absolute.replace(/#.*/, "");
+                if (!existsSync(absoluteWithoutAnchor)) {
+                    return;
+                }
+            } else {
+                return;
+            }
         }
         return this.registerAbsolute(absolute);
     }
diff --git a/src/lib/utils/entry-point.ts b/src/lib/utils/entry-point.ts
@@ -196,7 +196,7 @@ export function getDocumentEntryPoints(
         options,
         supportedFileRegex,
     );
-    const baseDir = options.getValue("basePath") || getCommonDirectory(expanded);
+    const baseDir = options.getValue("displayBasePath") || options.getValue("basePath") || getCommonDirectory(expanded);
     return expanded.map((path) => {
         return {
             displayName: relative(baseDir, path).replace(/\.[^.]+$/, ""),
@@ -293,7 +293,8 @@ function getEntryPointsForPaths(
     options: Options,
     programs = getEntryPrograms(inputFiles, logger, options),
 ): DocumentationEntryPoint[] {
-    const baseDir = options.getValue("basePath") || getCommonDirectory(inputFiles);
+    const baseDir = options.getValue("displayBasePath") || options.getValue("basePath") ||
+        getCommonDirectory(inputFiles);
     const entryPoints: DocumentationEntryPoint[] = [];
     let expandSuggestion = true;
 
diff --git a/src/lib/utils/options/declaration.ts b/src/lib/utils/options/declaration.ts
@@ -222,6 +222,7 @@ export interface TypeDocOptionMap {
     gitRevision: string;
     gitRemote: string;
     readme: string;
+    basePath: NormalizedPath;
 
     // Output
     outputs: ManuallyValidatedOption<Array<OutputSpecification>>;
@@ -261,7 +262,7 @@ export interface TypeDocOptionMap {
      * strictly typed here.
      */
     markdownItLoader: ManuallyValidatedOption<(parser: any) => void>;
-    basePath: NormalizedPath;
+    displayBasePath: NormalizedPath;
     cname: string;
     favicon: NormalizedPath;
     githubPages: boolean;
diff --git a/src/lib/utils/options/sources/typedoc.ts b/src/lib/utils/options/sources/typedoc.ts
@@ -20,9 +20,7 @@ function makeTagArrayValidator(name: keyof TypeDocOptionMap) {
 
 // For convenience, added in the same order as they are documented on the website.
 export function addTypeDocOptions(options: Pick<Options, "addDeclaration">) {
-    ///////////////////////////
-    // Configuration Options //
-    ///////////////////////////
+    // MARK: Configuration Options
 
     options.addDeclaration({
         type: ParameterType.Path,
@@ -96,9 +94,7 @@ export function addTypeDocOptions(options: Pick<Options, "addDeclaration">) {
         },
     });
 
-    ///////////////////////////
-    ////// Input Options //////
-    ///////////////////////////
+    // MARK: Input Options
 
     options.addDeclaration({
         name: "entryPoints",
@@ -232,10 +228,18 @@ export function addTypeDocOptions(options: Pick<Options, "addDeclaration">) {
             }
         },
     });
+    options.addDeclaration({
+        name: "readme",
+        help: () => i18n.help_readme(),
+        type: ParameterType.Path,
+    });
+    options.addDeclaration({
+        name: "basePath",
+        help: () => i18n.help_basePath(),
+        type: ParameterType.Path,
+    });
 
-    ///////////////////////////
-    ///// Output Options //////
-    ///////////////////////////
+    // MARK: Output Options
 
     options.addDeclaration({
         name: "outputs",
@@ -454,13 +458,8 @@ export function addTypeDocOptions(options: Pick<Options, "addDeclaration">) {
         type: ParameterType.Boolean,
     });
     options.addDeclaration({
-        name: "basePath",
-        help: () => i18n.help_basePath(),
-        type: ParameterType.Path,
-    });
-    options.addDeclaration({
-        name: "readme",
-        help: () => i18n.help_readme(),
+        name: "displayBasePath",
+        help: () => i18n.help_displayBasePath(),
         type: ParameterType.Path,
     });
     options.addDeclaration({
@@ -720,9 +719,7 @@ export function addTypeDocOptions(options: Pick<Options, "addDeclaration">) {
         type: ParameterType.Boolean,
     });
 
-    ///////////////////////////
-    ///// Comment Options /////
-    ///////////////////////////
+    // MARK: Comment Options
 
     options.addDeclaration({
         name: "jsDocCompatibility",
@@ -807,9 +804,7 @@ export function addTypeDocOptions(options: Pick<Options, "addDeclaration">) {
         validate: makeTagArrayValidator("cascadedModifierTags"),
     });
 
-    ///////////////////////////
-    // Organization Options ///
-    ///////////////////////////
+    // MARK: Organization Options
 
     options.addDeclaration({
         name: "categorizeByGroup",
@@ -884,9 +879,7 @@ export function addTypeDocOptions(options: Pick<Options, "addDeclaration">) {
         },
     });
 
-    ///////////////////////////
-    ///// General Options /////
-    ///////////////////////////
+    // MARK: General Options
 
     options.addDeclaration({
         name: "watch",
diff --git a/src/test/converter2/issues/gh3009.ts b/src/test/converter2/issues/gh3009.ts
@@ -0,0 +1,7 @@
+/**
+ * [link with base path](src/test/converter2/issues/gh3009.ts)
+ * [link direct](gh3009.ts)
+ *
+ * [asset link](CHANGELOG.md)
+ */
+export const x = 1;
diff --git a/src/test/issues.c2.test.ts b/src/test/issues.c2.test.ts
diff --git a/src/test/programs.ts b/src/test/programs.ts
