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: