Validate anchors in relative links

Author: Gerrit0

CHANGELOG.md

@@ -8,6 +8,12 @@ title: Changelog
 
 -   Relaxed requirements for file names and generated url fragments. This may
     result in a different file name structure, #2714.
+-   Anchors to document headings and reflections within a HTML generated pages
+    have changed. They can be partially restored to the previous format by
+    setting `--sluggerConfiguration.lowercase false`. This change was made to
+    more closely match the default behavior of GitHub's markdown rendering and
+    VSCode's autocomplete when creating a relative link to an external markdown
+    file.
 -   Removed the `hideParameterTypesInTitle` option, this was originally added as
     a workaround for many signatures overflowing the available horizontal space
     in rendered pages. TypeDoc now has logic to wrap types/signatures smartly,
@@ -26,6 +32,8 @@ title: Changelog
 
 -   TypeDoc will now discover entry points from `package.json` exports if they
     are not provided manually, #1937.
+-   Relative links to markdown files may now include `#anchor` links to
+    reference a heading within them.
 -   Improved support for `@param` comments with nested object types, #2555.
 -   Improved support for `@param` comments which reference a type
     alias/interface. Important properties on the referenced type can now be
@@ -94,7 +102,6 @@ title: Changelog
 
 TODO:
 
--   Validate anchors within relative linked paths?
 -   Figure out automation for beta releases
 
 # Unreleased

site/options/output.md

@@ -354,6 +354,38 @@ categories/groups.
 -   `@showCategories`
 -   `@hideCategories`
 
