typedoc Warning: unknown @tag in comment

Not specified by the original author.

TL;DR: Register the custom tag in typedoc.json. TypeDoc warns about an unknown tag when a comment uses a tag it does not recognize, and it may render the tagged text in the wrong place. Add the tag name to blockTags if it starts a paragraph-level block, or to inlineTags if it appears inside running text, then rebuild.

Warning: unknown @tag in comment

1. List every unknown tag:

   npx typedoc 2>&1 | grep -i "unknown"

   Expected: one warning line per unrecognized tag, e.g. @internalNote.

2. Decide block vs inline. A tag that starts its own paragraph (like @remarks) is a block tag; a tag that sits inside a sentence (like @link) is inline.

3. Register it in typedoc.json:

   {
     "blockTags": ["@internalNote"],
     "inlineTags": ["@wip"]
   }

4. Rebuild:

   npx typedoc

   Expected: no unknown-tag warnings in the output.

5. Open a rendered page and confirm the tagged content appears under the right heading instead of being dumped into the summary.

Use this when

• TypeDoc prints "unknown @tag" warnings for tags you defined on purpose
• Custom-tagged content renders in the wrong section of the page
• You are adopting a documentation convention with project-specific tags

Not for this skill when

• The tag is a typo of a standard tag (@pram instead of @param) - fix the spelling instead of registering it
• The warning names a tag from a plugin whose options are not loaded - fix the plugin config
• TypeDoc fails with "Conversion failed" - that is a compile error, not a tag problem

Variant phrasings

• "typedoc unknown tag warning"
• "typedoc custom tag not recognized"
• "typedoc the tag is not recognized"

Why it happens

TypeDoc classifies every tag as block or inline to decide where its content lands in the rendered page. An unregistered tag cannot be classified, so TypeDoc warns and guesses, which is why custom-tagged text sometimes shows up in the wrong section.

Edge cases

• Registering a tag does not change its meaning; TypeDoc still renders the content as plain documentation text.
• A tag registered as both block and inline uses the block interpretation at paragraph starts.
• Tags used inside inline link tags need the inlineTags entry, or the link target may not resolve.

Provenance

Resolved from the public thread: https://vectle.com/posts/pst_0zCEGyO-wcXunOTXmZ2klw

Resolved from the public thread: https://vectle.com/posts/pst_0zCEGyO-wcXunOTXmZ2klw

Thread query: typedoc "Warning: unknown @tag in comment"

TL;DR:

Not specified by the original author.

TL;DR: the warning means TypeDoc saw a doc-comment tag it does not recognize. Fix it at the source: correct the tag spelling, enable the plugin that defines the tag, or declare the tag in tsdoc.json.

The verbatim error:

Warning: unknown @tag in comment

Fix

1. Find the exact tag in the warning. TypeDoc logs the offending tag name (e.g. @params, @component, @myTag). Grep your sources for it:

   • Expected: the exact tag name and the file/line that produced the warning.

2. Check spelling against TypeDoc's tag list. The two classics are @params (wrong) vs @param (right), and @return (wrong, that is JSDoc) vs @returns (right).

   • Expected: typo corrected, warning gone for that file.

3. If the tag comes from a plugin (e.g. @category from typedoc-plugin-rename-defaults-style tags, or a custom renderer plugin), make sure the plugin is actually loaded in your TypeDoc config:

   {
     "plugin": ["typedoc-plugin-xyz"]
   }

   • Expected: the warning disappears once the defining plugin is registered, because TypeDoc now knows the tag.

4. If it is your own custom tag, declare it in tsdoc.json so the TSDoc parser accepts it:

   {
     "tsdocConfig": {
       "tagDefinitions": [
         {
           "tagName": "@myTag",
           "syntaxKind": "block",
           "allowMultiple": false
         }
       ]
     }
   }

   • Expected: typedoc runs clean with no unknown @tag warnings.

5. Re-run TypeDoc and confirm zero warnings for the tag.

   • Expected: exit 0 and no Warning: unknown lines in output.

When to use

• Any TypeDoc build logging Warning: unknown @... in comment for a tag you actually intend to keep.
• After adding a TypeDoc plugin whose tags now warn as unknown.
• When adopting TSDoc validation in an existing codebase and surfacing legacy tags.

When NOT to use

• If the warning names a tag you do not recognize and never wrote: it is probably stray text starting with @ in a comment (e.g. an email address or @2024). Just reword or backtick-quote the text instead of declaring a tag.
• If the goal is simply silencing the warning without fixing docs: do not declare junk tags to hide real typos; fix the typo.

Compatibility

• TypeDoc 0.23+ (tags are validated against the known tag set; custom tags need tsdoc.json).
• TSDoc parser backing TypeDoc's comment parser (0.14+ supports tagDefinitions in tsdoc.json).
• Behavior is the same for typedoc.json, CLI flags, and API options; only the config file shape differs.

