Inline scripts in page content run before preceding external scripts on instant navigation and lose their attributes

[michaelweinold]

Context

We migrated the documentation of our tool from
Material for MkDocs to Zensical. The homepage embeds an interactive Plotly figure generated at build time by markdown-exec's documented pattern (fig.to_html(full_html=False, include_plotlyjs="cdn")), which emits an external <script src="https://cdn.plot.ly/..."> followed by an inline <script>Plotly.newPlot(...)</script> in the page content. After the migration the figure was reported as "gone" — it turned out to render fine on hard loads but to disappear whenever the page was reached through instant navigation.

Bug description

[thank you to Claude for helping me write this up]

When instant navigation injects a new page, author scripts inside the content container are re-evaluated by cloning each <script> element (inject() in src/assets/javascripts/integrations/instant/index.ts). Two defects in that block break common content patterns:

1. Execution order is not preserved. The script list is piped through concat(...).pipe(switchMap(...)). Because the list is emitted synchronously, switchMap unsubscribes the script.onload completion of an external (src) script the moment the next element is emitted — and a dynamically inserted script loads asynchronously anyway. A following inline script therefore always executes before a preceding external script has loaded (deterministically so, since the external script cannot run until the current task yields). For the Plotly pattern above this throws ReferenceError: Plotly is not defined and leaves an empty figure.

2. Inline clones lose all attributes. The src branch copies attributes onto the clone, but the inline branch copies only textContent. Inert data payloads such as <script type="application/json">…</script> are therefore re-injected as plain executable scripts: the JSON is parsed as JavaScript and throws right inside inject() (Failed to execute 'replaceWith' on 'Element': Unexpected token ':'), and selectors like script[type="application/json"] no longer match after the swap.

Both defects only manifest on instant navigation; a hard load of the same page behaves correctly, which makes the breakage easy to miss and confusing to reproduce ("sometimes the chart is gone").

Related links

• Report a bug
• Instant navigation
• Customization – Additional JavaScript / document$
• Instant navigation breaks MathJax on anchor link #93 (MathJax broken by instant navigation), glightbox extension does not re-initialize on navigation.instant transitions #150 and
  GLightbox is not re-bound after instant navigation — images open the raw URL instead of a lightbox #157 (GLightbox not re-bound after instant navigation) — related
  instant-navigation re-initialization issues
• Support for plotly (mkdocs-plotly) zensical#455 / Support mkdocs-plotly plugin functionality backlog#113 (Plotly plugin support request)

Reproduction

zensical-repro.zip

Steps to reproduce

1. Unzip the attached reproduction (the three files above), pip install zensical==0.0.50 (zensical-ui 0.0.22), zensical serve.
2. Open http://localhost:8000/chart/ directly (hard load): the Plotly chart renders, console is clean.
3. Open http://localhost:8000/ and click Chart in the navigation (instant navigation): the chart is missing and the console shows ReferenceError: Plotly is not defined (defect 1) and Failed to execute 'replaceWith' on 'Element': Unexpected token ':' (defect 2, from the application/json script losing its type).

Browser

No response

Before submitting

• I have read and followed the bug reporting guidelines.
• I have attached links to the documentation, and possibly related issues.
• I assure that I have removed all customizations before submitting this bug report.
• I have attached a .zip file with a minimal reproduction.

[squidfunk]

Thanks for reporting. Moving to UI repository.

We migrated the documentation of our tool from Material for MkDocs to Zensical.

For our understanding: is this a regression, meaning it worked in Material for MkDocs but doesn't in Zensical?

[michaelweinold]

@squidfunk , we never used the instant navigation setting with Material - but it seems that the current Material theme is equally broken.

I rebuilt our pre-migration site with mkdocs-material 9.7.6 and added a site_url. The figures are fine on hard load, but gone after instant navigation with Plotly not defined - identical to Zensical. Looking through the commit history, Claude let me know that:

through Material 9.1.x, the pipeline used concatMap with a per-script onload wait (correct, document-order semantics, dating to 2021). The instant-loading refactor 80d9603 (#5032, first shipped in 9.2.0, March 2023) replaced it with switchMap, which discards the wait.

[squidfunk]

Thanks for checking! We'll investigate. However, please note that the priority to fix this is currently not very high, since it's a bug that also exists in Material for MkDocs, and the fact that it was just reported with Material for MkDocs having 80k dependent projects indicates that this seems to be an edge case. We'll look into it when we work on instant navigation again.

In the meantime, please just disable instant navigation as you did with Material for MkDocs ☺️