+## headings
+
+```json
+// typedoc.json
+{
+    "headings": {
+        "readme": true,
+        "document": false
+    }
+}
+```
+
+Defines whether a heading describing the reflection should be included on the rendered page.
+
+## sluggerConfiguration
+
+```json
+// typedoc.json
+{
+    "sluggerConfiguration": {
+        "lowercase": true
+    }
+}
+```
+
+Determines how anchors within a page are created. This option exists primarily
+for backwards compatibility. It may be removed in a future release. TypeDoc 0.26
+did not lowercase headings within a page which is inconsistent with how GitHub
+pages sites commonly generate headings and does not play well with VSCode's
+autocomplete to anchors within external markdown files. In 0.27, this option
+defaults to `true`.
+
 ## navigationLeaves
 
 ```json

site/overview.md

@@ -32,7 +32,7 @@ support more versions of TypeScript.
 
 TypeDoc's CLI can be used through your terminal or npm scripts. Any arguments
 passed to TypeDoc which are not flags are parsed as entry points. TypeDoc will
-also read configuration from several files. See [Configuration](./options/configuration.md)
+also read configuration from several files. See [Configuration](./options/configuration.md#compileroptions)
 for details on where options are read from.
 
 <details>

src/lib/converter/comments/textParser.ts

@@ -9,7 +9,10 @@ import type {
     TranslationProxy,
     TranslatedString,
 } from "../../internationalization/index.js";
-import type { CommentDisplayPart } from "../../models/index.js";
+import type {
+    CommentDisplayPart,
+    RelativeLinkDisplayPart,
+} from "../../models/index.js";
 import type { FileRegistry } from "../../models/FileRegistry.js";
 import { HtmlAttributeParser, ParserState } from "../../utils/html.js";
 import { type Token, TokenSyntaxKind } from "./lexer.js";
@@ -32,6 +35,7 @@ interface RelativeLink {
     end: number;
     /** May be undefined if the registry can't find this file */
     target: number | undefined;
+    targetAnchor: string | undefined;
 }
 
 /**
@@ -92,11 +96,13 @@ export function textContent(
             kind: "text",
             text: token.text.slice(lastPartEnd, ref.pos),
         });
-        outContent.push({
+        const link: RelativeLinkDisplayPart = {
             kind: "relative-link",
             text: token.text.slice(ref.pos, ref.end),
             target: ref.target,
-        });
+            targetAnchor: ref.targetAnchor,
+        };
+        outContent.push(link);
         lastPartEnd = ref.end;
         data.pos = ref.end;
         if (!ref.target) {
@@ -190,10 +196,15 @@ function checkMarkdownLink(
             // Only make a relative-link display part if it's actually a relative link.
             // Discard protocol:// links, unix style absolute paths, and windows style absolute paths.
             if (isRelativePath(link.str)) {
+                const { target, anchor } = files.register(
+                    sourcePath,
+                    link.str,
+                ) || { target: undefined, anchor: undefined };
                 return {
                     pos: labelEnd + 2,
                     end: link.pos,
-                    target: files.register(sourcePath, link.str),
+                    target,
+                    targetAnchor: anchor,
                 };
             }
 
@@ -241,10 +252,15 @@ function checkReference(data: TextParserData): RelativeLink | undefined {
 
                 if (link.ok) {
                     if (isRelativePath(link.str)) {
+                        const { target, anchor } = files.register(
+                            sourcePath,
+                            link.str,
+                        ) || { target: undefined, anchor: undefined };
                         return {
                             pos: lookahead,
                             end: link.pos,
-                            target: files.register(sourcePath, link.str),
+                            target,
+                            targetAnchor: anchor,
                         };
                     }
 
@@ -286,13 +302,15 @@ function checkAttribute(
 
             if (isRelativePath(parser.currentAttributeValue)) {
                 data.pos = parser.pos;
+                const { target, anchor } = data.files.register(
+                    data.sourcePath,
+                    parser.currentAttributeValue,
+                ) || { target: undefined, anchor: undefined };
                 return {
                     pos: parser.currentAttributeValueStart,
                     end: parser.currentAttributeValueEnd,
-                    target: data.files.register(
-                        data.sourcePath,
-                        parser.currentAttributeValue,
-                    ),
+                    target,
+                    targetAnchor: anchor,
                 };
             }
             return;

src/lib/internationalization/locales/en.cts

@@ -131,7 +131,7 @@ export = {
     could_not_empty_output_directory_0: `Could not empty the output directory {0}`,
     could_not_create_output_directory_0: `Could not create the output directory {0}`,
     theme_0_is_not_defined_available_are_1: `The theme '{0}' is not defined. The available themes are: {1}`,
-    custom_theme_does_not_define_getSlugger: `Custom theme does not define a getSlugger(reflection) method, but tries to render markdown`,
+    reflection_0_links_to_1_but_anchor_does_not_exist_try_2: `{0} links to {1}, but the anchor does not exist. You may have meant:\n\t{2}`,
 
     // entry points
     no_entry_points_provided:
@@ -295,6 +295,8 @@ export = {
     help_navigationLeaves:
         "Branches of the navigation tree which should not be expanded",
     help_headings: "Determines which optional headings are rendered",
+    help_sluggerConfiguration:
+        "Determines how anchors within rendered HTML are determined.",
     help_navigation: "Determines how the navigation sidebar is organized",
     help_visibilityFilters:
         "Specify the default visibility for builtin filters and additional filters according to modifier tags",

src/lib/internationalization/locales/jp.cts

@@ -142,8 +142,6 @@ export = localeUtils.buildIncompleteTranslation({
         "出力ディレクトリ {0} を作成できませんでした",
     theme_0_is_not_defined_available_are_1:
         "テーマ '{0}' は定義されていません。使用可能なテーマは次のとおりです: {1}",
-    custom_theme_does_not_define_getSlugger:
-        "カスタムテーマはgetSlugger(reflection)メソッドを定義していませんが、マークダウンをレンダリングしようとします",
     // no_entry_points_provided:
     unable_to_find_any_entry_points:
         "エントリ ポイントが見つかりません。以前の警告を参照してください",

src/lib/internationalization/locales/zh.cts

@@ -146,8 +146,6 @@ export = localeUtils.buildIncompleteTranslation({
     could_not_empty_output_directory_0: "无法清空输出目录 {0}",
     could_not_create_output_directory_0: "无法创建输出目录 {0}",
     theme_0_is_not_defined_available_are_1: "主题“{0}”未定义。可用主题为：{1}",
-    custom_theme_does_not_define_getSlugger:
-        "自定义主题没有定义 getSlugger(reflection) 方法，但尝试渲染 markdown",
 
     no_entry_points_provided: "没有提供入口点，这可能是配置错误",
     unable_to_find_any_entry_points: "无法找到任何入口点。请参阅先前的警告",

src/lib/models/FileRegistry.ts

@@ -19,32 +19,44 @@ export class FileRegistry {
     protected names = new Map<number, string>();
     protected nameUsage = new Map<string, number>();
 
-    registerAbsolute(absolute: string) {
+    registerAbsolute(absolute: string): {
+        target: number;
+        anchor: string | undefined;
+    } {
+        const anchorIndex = absolute.indexOf("#");
+        let anchor: string | undefined = undefined;
+        if (anchorIndex !== -1) {
+            anchor = absolute.substring(anchorIndex + 1);
+            absolute = absolute.substring(0, anchorIndex);
+        }
         absolute = normalizePath(absolute).replace(/#.*/, "");
         const existing = this.pathToMedia.get(absolute);
         if (existing) {
-            return existing;
+            return { target: existing, anchor };
         }
 
         this.mediaToPath.set(this.nextId, absolute);
         this.pathToMedia.set(absolute, this.nextId);
 
-        return this.nextId++;
+        return { target: this.nextId++, anchor };
     }
 
     /** Called by {@link ProjectReflection.registerReflection} @internal*/
     registerReflection(absolute: string, reflection: Reflection) {
         absolute = normalizePath(absolute);
-        const id = this.registerAbsolute(absolute);
+        const { target } = this.registerAbsolute(absolute);
         this.reflectionToPath.set(reflection.id, absolute);
-        this.mediaToReflection.set(id, reflection.id);
+        this.mediaToReflection.set(target, reflection.id);
     }
 
     getReflectionPath(reflection: Reflection): string | undefined {
         return this.reflectionToPath.get(reflection.id);
     }
 
-    register(sourcePath: string, relativePath: string): number | undefined {
+    register(
+        sourcePath: string,
+        relativePath: string,
+    ): { target: number; anchor: string | undefined } | undefined {
         return this.registerAbsolute(
             resolve(dirname(sourcePath), relativePath),
         );
@@ -131,7 +143,8 @@ export class FileRegistry {
     fromObject(de: Deserializer, obj: JSONFileRegistry): void {
         for (const [key, val] of Object.entries(obj.entries)) {
             const absolute = normalizePath(resolve(de.projectRoot, val));
-            de.oldFileIdToNewFileId[+key] = this.registerAbsolute(absolute);
+            de.oldFileIdToNewFileId[+key] =
+                this.registerAbsolute(absolute).target;
         }
 
         de.defer((project) => {
@@ -154,12 +167,10 @@ export class ValidatingFileRegistry extends FileRegistry {
     override register(
         sourcePath: string,
         relativePath: string,
-    ): number | undefined {
-        const absolute = resolve(dirname(sourcePath), relativePath).replace(
-            /#.*/,
-            "",
-        );
-        if (!isFile(absolute)) {
+    ): { target: number; anchor: string | undefined } | undefined {
+        const absolute = resolve(dirname(sourcePath), relativePath);
+        const absoluteWithoutAnchor = absolute.replace(/#.*/, "");
+        if (!isFile(absoluteWithoutAnchor)) {
             return;
         }
         return this.registerAbsolute(absolute);
@@ -178,7 +189,8 @@ export class ValidatingFileRegistry extends FileRegistry {
                 continue;
             }
 
-            de.oldFileIdToNewFileId[+key] = this.registerAbsolute(absolute);
+            de.oldFileIdToNewFileId[+key] =
+                this.registerAbsolute(absolute).target;
         }
 
         de.defer((project) => {

src/lib/models/comments/comment.ts

@@ -68,6 +68,10 @@ export interface RelativeLinkDisplayPart {
      * This may be `undefined` if the relative path does not exist.
      */
     target: number | undefined;
+    /**
+     * Anchor within the target page, validated after rendering if possible
+     */
+    targetAnchor: string | undefined;
 }
 
 /**
@@ -230,7 +234,7 @@ export class Comment {
                 case "relative-link": {
                     return {
                         ...part,
-                    };
+                    } satisfies JSONOutput.CommentDisplayPart;
                 }
             }
         });
@@ -293,11 +297,16 @@ export class Comment {
                             kind: "relative-link",
                             text: part.text,
                             target: null!,
+                            targetAnchor: part.targetAnchor,
                         } satisfies RelativeLinkDisplayPart;
                         files.push([part.target, part2]);
                         return part2;
                     }
-                    return { ...part, target: undefined };
+                    return {
+                        ...part,
+                        target: undefined,
+                        targetAnchor: part.targetAnchor,
+                    };
                 }
             }
         });

src/lib/models/reflections/abstract.ts

@@ -17,7 +17,6 @@ import type {
     TranslatedString,
 } from "../../internationalization/index.js";
 import type { ParameterReflection } from "./parameter.js";
-import { createNormalizedUrl } from "../../utils/html.js";
 import type { ReferenceReflection } from "./reference.js";
 
 /**
@@ -315,13 +314,6 @@ export abstract class Reflection {
      */
     hasOwnDocument?: boolean;
 
-    /**
-     * Url safe alias for this reflection.
-     */
-    private _alias?: string;
-
-    private _aliases?: Map<string, number>;
-
     constructor(name: string, kind: ReflectionKind, parent?: Reflection) {
         this.id = REFLECTION_ID++ as ReflectionId;
         this.parent = parent;
@@ -392,45 +384,6 @@ export abstract class Reflection {
         this.flags.setFlag(flag, value);
     }
 
-    /**
-     * Return an url safe alias for this reflection.
-     */
-    getAlias(): string {
-        this._alias ||= this.getUniqueAliasInPage(
-            createNormalizedUrl(this.name) || `reflection-${this.id}`,
-        );
-
-        return this._alias;
-    }
-
-    // This really ought not live here, it ought to live in the html renderer, but moving that
-    // is more work than I want right now, it can wait for 0.27 when trying to split models into
-    // a bundleable structure.
-    getUniqueAliasInPage(heading: string) {
-        // NTFS/ExFAT use uppercase, so we will too. It probably won't matter
-        // in this case since names will generally be valid identifiers, but to be safe...
-        const upperAlias = heading.toUpperCase();
-
-        let target = this as Reflection;
-        while (target.parent && !target.hasOwnDocument) {
-            target = target.parent;
-        }
-
-        target._aliases ||= new Map();
-
-        let suffix = "";
-        if (!target._aliases.has(upperAlias)) {
-            target._aliases.set(upperAlias, 1);
-        } else {
-            const count = target._aliases.get(upperAlias)!;
-            suffix = "-" + count.toString();
-            target._aliases.set(upperAlias, count + 1);
-        }
-
-        heading += suffix;
-        return heading;
-    }
-
     /**
      * Has this reflection a visible comment?
      *