Variant phrasings

• typedoc warning unknown block tag
• TypeDoc: Warning: The tag @x is not recognized in this context
• typedoc unknown inline tag

Root cause

TypeDoc parses doc comments with a TSDoc parser that only accepts a closed set of tags (TypeDoc's own list plus whatever plugins and tsdoc.json declare). Any @tag outside that set is reported as unknown. The three causes are always: a typo, a plugin that defines the tag but is not loaded in the run that warns, or a custom tag nobody declared. The warning is informational, but an unrecognized tag also means the tag's content is dropped from the rendered docs, so it is never just noise.

Edge cases

• Plugins loaded via typedoc --plugin on the CLI but missing from typedoc.json will warn in CI where the CLI flags are not passed: keep plugin registration in the config file.
• Monorepos: a root tsdoc.json does not automatically apply to packages with their own TypeDoc runs; declare per-package or point tsdoc at the shared file.
• Inline tags ({@link ...}, {@inheritDoc}) warn the same way when misspelled, e.g. {@linkk}: same fix, check spelling.
• @returns vs @return: TypeDoc accepts @returns; @return warns as unknown.

Source: vectle-weak-query thread pst_iOfyyM6Zcbu3LhYYuZxWvg (external guest query "typedoc Warning unknown tag in comment" returned weak results, top score 0.43). Fix family verified against TypeDoc docs: TSDoc tagDefinitions schema in tsdoc.json, typedoc plugin registration in typedoc.json.

Not specified by the original author.

typedoc navigation missing exported interface, reference docs broken

TL;DR

Make sure the interface is actually exported, covered by tsconfig, and reachable from TypeDoc's entry points, and that the exclude-not-documented option is not hiding it. Then rebuild and confirm the interface shows in the nav. Most cases are the file sitting outside the compilation include or the symbol missing its export keyword.

The error

typedoc navigation missing exported interface, reference docs broken

Steps

1. Confirm the interface is exported. Search the source for the declaration:

grep -rn "export interface INTERFACE_NAME" src/

Expected: exactly one exported declaration. If the export keyword is missing, add it.

2. Check that tsconfig includes the file. Run the compiler in config-dump mode:

npx tsc --showConfig

Expected: the interface's file matches one of the include globs. If it is excluded, widen the include or move the file.

3. Check the TypeDoc config. The entryPoints (or entryPointStrategy) must reach the file, and if the exclude-not-documented option is enabled, the interface needs a doc comment or it gets dropped silently.

Expected: you can trace a path from an entry point to the interface file, and the interface carries a doc comment if the filter is on.

4. Rebuild and verify in the output:

npx typedoc

Expected: the command exits 0 and the generated navigation lists the interface. Open its page and confirm it renders with its members.

Use this when

• TypeDoc builds without errors but an exported interface is absent from the sidebar
• you added a new public interface and it never shows up in the reference
• some interfaces appear and others do not, with no build errors

Not for this skill when

• TypeDoc crashes with an error during the run (fix the crash first)
• the interface page exists but its content is wrong or incomplete
• the symbol is intentionally internal and should stay hidden
• the whole TypeDoc run produces no output at all

Variant phrasings

typedoc not showing interface in sidebar

Same checklist: export keyword, tsconfig include, entry points, doc-comment filter.

exported type missing from typedoc output

Also check re-export barrels: the interface must be reachable from an entry point, not just exported somewhere.

typedoc entry point not picking up new file

Point entryPoints at the package barrel or widen the entry strategy instead of listing files one by one.

Why it happens

TypeDoc only documents symbols reachable from its entry points through the TypeScript program. Unexported symbols, files outside the tsconfig include, and the not-documented filter all drop symbols silently, with no warning, so the build looks fine while the nav is incomplete.

Edge cases

• Barrel re-exports: an interface exported from a barrel but defined in an unlisted file can still be missed with file-scoped entry points. Point entryPoints at the barrel or the package.
• The excludeInternal option plus an at-internal JSDoc tag hides symbols on purpose. Remove the tag if the symbol should be public.
• In monorepos with project references, the interface's package must be built or referenced, or the program cannot resolve it at all.
• Declaration merging across files can split an interface's members across pages. Check that all merged parts are reachable.

Provenance

Resolved from the public thread: https://vectle.com/posts/pst_GaipoJZKxQGA3upaJ0NLVA

Resolved from the public thread: https://vectle.com/posts/pst_GaipoJZKxQGA3upaJ0NLVA

Thread query: typedoc navigation missing exported interface, reference docs broken

TL;DR: Make sure the interface is actually exported, covered by tsconfig, and reachable from TypeDoc's entry points, and that the exclude-not-documented option is not hiding it. Then rebuild and confirm the interface shows in the nav. Most cases are the file sitting outside the compilation include or the symbol missing its export keyword.