Addons failing on hydrated pages

[LecrisUT]

Details

I have enabled both Addons and Flyout enabled in the project dashboard, but the menu seems to not reliably show up for me. It pops up for a millisecond and then dissapears. I am not sure if it requires rebuilding when you enable/disable this feature, but I have tried it on a few other builds with similar results.

Potential caveat, I am using noscript, but I have enabled all javascripts links and I have tested in incognito with noscript off, and the same results show up. I did not check that thoroughly when re-building the builds though.

• The build uses mystmd to generate the static site.
• The build has various other linking issues related to redirect: Clean file URLs as well readthedocs.org#11220
• Read the Docs project URL: https://beta.readthedocs.org/dashboard/mystmd-temp/

[humitos]

Thanks for opening this issue. I'm transferring it to the addons repository since it fits better there.

I am not sure if it requires rebuilding when you enable/disable this feature, but I have tried it on a few other builds with similar results.

No, it does not require re-building.

It pops up for a millisecond and then dissapears.

I'm experiencing the same behavior at https://mystmd-temp.readthedocs.io/latest/

It seems the page is failing with some react issues in the console. Also, I found the DOM is re-written completely in some weird way after loading the page completely, because there is a lot of things removed from it after loading. It seems that removes the addons and all the other Read the Docs features.

It seems this is an issue of that particular theme and you should report it there. Keep us posted, please.

[LecrisUT]

Upstream PR where the RTD is implemented. jupyter-book/mystmd#982

Do you think it's an issue with the theme or the site generator? For debugging, we could try different themes, do you have a suggestion on which ones to try? I'm thinking of rtd theme (nvm, it's not available) and then book?

(Also to avoid confusion for other readers this is mystmd and not myst-parser + sphinx)

[humitos]

Do you think it's an issue with the theme or the site generator?

I'm not sure how mystmd works and how its themes are implemented --so I don't have a suggestion here. However, its homepage has the same React issue, and its DOM is also completely rewritten in some weird way. Take a look at the JS console while loading https://mystmd.org/

[LecrisUT]

Ok, I've opened an upstream issue. I have tried to change the theme, but it doesn't use the sphinx theme, and it is already on book theme, so there is no change that can be done right now.

[LecrisUT]

Got some feedback. We are suspecting it's related to react/hydrate: https://react.dev/reference/react-dom/client/hydrateRoot

React will attach to the HTML that exists inside the domNode, and take over managing the DOM inside it. An app fully built with React will usually only have one hydrateRoot call with its root component.

Also relevant comment: jupyter-book/mystmd#188 (comment)

This limitation is currently in Remix (we are building a web application, and then making a static html export of it).

[humitos]

In jupyter-book/mystmd#997 (comment) I noted that this hydrated issue may not be 100% related to Read the Docs since it happens on their home page which is not hosted in our platform as well.

[LecrisUT]

Indeed, but it actually doesn't happen to me. In more investigation, I've seen that this is an issue with anything that injects contents in pages, and most probably in your case it's to do with browser plugins? The issue with the hydration is that it requires the content on the server to be identical with that on the client, since it takes over and re-renders all the elements under its hydrated node.

But, it seems that the hydration can be limited to a sub-node, so if all the page content can be wrapped in a container node, so that the hydration is not on the html root, in principle, it should allow for at least the flyout compatibility

[humitos]

I've seen that this is an issue with anything that injects contents in pages, and most probably in your case it's to do with browser plugins? The issue with the hydration is that it requires the content on the server to be identical with that on the client, since it takes over and re-renders all the elements under its hydrated node.

😞

Do you know what is hydrated useful for? I'm not sure to understand its goal. Does it make sense to disable that feature?

But, it seems that the hydration can be limited to a sub-node, so if all the page content can be wrapped in a container node, so that the hydration is not on the html root, in principle, it should allow for at least the flyout compatibility

This could be a good intermediate solution --not only of Read the Docs addons, but for any user that has plugins installed in their browser.

[LecrisUT]

Do you know what is hydrated useful for? I'm not sure to understand its goal. Does it make sense to disable that feature?

Unfortunately that seems to be a staple of react and its their way of getting interactive UI elements. This also means that you will probably encounter similar feedback when another react based projects wants to integrate. The issue is that since the html content is not templatized, but instead it's generated from the json/js data, I don't see a way around the react backend right now.

A related issue could be the static-site-generation, since right now it is done very naively on mystmd by simply downloading the pages from a temporary server. This is a limitation that remix backend has. I have found that next.js does have a ssg, but I did not look deeply into how it works. If it can do without hydration, or at least make it more intelligent (maybe only affecting tagged elements), than maybe there is some hope for a simpler integration.