Support for dynamic light/dark theme

[gaborbernat]

As explained here https://twitter.com/hynek/status/1460241865652027397 and detailed https://pradyunsg.me/furo/customisation/colors/#how-light-and-dark-mode-work

[sneakers-the-rat]

fwiw I have got this working in a hacky way like this:

in conf.py, with javascript pulled out to separate block for the sake of syntax highlighting:

mermaid_version = None
mermaid_use_local = "https://example.com"
mermaid_init_js = """(below)"""

import mermaid from 'https://cdn.jsdelivr.net/npm/mermaid/dist/mermaid.esm.min.mjs'

const make_config = () => {
  let prefersDark = localStorage.getItem('theme') === 'dark' || (localStorage.getItem('theme') === null && window.matchMedia && window.matchMedia('(prefers-color-scheme: dark)').matches)
  return({
    startOnLoad:false,
    darkMode: prefersDark,
    theme: prefersDark ? "dark" : "default"
  })
}

const init_mermaid = () => {
    let graphs = document.querySelectorAll(".mermaid");
    [...graphs].forEach((element) => {
        if (!element.hasAttribute("data-source")) {
            element.setAttribute("data-source", element.innerText);
        }
        if (element.hasAttribute("data-processed")) {
            let new_elt = document.createElement("pre");
            let graph_source = element.getAttribute("data-source");
            new_elt.appendChild(document.createTextNode(graph_source));
            new_elt.classList.add("mermaid");
            new_elt.setAttribute("data-source", graph_source);
            element.replaceWith(new_elt);
        }
    });

    let config = make_config()
    mermaid.initialize(config);
    mermaid.run();
}

init_mermaid();

let theme_observer = new MutationObserver(init_mermaid);
let body = document.getElementsByTagName("body")[0];
theme_observer.observe(body, {attributes: true});
window.theme_observer = theme_observer;

This is basically designed for furo, watching the data-theme attribute in the body element, but it also detects general css preferences as well. There isn't a generic thing to watch for to see light/dark switches in js, so if we wanted to make this general we would have to just allow a config option that e.g. lets someone provide some selector to watch or a function that returns a boolean if it's dark or not or something.

I have to break the mermaid url in conf.py because the plugin actually loads mermaid three times - once from the CDN with a url script tag, once as an import in the init script tag, and then a third time in the script tag where run is called. If the other two mermaids fire, then they override the initialization in the init block. there's a ton of cleanup to be done with how that works in order to make something like this feasible, because already several of the options are mutually in conflict (e.g. you can't provide custom init js while also using the elk options, etc.)

[stevepiercy]

In our diagrams, I used the Mermaid base theme and customized it. It's not perfect, but it's better than the default.

Code

https://github.com/plone/documentation/blob/aea0b938b6fff482cfe844b5744b50ef07ca395d/docs/conceptual-guides/package-dependencies.md?plain=1#L166-L179

Preview

https://6.docs.plone.org/conceptual-guides/package-dependencies.html#detailed-view-of-the-architecture

You can copy-paste the code into https://www.mermaidchart.com/play for a live preview, although you will need to change the config from a dict to YAML.

Details are available in the Mermaid docs, Customizing Themes with themeVariables.