Newest Backstage version does not trigger the hook

[mstrangfeld]

I have noticed that the Mermaid code blocks are not being rendered with version v1.22.1 & React 18. A full refresh will make them work, but if you navigate to the documentation page by following the links of the catalog, the hook does not seem to trigger and the code blocks are not replaced.

[johanneswuerbach]

I can't replicate this in our backstage with v1.22.2, but I published a new version with updated dependencies https://github.com/johanneswuerbach/backstage-plugin-techdocs-addon-mermaid/releases/tag/v0.11.0. Could you test whether this resolves your issue?

[mstrangfeld]

Thank you very much for the effort! Unfortunately, this issue still persists. If I have some spare time in the future, I will try to further debug the problem.

[johanhammar]

I'm also seeing this on Backstage 1.23.4. Sometimes I see the rendered graph flash before outputting the raw code again. Haven't figured out what is causing this, anything I can do to investigate further?

[johanhammar]

It seems to work when I navigate to the documentation from the Docs sidebar item but not when coming from the component itself. Also see this thread in Discord https://discord.com/channels/687207715902193673/714754240933003266/1212769278927966218

[johanhammar]

@mstrangfeld Did you find a solution or workaround?

[johanhammar]

I've done some more digging. It seems like when navigating to the docs from the component that the mermaid addon is called twice whereas when navigating via the Docs sidebar item it is only called once and the graph is rendered. Se below for some basic console.log()-debugging

From the Docs sidebar-item

>>> MermaidAddon Mermaid.tsx:71
>>> useEffect - highlightTable Mermaid.tsx:80
>>> useEffect - highlightDiv Mermaid.tsx:108
>>> isMermaidCode() 3 hooks.ts:21
>>> makeDiagram() Mermaid.tsx:50
>>> selectConfig() Mermaid.tsx:28
>>> useEffect - mermaidPreBlock Mermaid.tsx:142

From the component itself

>>> MermaidAddon Mermaid.tsx:71
>>> useEffect - highlightTable Mermaid.tsx:80
>>> useEffect - highlightDiv Mermaid.tsx:108
>>> isMermaidCode() 3 hooks.ts:21
>>> makeDiagram() Mermaid.tsx:50
>>> selectConfig() Mermaid.tsx:28
>>> useEffect - mermaidPreBlock Mermaid.tsx:142
>>> MermaidAddon Mermaid.tsx:71
>>> useEffect - highlightTable Mermaid.tsx:80
>>> useEffect - highlightDiv Mermaid.tsx:108
>>> isMermaidCode() 2 hooks.ts:21
>>> useEffect - mermaidPreBlock Mermaid.tsx:142

Any idea or advice how to continue troubleshooting?

[johanneswuerbach]

@johanhammar I sadly still can't reproduce this locally. How did you add the addon? Is there a different configuration between those pages?

[johanneswuerbach]

Looking further, I also noticed some re-rendering on the component page itself. This seems to be triggered outside the addon, so can't really be influenced, but shouldn't break the rendering.

@johanhammar could you share a few more details about your setup, is this breaking for all pages with mermaid diagrams or mainly on specific pages? Some diagram types are using an async rendered under the hood, maybe this clashes with the re-rendering somehow 🤔

Would it be possible to the share the markdown of a page that shows this behaviour? (Feel free to remove everything the isn't relevant).

[johanhammar]

Hi! I'll try to summarize below

The problem only occurs when navigating via the component to the documentation. Not when navigating via the Docs-menu item in the left menu.

It seems that it's mainly Firefox that is affected (I do think it happened in chromium based browsers when I wrote my first comment but doesn't seem to be the case anymore).

I've implemented the addon both by including the dependency (in package.json) and by cloning the repository directly in the plugins folder

I've seen the problem occur for atleast three different diagram types: graph, sequenceDiagram and timeline.

The simplest diagram that does not display correctly is this example:

```mermaid graph TD; A-->B; A-->C; B-->D; C-->D; ```

And the markdown is really simple

# Mermaid

## Graph

```mermaid graph TD; A-->B; A-->C; B-->D; C-->D; ```

I do see it flicker though which sounds like som clash with the re-rendering.

So, this might be a Firefox only problem. Hope this helps, please let me know if I do anything more to help out

[johanneswuerbach]

Reported an upstream issue https://github.com/backstage/backstage/issues/24270 🤞

[eamodeorubio]

We have the same problem with Backstage 1.24.2 but with Google Chrome instead of Firefox.

As described by @johanhammar

• If user goes directly to the doc page containing the mermaid, it is rendered
• If the user was in another page inside the same docs, and then navigates using side bard to the one with the mermaid, it is not rendered

[johanhammar]

This problem might have been fixed in some newer Backstage release. It seems to work again using Backstage 1.34.0 and Backstage TechDocs Mermaid Addon 0.14.1

@johanneswuerbach Can you verify on your side?

[johanneswuerbach]

Verified 🎉