Resolving broken anchors in API when nested reflections (e.g. agRegistry#TagGroup#getAllWhere) appears

Author: rislaed

api/docusaurus-plugin/src/components/Index.tsx

@@ -5,22 +5,26 @@ import type { TSDDeclarationReflection } from '../types';
 import { AnchorLink } from './AnchorLink';
 import { Icon } from './Icon';
 import { Name } from './Name';
+import { resolveAnchorLink } from '../utils/links';
 
 export interface IndexChildProps {
 	id: number;
 }
 
 function IndexChild({ id }: IndexChildProps) {
-	const reflection = useRequiredReflection(id);
+    const reflection = useRequiredReflection(id);
 
-	return (
-		<li>
-			<Link className="tsd-kind-icon" to={reflection.permalink ?? `#${reflection.name}`}>
-				<Icon reflection={reflection} />
-				<Name reflection={reflection} colorful={true} />
-			</Link>
-		</li>
-	);
+    return (
+        <li>
+            <Link 
+                className="tsd-kind-icon" 
+                to={reflection.permalink ? resolveAnchorLink(reflection.permalink) : resolveAnchorLink('', reflection.name)}
+            >
+                <Icon reflection={reflection} />
+                <Name reflection={reflection} colorful={true} />
+            </Link>
+        </li>
+    );
 }
 
 export interface IndexProps {

api/docusaurus-plugin/src/plugin/data.ts

@@ -14,6 +14,7 @@ import type {
 } from '../types';
 import { migrateToVersion0230 } from './structure/0.23';
 import { getKindSlug, getPackageSlug, joinUrl } from './url';
+import { resolveAnchorLink } from '../utils/links';
 
 function shouldEmit(projectRoot: string, tsconfigPath: string) {
 	// eslint-disable-next-line @typescript-eslint/no-unsafe-assignment
@@ -176,42 +177,43 @@ export function loadPackageJsonAndDocs(
 }
 
 export function addMetadataToReflections(
-	project: JSONOutput.DeclarationReflection,
-	packageSlug: string,
-	urlPrefix: string,
+    project: JSONOutput.DeclarationReflection,
+    packageSlug: string,
+    urlPrefix: string,
 ): TSDDeclarationReflection {
-	const permalink = `/${joinUrl(urlPrefix, packageSlug)}`;
-
-	if (project.children) {
-		// eslint-disable-next-line no-param-reassign
-		project.children = project.children.map((child) => {
-			migrateToVersion0230(child);
-
-			const kindSlugPart = getKindSlug(child);
-			const childSlug = kindSlugPart ? `/${kindSlugPart}/${child.name}` : `#${child.name}`;
-			const childPermalink = permalink + childSlug;
-
-			// We need to go another level deeper and only use fragments
-			if (child.kind === ReflectionKind.Namespace && child.children) {
-				// eslint-disable-next-line no-param-reassign
-				child.children = child.children.map((grandChild) => ({
-					...grandChild,
-					permalink: normalizeUrl([`${childPermalink}#${grandChild.name}`]),
-				}));
-			}
-
-			return {
-				...child,
-				permalink: normalizeUrl([childPermalink]),
-			};
-		});
-	}
-
-	// @ts-expect-error Not sure why this fails
-	return {
-		...project,
-		permalink: normalizeUrl([permalink]),
-	};
+    const permalink = `/${joinUrl(urlPrefix, packageSlug)}`;
+
+    if (project.children) {
+        // eslint-disable-next-line no-param-reassign
+        project.children = project.children.map((child) => {
+            migrateToVersion0230(child);
+
+            const kindSlugPart = getKindSlug(child);
+            const childPermalink = kindSlugPart 
+                ? `${permalink}/${kindSlugPart}/${child.name}` 
+                : resolveAnchorLink(permalink, child.name);
+
+            // We need to go another level deeper and only use fragments
+            if (child.kind === ReflectionKind.Namespace && child.children) {
+                // eslint-disable-next-line no-param-reassign
+                child.children = child.children.map((grandChild) => ({
+                    ...grandChild,
+                    permalink: normalizeUrl([resolveAnchorLink(childPermalink, grandChild.name)]),
+                }));
+            }
+
+            return {
+                ...child,
+                permalink: normalizeUrl([childPermalink]),
+            };
+        });
+    }
+
+    // @ts-expect-error Not sure why this fails
+    return {
+        ...project,
+        permalink: normalizeUrl([permalink]),
+    };
 }
 
 function mergeReflections(base: TSDDeclarationReflection, next: TSDDeclarationReflection) {

api/docusaurus-plugin/src/utils/links.ts

@@ -8,3 +8,20 @@ export function removeScopes(text: string, scopes: string[]): string {
 		text,
 	);
 }
+
+export function resolveAnchorLink(base: string, anchor?: string): string {
+    let fullPath = base || '';
+    if (anchor) {
+        fullPath = fullPath ? `${fullPath}#${anchor}` : `#${anchor}`;
+    }
+
+    const parts = fullPath.split('#');
+    if (parts.length <= 2) {
+        return fullPath;
+    }
+
+    const urlPath = parts[0];
+    const combinedAnchors = parts.slice(1).join('.');
+
+    return `${urlPath}#${combinedAnchors}`;
+}

api/docusaurus-plugin/src/utils/markdown.ts

@@ -1,5 +1,6 @@
 import type { PropVersionMetadata } from '@docusaurus/plugin-content-docs';
 import type { TSDDeclarationReflectionMap } from '../types';
+import { resolveAnchorLink } from './links';
 
 function splitLinkText(text: string): { caption: string; target: string } {
 	let splitIndex = text.indexOf('|');
@@ -39,20 +40,20 @@ function findReflectionWithMatchingTarget(
 }
 
 function replaceApiLinks(
-	reflections: TSDDeclarationReflectionMap,
+    reflections: TSDDeclarationReflectionMap,
 ): (match: string, tagName: string, content: string) => string {
-	return (match: string, tagName: string, content: string) => {
-		const { caption, target } = splitLinkText(content);
-		const [symbol, member] = target.split('.');
-		const reflection = findReflectionWithMatchingTarget(reflections, symbol, member);
-		const label = tagName === 'linkcode' ? `\`${caption}\`` : caption;
+    return (match: string, tagName: string, content: string) => {
+        const { caption, target } = splitLinkText(content);
+        const [symbol, member] = target.split('.');
+        const reflection = findReflectionWithMatchingTarget(reflections, symbol, member);
+        const label = tagName === 'linkcode' ? `\`${caption}\`` : caption;
 
-		if (!reflection?.permalink) {
-			return label;
-		}
+        if (!reflection?.permalink) {
+            return label;
+        }
 
-		return `[${label}](${reflection.permalink}${member ? `#${member}` : ''})`;
-	};
+        return `[${label}](${resolveAnchorLink(reflection.permalink, member)})`;
+    };
 }
 
 function replaceDocLinks(