Icons might be missing when a custom theme overrides icons member

This issue has been tracked since 2023-02-13.

Search terms

theme, icons, cache

Expected Behavior

When a custom theme overrides the icons member, the icons correctly appear on all generated pages.

Actual Behavior

TypeDoc fails to show icons on all generated pages. Compare the navigation on the right hand side of the two screenshots:

  • default theme:


  • custom theme (see the reproduction repository linked in reproduction steps):


I believe this is due to this call to clearSeenIconCache() function as it is imported from the default theme. If the custom theme overrides the icons, the icon cache will not be correctly invalidated and some generated pages might refer to icons that do not exist.

This is further confirmed by printing the order in which pages are rendered:

$ npm run docs-custom-theme

> [email protected] docs-custom-theme
> tsc && typedoc src --plugin ./dist/index.js --theme icon-override

Loaded plugin C:\dev\typedoc-custom-icons-bug\dist\index.js
warning Failed to resolve link to "DeclarationReflection.cssClasses" in comment for IconOverrideTheme.applyReflectionClasses.applyReflectionClasses
warning Failed to resolve link to "UrlMapping" in comment for IconOverrideTheme.getUrls.getUrls
Rendering modules.html
Rendering index.html
Rendering classes/IconOverrideTheme.html
Rendering classes/IconOverrideThemeContext.html
Rendering functions/load.html
Documentation generated at ./docs

The icons on modules.html page are all shown correctly:


But the class icon on classes/IconOverrideTheme.html is not:


as it attempts to use (<use href="#icon-128-path"></use>) an element that does not exist on the page.

Steps to reproduce the bug

  1. Clone the reproduction repository.
  2. npm ci
  3. npm run docs-custom-theme
  4. This will generate documentation into docs directory.

The custom theme's icon.tsx is copied straight from the default theme's icon.tsx file, but the icons are filled in to make the distinction between the default and custom themes clearer.

For ease of comparison, npm run docs command will generate documentation using the default theme.


  • Typedoc version: 0.23.24
  • TypeScript version: 4.9.5
  • Node.js version: 18.13.0
  • OS: Windows 10
Gerrit0 wrote this answer on 2023-02-18

There's a part of me that wants to just kill the cache. Icons aren't the majority of the page size, and gzip is good.

ejuda wrote this answer on 2023-03-05

We use TypeDoc to generate documentation for a big TypeScript codebase, and getting rid of the cache would increase the size of our docs by a factor of 1.75. gzip does solve this issue when serving the webpage, but the proposed change would have consequences for our storage requirements. There are ways of working around it in our custom theme (e.g. using an icon file, like in TypeDoc 0.22), but just wanted to feed this back!

Gerrit0 wrote this answer on 2023-03-05

Finally got around to actually looking at your repro... yeah. That's not going to work. If you are going to overwrite icons, you need to handle clearing the cache yourself. I think this is working as intended. Themes which want to overwrite the icons template and still have caching will have to clear the cache themselves.

You could toss a _icons.clearSeenIconCache() into your custom render method, or have the context register a listener for when a page is rendered to clear it... but this is theme implementation problem, not a TypeDoc problem.

ejuda wrote this answer on 2023-03-05

I see, I initially thought that cache clearing would be a feature for themes deriving from default theme, but I understand the different approach. 😊 We worked around it by listening to Renderer.EVENT_END_PAGE, so no issues there. Thanks for looking at this anyway!

More Details About Repo
Owner Name TypeStrong
Repo Name typedoc
Full Name TypeStrong/typedoc
Language TypeScript
Created Date 2014-05-24
Updated Date 2023-03-19
Star Count 6487
Watcher Count 68
Fork Count 639
Issue Count 48


Issue Title Created Date Updated Date