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

Clone the reproduction repository.
npm ci
npm run docs-custom-theme
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.

Environment

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!

Your Name

Your Comment

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

YOU MAY BE INTERESTED

Issue Title	Created Date	Updated Date