feat: Support for reference tag [#153]

packages/plugin/src/components/Comment.tsx

@@ -37,6 +37,9 @@ export function Comment({ comment, root, hideTags = [] }: CommentProps) {
 		return null;
 	}
 
+	// Hide custom tags.
+	hideTags.push('@reference');
+
 	const blockTags =
 		comment.blockTags?.filter((tag) => {
 			if (hideTags.includes(tag.tag)) {

packages/plugin/src/plugin/data.ts

@@ -1,7 +1,7 @@
 import fs from 'fs';
 import path from 'path';
 import * as TypeDoc from 'typedoc';
-import { JSONOutput, ReflectionKind } from 'typedoc';
+import { type InlineTagDisplayPart, type JSONOutput, ReflectionKind } from 'typedoc'
 import ts from 'typescript';
 import { normalizeUrl } from '@docusaurus/utils';
 import type {
@@ -110,7 +110,42 @@ export function createReflectionMap(
 ): TSDDeclarationReflectionMap {
 	const map: TSDDeclarationReflectionMap = {};
 
+	// eslint-disable-next-line complexity
 	items.forEach((item) => {
+		// Add @reference categories to reflection.
+		const referenceCategories: Record<string, { title: string; children: number[] }> = {};
+		for (const tag of item.comment?.blockTags ?? []) {
+			if (tag.tag === '@reference' && tag.content.length >= 2 && tag.content[0].kind === 'text') {
+				const categoryName = tag.content[0].text.trim();
+				const ref = (tag.content as InlineTagDisplayPart[]).find((t) => t.tag === '@link');
+
+				if (ref && typeof ref.target === 'number') {
+					if (!(categoryName in referenceCategories)) {
+						referenceCategories[categoryName] = { title: categoryName, children: [] };
+					}
+
+					if (!referenceCategories[categoryName].children.includes(ref.target)) {
+						referenceCategories[categoryName].children.push(ref.target);
+					}
+				}
+			}
+		}
+
+		// Update categories with reference categories.
+		if (!item.categories) {
+			// eslint-disable-next-line no-param-reassign
+			item.categories = [];
+		}
+		for (const category of Object.values(referenceCategories)) {
+			if (category.children.length > 0) {
+				const index = item.categories.findIndex((c) => c.title === category.title);
+				if (index === -1) {
+					item.categories.push(category);
+				}
+			}
+		}
+
+		// Add item.
 		map[item.id] = item;
 	});