Rendering Mermaid graph after navigation

[David-Klemenc]

Opening Task.html documentation and then navigating to the Supervisor.html docs via the sidebar does not trigger mermaid and therefore the mermaid graph is not visible - refreshing the page will trigger mermaid and render the graph:

To display the graph when navigating from the sidebar mermaid would have to be triggered. Example code that achieves this:

<script>
  function mermaidLoaded() {
    mermaid.initialize({
      startOnLoad: false,
      theme: document.body.className.includes("dark") ? "dark" : "default"
    });
    const runMermaid = () => {
      let id = 0;
      for (const codeEl of document.querySelectorAll("pre code.mermaid")) {
        const preEl = codeEl.parentElement;
        const graphDefinition = codeEl.textContent;
        const graphEl = document.createElement("div");
        const graphId = "mermaid-graph-" + id++;
        mermaid.render(graphId, graphDefinition).then(({svg, bindFunctions}) => {
          graphEl.innerHTML = svg;
          bindFunctions?.(graphEl);
          preEl.insertAdjacentElement("afterend", graphEl);
          preEl.remove();
        });
      }
    }
    const observer = new MutationObserver(runMermaid);

    // re run mermaid each time we navigate via sidebar
    observer.observe(document.querySelector("#sidebar"), {
      attributes: true,
      subtree: true,
      childList: true,
    });

    runMermaid();
  }
</script>
<script async src="https://cdn.jsdelivr.net/npm/mermaid@10.2.3/dist/mermaid.min.js" onload="mermaidLoaded();"></script>

[josevalim]

Thank you. Perhaps it would be best to not rely on the sidebar changing...

What if we introduce a new attribute called data-on-exdoc-load="..."? Then when we load the page and do the navigation, we search for all said attributes and execute their contents?

<script>
  function initMermaid() {
    mermaid.initialize({
      startOnLoad: false,
      theme: document.body.className.includes("dark") ? "dark" : "default"
    });
  }
  function loadMermaid() {
    let id = 0;
    for (const codeEl of document.querySelectorAll("pre code.mermaid")) {
      const preEl = codeEl.parentElement;
      const graphDefinition = codeEl.textContent;
      const graphEl = document.createElement("div");
      const graphId = "mermaid-graph-" + id++;
      mermaid.render(graphId, graphDefinition).then(({svg, bindFunctions}) => {
        graphEl.innerHTML = svg;
        bindFunctions?.(graphEl);
        preEl.insertAdjacentElement("afterend", graphEl);
        preEl.remove();
      });
    }
  }
</script>
<script async src="https://cdn.jsdelivr.net/npm/mermaid@10.2.3/dist/mermaid.min.js"
  onload="initMermaid();" data-on-exdoc-load="loadMermaid();"></script>

The code, according to Claude, would roughly be:

function executeScripts() {
  document.querySelectorAll('[data-on-exdoc-load]').forEach(tag => {
    const code = tag.getAttribute('data-on-exdoc-load');
    if (code) {
      eval(code);
    }
  });
}

If we are worried about eval, then the best would be ExDoc.onLoad() callback. But so far we have no public APIs.

Pinging @liamcmitchell as he may have suggestions that do not affect load time. Pinging @jonatanklosko for general JS feedback.

[jonatanklosko]

We could emit a window event like exdoc:loaded (similarly to phx:page-loading-start) and call it both on initial load and on every Swup change.

However, <script async> may load after exdoc:loaded happens, which makes it more tricky. This could be solved in code with promises or similar, but that's not exactly user-friendly. I mean something like this:

<script>
  let resolveInitialized = null;
  const initialized = new Promise((resolve, reject) => {
    resolveInitialized = resolve;
  });
  
  function initMermaid() {
    mermaid.initialize({
      startOnLoad: false,
      theme: document.body.className.includes("dark") ? "dark" : "default"
    });
    resolveInitialized();
  }
  
  window.addEventListener("exdoc:loaded", () => {
    resolveInitialized.then(() => {
      let id = 0;
      for (const codeEl of document.querySelectorAll("pre code.mermaid")) {
        const preEl = codeEl.parentElement;
        const graphDefinition = codeEl.textContent;
        const graphEl = document.createElement("div");
        const graphId = "mermaid-graph-" + id++;
        mermaid.render(graphId, graphDefinition).then(({svg, bindFunctions}) => {
          graphEl.innerHTML = svg;
          bindFunctions?.(graphEl);
          preEl.insertAdjacentElement("afterend", graphEl);
          preEl.remove();
        });
      }
    });
  });
