How to efficiently fix unresolved links in generated docs?

[litvix-whale]

Hello!

When generating documentation with TypeDoc, We get many warnings like:
[warning] Failed to resolve link to "ResourceList" in document README

However, "ResourceList" is exported from src/index.ts and has a JSDoc comment like:

/**
 * Displays a list of resources with optional filtering and table display modes.
 *
 * @param props - {@link ResourceListProps}
 */
export function ResourceList({ ... }: ResourceListProps) { ... }

Our typedoc.json looks like this:

{
    "entryPoints": ["./src", "./server"],
    "out": "packages/docusaurus/docs",
    "plugin": ["typedoc-plugin-markdown", "./tools/custom-typedoc-theme/custom-typedoc-theme.mjs"],
    "theme": "custom-markdown-theme",
    "excludePrivate": true,
    "excludeProtected": true,
    "suppressCommentWarningsInDeclarationFiles": true,
    "projectDocuments": ["./docs/**/*.md", "./README.md"],
    "hideBreadcrumbs": true,
    "entryPointStrategy": "expand",
    "excludeNotDocumented": true,
    "readme": "none"
}

Why does TypeDoc fail to resolve the link to ResourceList in the README, even though it is exported and documented? Is there something wrong with our configuration or the way we reference the symbol in markdown?

What is the recommended way to efficiently fix or manage these unresolved links in documentation?

TypeDoc version: 0.27.6
Node.js version: 22.14.0

Thank you!

[Gerrit0]

Link resolution outside of TS files can't use the TS language server to resolve symbols, so it falls back to TypeDoc's declaration references implementation.

The way this works is effectively splitting the link by . and trying to find each components of that path in children of the current scope. For the README, you are starting from the root scope, so need to specify the full path to the reflection. In this case, because you have more than one entry point, you'll need to specify the entry point as a part of that link. This probably means {@link "src/index".ResourceList}, but might be something else if you're using @module... the easiest way to tell is to look at the generated file path.

For example, in TypeDoc's docs:

https://typedoc.org/api/interfaces/JSONOutput.ReflectionVariantMap.html

Tells me I can probably link to this with {@link JSONOutput.ReflectionVariantMap}. It isn't perfect as / will end up replaced with _ in the URLs, looking at the breadcrumbs at the top of the page can also be helpful.