init_notebook
init_notebook(use_cdn=None, force=False)Stash the bundled maidr.js / maidr-math.css in the notebook page.
Mirrors the plotly.offline.init_notebook_mode / bokeh.io.output_notebook pattern: put the library in the notebook’s page once instead of duplicating the ~1.7 MB bundle in every iframe srcdoc. The source strings are stashed on window.__maidrJsSource / window.__maidrMathCssSource in the parent document so that later iframe outputs can evaluate them in their own JS context without the bundle re-appearing in the notebook file.
The stylesheet stashed alongside the script is maidr-math.css, the KaTeX rules that style LaTeX in AI chat responses. It travels as a source string for the same reason the script does: an iframe rendered from srcdoc has no base URL, so maidr.js cannot fetch the file for itself the way it does on a page that loaded it over HTTP.
Nothing this emits runs maidr.js in the notebook’s own page: only the chart frames run it. Where the frames load the CDN copy, the page prefetches it for them, with a <link rel="prefetch"> rather than a <script src>, which the require.js of classic Notebook and of nbconvert’s HTML exports would swallow and every other frontend would run again for each chart. Not in a Quarto render, whose charts load the version the render resolves, which need not be the one prefetched.
Parameters
| Name | Type | Description | Default |
|---|---|---|---|
| use_cdn | bool, {"auto"}, or None | * True: stash nothing, and prefetch the CDN copy the frames load. * False: read the bundled maidr.js / maidr-math.css from the installed package and embed them as strings on window. Nothing else: the frames run only that copy, so when the bundle cannot be read this warns and emits nothing. * "auto": stash them as for False, as the fallback of frames that try the CDN first, and prefetch the CDN copy. * None (default): defer to :func:get_use_cdn. |
None |
| force | bool | Re-inject even if :data:_NOTEBOOK_LOADED is already True. Useful in Colab where each cell renders in isolation and the parent context is reset between cells. |
False |
Notes
No-op outside notebook environments (Environment.is_notebook() returns False). Safe to call multiple times — the guard flag prevents re-injection unless force=True.
Pins its prefetch to the bundled version rather than resolving one. maidr/__init__.py calls this at import, and resolving here would put a blocking network request inside import maidr — before the user has run anything, and before the documented opt-outs could be applied. A stalled DNS resolver is not reliably bounded by a socket timeout, so that wait has no dependable ceiling.
The bundled version needs no request and is still immutable, so the prefetch is cache-safe: naming @latest here would have left the parent document subject to the same seven-day cache lifetime this module exists to remove. Plots themselves render in iframes that inject their own <script> at the resolved version, so the first render() / save_html() is where a lookup happens. In a notebook that is the bundled version too, unless a pin or an explicit :func:maidr.bundle_status names another, so the frames load the very URL prefetched here.
That split has a known, accepted cost: whenever the bundle is behind the published release and a lookup has moved the frames past it — the very case :func:maidr.bundle_status exists to report — a notebook session fetches two different maidr.js builds, and this prefetch is one the plots do not end up using. It is still the right trade: the alternative is resolving at import time, which is the blocking request described above, and the duplicate cost falls away as soon as the bundle is refreshed at release time. Please do not “fix” this by resolving here.