</script>

<script async src="https://cdn.jsdelivr.net/npm/mermaid@10.2.3/dist/mermaid.min.js"
  onload="initMermaid();"></script>

[jonatanklosko]

ExDoc.onLoad(() => ...) could actually solve it. If ExDoc.onLoad is called, and the page is already loaded, we could run the callback immediately. So it would be this:

<script>
  function initMermaid() {
    mermaid.initialize({
      startOnLoad: false,
      theme: document.body.className.includes("dark") ? "dark" : "default"
    });
    
    ExDoc.onLoad(() => {
      let id = 0;
      for (const codeEl of document.querySelectorAll("pre code.mermaid")) {
        const preEl = codeEl.parentElement;
        const graphDefinition = codeEl.textContent;
        const graphEl = document.createElement("div");
        const graphId = "mermaid-graph-" + id++;
        mermaid.render(graphId, graphDefinition).then(({svg, bindFunctions}) => {
          graphEl.innerHTML = svg;
          bindFunctions?.(graphEl);
          preEl.insertAdjacentElement("afterend", graphEl);
          preEl.remove();
        });
      }
    });
  }
</script>

<script async src="https://cdn.jsdelivr.net/npm/mermaid@10.2.3/dist/mermaid.min.js"
  onload="initMermaid();"></script>

In this case if <script async> loads late, we initialize mermaid, call ExDoc.onLoad, and the callback is immediately called to render the graphs on the current page.

[jonatanklosko]

Actually, instead of async we could be using defer, so that the script is executed after HTML parsing and before DOMContentLoaded. This way inside window.addEventListener("exdoc:loaded", ...) we know that mermaid is available. Then we remove onload, but we still need to make sure init happens only once (because of Swup):

<script defer src="https://cdn.jsdelivr.net/npm/mermaid@10.2.3/dist/mermaid.min.js"></script>

<script>
  let initialized = false;
  
  window.addEventListener("exdoc:loaded", () => {
    if (!initialized) {
      mermaid.initialize({
        startOnLoad: false,
        theme: document.body.className.includes("dark") ? "dark" : "default"
      });
      initialized = true;
    }
    
    let id = 0;
    for (const codeEl of document.querySelectorAll("pre code.mermaid")) {
      const preEl = codeEl.parentElement;
      const graphDefinition = codeEl.textContent;
      const graphEl = document.createElement("div");
      const graphId = "mermaid-graph-" + id++;
      mermaid.render(graphId, graphDefinition).then(({svg, bindFunctions}) => {
        graphEl.innerHTML = svg;
        bindFunctions?.(graphEl);
        preEl.insertAdjacentElement("afterend", graphEl);
        preEl.remove();
      });
    }
  });
</script>

[David-Klemenc]

@jonatanklosko I tried the code above and the render is off:

code:

stateDiagram-v2
     [*] --> start
     start --> state_1: progress
     state_1 --> state_2: move
     state_2 --> wait_for_something: we wait
     wait_for_something --> stop: got something
     wait_for_something --> give_up: done waiting
     stop --> [*]
     give_up --> [*]

should look like:

[jonatanklosko]

@David-Klemenc all of the snippets rely on hypothetical changes to exdoc, so non of them should actually work, did other changes :)

[liamcmitchell]

The existingswup:page:view event can be used to run code on content change. No need for mutation observer.

// re run mermaid each time we navigate
window.addEventListener('swup:page:view', runMermaid)

What if we introduce a new attribute called data-on-exdoc-load="..."? Then when we load the page and do the navigation, we search for all said attributes and execute their contents?

The ex_docs scripts have no reliable way of knowing if the CDN script is loaded. Setting up callbacks needs to happen in the CDN scripts onload event as @jonatanklosko suggests here.

Actually, instead of async we could be using defer, so that the script is executed after HTML parsing and before DOMContentLoaded. This way inside window.addEventListener("exdoc:loaded", ...) we know that mermaid is available.

