Issues with custom themes (0.22)

matteobruni commented 2 years ago

Search terms

custom themes

Expected Behavior

Custom theme output should be the same as the default when overridden
JSX.Raw should write correctly the HTML in Hooks
Google Analytics should write a valid Javascript

Actual Behavior

Today I was migrating from 0.21.x to 0.22.x, and my custom theme (2 additional scripts, nothing more) needs a migration too.

I started from a sample theme found on GitHub (this) but it didn't worked. I tried checking the documentation here but also this wasn't working as expected.

Here are the errors found:

The sample theme had an invalid docs folder when tested. The output docs folder was containing only two .html files. The default theme that was overridden generates a lot of additional files, .css and .js files included.
I tried overriding the analytics property like in the documentation linked above, the issues were the same as the custom theme, but I noticed that also Google Analytics had issues since here and below all the ' characters will be replaced by the engine with the corresponding HTML escape value.
I tried the new hooks, Google Analytics had the same issue (so maybe it's in the engine) and when using JSX.Raw like described in the documentation linked above the parent <script> tag was empty.

Steps to reproduce the bug

For testing the theme output you can just clone this repository

To see the invalid docs output these are the steps:

cd typedoc-test-theme
yarn or npm i
yarn build or npm run build
cd demo
yarn or npm i
yarn build or npm run build

The demo/docs folder will have only two html files instead of the full output.

For testing the hooks output follow the steps described here in the hooks section.

Google Analytics seems broken in any test I've made, I've disabled it for now in my tsconfig.json and used my custom theme to readd it manually.

Using the hooks I've found a workaround that can be seen here

You can also find more informations in the issue #1785, the required tags were the fix in that case.

Environment

Typedoc version: 0.22.8
TypeScript version: 4.4.4
Node.js version: 16.13.0
OS: macOS Big Sur 11.6.1

omar0404 commented 2 years ago

same , it results in empty script !!

Gerrit0 commented 2 years ago

That theme is set up incorrectly, see https://github.com/TypeStrong/typedoc/issues/1741#issuecomment-945151479, because there are multiple installs of typedoc, as far as the rendering TypeDoc is concerned, the theme that extends the default theme is not inherited from the default theme and therefore shouldn't have the default assets created. Given that this is the third time that I know of that this has tripped people up... it's probably time I added a hack to detect it and print lots of warnings.

The Google Analytics issue is definitely real - I totally missed this since I don't use it anywhere... easy fix at least, though looking at Google's page, the JS we're injecting is old... a change for the next minor version I think, since the new code only requires an ID, no site.

Your hook workaround looks broken to me. You don't use the JSX.Raw component at all, instead setting a "html" attribute on <script>, which will generate <script html="...."></script>. It should be <script><JSX.Raw html={ga} /></script>

Gerrit0 commented 2 years ago

I just published 0.22.9, which fixes the google analytics issue, and adds a warning that will try to tell you if you're doing something that will cause your theme to break. I've also created https://github.com/Gerrit0/typedoc-custom-theme-demo, which shows a working example of hooks + custom themes.

matteobruni commented 2 years ago

@Gerrit0 I've updated to TypeDoc 0.22.9 but the docs output is not good (only two html files).

You can see it here: https://github.com/matteobruni/tsparticles/tree/72983dad4686ca84381b636642555a8073928064

engine folder uses typedoc
utils/typedoc-theme creates the theme

Both uses 0.22.9 version, both has it as a dev dependency, the theme package.json has also the peerDependency. It's loaded with the typedoc-theme but when I'm building the documentation this warning appears after the loading:

Info: Loaded plugin tsparticles-typedoc-theme
Warning: TypeDoc has been loaded multiple times. This is commonly caused by plugins which have their own installation of TypeDoc. This will likely break things.

I've not checked yet if the GA code is fine, or other things, since it's not working. I tried checking your repository but I don't find anything useful about this error since the dependencies are the same.

Gerrit0 commented 2 years ago

Well, that warning at least confirms that what I thought was going wrong is what is going wrong. It doesn't matter if you're loading the same version of TypeDoc multiple times. It's still a problem to load it multiple times, so my initial comment still stands. If you're going to have a theme and a use of that theme in a single repo, you need to figure out some way to have only a single install of TypeDoc. Lerna might have options that make this possible, not sure...

matteobruni commented 2 years ago

I've tried with local path like this:

"tsparticles-typedoc-theme": "file:../utils/typedoc-theme/dist",

and it's working fine. I'd like to know what is the difference, in this case the package is copied, with Lerna the package is a link to the folder.

I was testing also hooks for achieve the same thing without a full theme but it's not working.

You can see the code here: https://github.com/matteobruni/tsparticles/blob/typedoc-test-theme-2/utils/typedoc-theme/src/index.tsx

It uses a hook to body.end but I can't find the code in the page.

cyberwombat commented 2 years ago

@matteobruni thanks that was the trick. Evidently its not possible to develop a custom theme without either npm packaging it or doing your trick which is less painful. I don't use Lerna but yarn link fails with same issue.

Gerrit0 commented 2 years ago

in this case the package is copied

This is the relevant piece - the package is copied... but not the package's node_modules, so it ends up using the same installation of TypeDoc as what is actually being executed by the package using the theme. With a link, Node walks up directories after resolving the link, so ends up using the plugin's installation of TypeDoc instead of the one it ought to be using.

There's nothing that can really be done by TypeDoc to make this less of a problem as far as I know.

TypeStrong / typedoc