Agree about preferring defer but you still aren't guaranteed that mermaid is available in the exdoc:loaded callback. The mermaid script could still be loading. EDIT: corrected below, later suggestion works too

To have a single API for these scripts to do updates in, you'll need a fn like ExDoc.onLoad(() => {}) and it will need to be called from the script onload event. If the script uses defer, the API can be set up in the deferred JS bundle which will exec before the CDN script.

<script>
function initMermaid() {
  mermaid.initialize(...)
  ExDoc.onLoad(runMermaid)
}
function runMermaid() { ... }
</script>
<script defer src="https://cdn.jsdelivr.net/npm/mermaid@10.2.3/dist/mermaid.min.js" onload="initMermaid();"></script>

or without the ExDoc.onLoad:

<script>
function initMermaid() {
  mermaid.initialize(...)
  runMermaid()
  window.addEventListener('swup:page:view', runMermaid)
}
function runMermaid() { ... }
</script>
<script defer src="https://cdn.jsdelivr.net/npm/mermaid@10.2.3/dist/mermaid.min.js" onload="initMermaid();"></script>

But so far we have no public APIs.

Inline JS is a public API so adding SWUP was a breaking change 😬

I think there are potentially more issues as these init scripts are called multiple times, assuming that they will only be called once.

Also just found this issue documented on SWUP website, linking this plugin to re-enable scripts on nav: https://swup.js.org/plugins/scripts-plugin/

Could be an option without requiring any user code changes...

... or remove SWUP? 🤔

[jonatanklosko]

Agree about preferring defer but you still aren't guaranteed that mermaid is available in the exdoc:loaded callback. The mermaid script could still be loading.

To be clear, we would dispatch exdoc:loaded the first time on DOMContentLoaded, and the <script defer> is loaded and executed by that point.

[liamcmitchell]

If both are deferred, I would expect them to exec in DOM order e.g. ex_docs before CDN.

…

On Fri, 24 Jan 2025, 18:43 Jonatan Kłosko, ***@***.***> wrote: Agree about preferring defer but you still aren't guaranteed that mermaid is available in the exdoc:loaded callback. The mermaid script could still be loading. To be clear, we would dispatch exdoc:loaded the first time on DOMContentLoaded, and the <script defer> is loaded and executed by that point. — Reply to this email directly, view it on GitHub <#2068 (comment)>, or unsubscribe <https://github.com/notifications/unsubscribe-auth/AAMQBUTXEQQMJ5HOKZG2PKT2MJ3VRAVCNFSM6AAAAABVZLNPDCVHI2DSMVQWIX3LMV43OSLTON2WKQ3PNVWWK3TUHMZDMMJTGA3TCNBYGQ> . You are receiving this because you were mentioned.Message ID: ***@***.***>

[jonatanklosko]

Correct, but in ex_doc we can listen to DOMContentLoaded (which should happen after both are executed) and once that happens we dispatch exdoc:loaded.

[liamcmitchell]

Oh you're right, it waits for all deferred scripts. Thanks 🙏

…

On Fri, 24 Jan 2025, 19:13 Jonatan Kłosko, ***@***.***> wrote: Correct, but in ex_doc we can listen to DOMContentLoaded (which should happen after both are executed) and once that happens we dispatch exdoc:loaded. — Reply to this email directly, view it on GitHub <#2068 (comment)>, or unsubscribe <https://github.com/notifications/unsubscribe-auth/AAMQBUWCTV76B4S2JY4JQHD2MJ7GLAVCNFSM6AAAAABVZLNPDCVHI2DSMVQWIX3LMV43OSLTON2WKQ3PNVWWK3TUHMZDMMJTGEZDANZZGI> . You are receiving this because you were mentioned.Message ID: ***@***.***>

[josevalim]

Please see #2069.

[liamcmitchell]

Note an ex doc:loaded event won't solve the issue if the inline scripts in SWUP-loaded pages aren't executed. See https://swup.js.org/getting-started/reloading-javascript/
E.g. navigating from page without mermaid script to page with mermaid script

[jonatanklosko]

I believe ExDoc only allows configuring extra HTML content/scripts for all pages. Someone could post-process the files, but that's probably no something we need to worry about. @josevalim correct?