Add exdoc:loaded event (#2069)

Author: josevalim

README.md

@@ -370,6 +370,8 @@ docs: [
 ]
 ```
 
+On the JavaScript side, ExDoc emits the `"exdoc:loaded"` event. This event may be called multiple times, as you navigate across pages, so initialization that should happen only once must be conditional. We recommend external scripts to use `defer`, not `async`, as shown in the examples below.
+
 ### Rendering Math
 
 If you write TeX-style math in your Markdown, such as `$\sum_{i}^{N} x_i$`, it ends up as raw text on the generated pages. To render expressions, we recommend using [KaTeX](https://katex.org/), a JavaScript library that turns expressions into graphics. To load and trigger KaTeX on every documentation page, we can insert the following HTML:
@@ -381,13 +383,17 @@ If you write TeX-style math in your Markdown, such as `$\sum_{i}^{N} x_i$`, it e
 <link href="https://cdn.jsdelivr.net/npm/[email protected]/dist/katex-copytex.min.css" rel="stylesheet" type="text/css">
 <script defer src="https://cdn.jsdelivr.net/npm/[email protected]/dist/katex-copytex.min.js" crossorigin="anonymous"></script>
 
-<script defer src="https://cdn.jsdelivr.net/npm/[email protected]/dist/contrib/auto-render.min.js" integrity="sha384-+VBxd3r6XgURycqtZ117nYw44OOcIax56Z4dCRWbxyPt0Koah1uHoK0o4+/RRE05" crossorigin="anonymous"
-  onload="renderMathInElement(document.body, {
-    delimiters: [
-      {left: '$$', right: '$$', display: true},
-      {left: '$', right: '$', display: false},
-    ]
-  });"></script>
+<script defer src="https://cdn.jsdelivr.net/npm/[email protected]/dist/contrib/auto-render.min.js" integrity="sha384-+VBxd3r6XgURycqtZ117nYw44OOcIax56Z4dCRWbxyPt0Koah1uHoK0o4+/RRE05" crossorigin="anonymous"></script>
+
+<script>
+  window.addEventListener("exdoc:loaded", () => {
+    renderMathInElement(document.body, {
+      delimiters: [
+        {left: '$$', right: '$$', display: true},
+        {left: '$', right: '$', display: false},
+      ]
+    })
+  })
 </script>
 ```
 
@@ -402,7 +408,7 @@ Snippets are also objects you may want to render in a special manner. For exampl
 <script defer src="https://cdn.jsdelivr.net/npm/[email protected]"></script>
 <script defer src="https://cdn.jsdelivr.net/npm/[email protected]"></script>
 <script>
-  document.addEventListener("DOMContentLoaded", function () {
+  window.addEventListener("exdoc:loaded", () => {
     for (const codeEl of document.querySelectorAll("pre code.vega-lite")) {
       try {
         const preEl = codeEl.parentElement;
@@ -426,12 +432,19 @@ For more details and configuration options, see [vega/vega-embed](https://github
 Similarly to the example above, if your Markdown includes Mermaid graph specification in `mermaid` code snippets:
 
 ```html
+<script defer src="https://cdn.jsdelivr.net/npm/[email protected]/dist/mermaid.min.js"></script>
 <script>
-  function mermaidLoaded() {
-    mermaid.initialize({
-      startOnLoad: false,
-      theme: document.body.className.includes("dark") ? "dark" : "default"
-    });
+  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;
@@ -445,9 +458,8 @@ Similarly to the example above, if your Markdown includes Mermaid graph specific
         preEl.remove();
       });
     }
-  }
+  });
 </script>
-<script async src="https://cdn.jsdelivr.net/npm/[email protected]/dist/mermaid.min.js" onload="mermaidLoaded();"></script>
 ```
 
 For more details and configuration options, see the [Mermaid usage docs](https://mermaid-js.github.io/mermaid/#/usage).

assets/js/content.js

@@ -6,8 +6,7 @@ import { settingsStore } from './settings-store'
  * corresponding to the current documentation page.
  */
 
-window.addEventListener('swup:page:view', initialize)
-initialize()
+window.addEventListener('exdoc:loaded', initialize)
 
 function initialize () {
   const notebookPath = window.location.pathname.replace(/(\.html)?$/, '.livemd')

assets/js/copy-button.js

@@ -8,8 +8,7 @@ let buttonTemplate
  * Initializes copy buttons.
  */
 
-window.addEventListener('swup:page:view', initialize)
-initialize()
+window.addEventListener('exdoc:loaded', initialize)
 
 function initialize () {
   if (!('clipboard' in navigator)) return

assets/js/makeup.js

@@ -6,8 +6,7 @@ const HIGHLIGHT_CLASS = 'hll'
  * Sets up dynamic behaviour for code blocks processed with *makeup*.
  */
 
-window.addEventListener('swup:page:view', initialize)
-initialize()
+window.addEventListener('exdoc:loaded', initialize)
 
 export function initialize () {
   // Hovering over a delimiter (bracket, parenthesis, do/end)

assets/js/quick-switch.js

@@ -74,8 +74,7 @@ const state = {
  */
 
 if (!isEmbedded) {
-  window.addEventListener('swup:page:view', initialize)
-  initialize()
+  window.addEventListener('exdoc:loaded', initialize)
 }
 
 function initialize () {

assets/js/search-bar.js

@@ -21,8 +21,7 @@ const SEARCH_CLOSE_BUTTON_SELECTOR = 'form.search-bar .search-close-button'
  */
 
 if (!isEmbedded) {
-  window.addEventListener('swup:page:view', initialize)
-  initialize()
+  window.addEventListener('exdoc:loaded', initialize)
 }
 
 function initialize () {

assets/js/search-page.js

@@ -20,8 +20,7 @@ lunr.Pipeline.registerFunction(docTrimmerFunction, 'docTrimmer')
  * Activates only on the `/search.html` page.
  */
 
-window.addEventListener('swup:page:view', initialize)
-initialize()
+window.addEventListener('exdoc:loaded', initialize)
 
 function initialize () {
   const pathname = window.location.pathname

assets/js/settings.js

@@ -26,8 +26,7 @@ const modalTabs = [
  * Sets up the settings modal.
  */
 
-window.addEventListener('swup:page:view', initialize)
-initialize()
+window.addEventListener('exdoc:loaded', initialize)
 
 function initialize () {
   qsAll(SETTINGS_LINK_SELECTOR).forEach(element => {

assets/js/sidebar/sidebar-drawer.js

@@ -11,9 +11,7 @@ const SIDEBAR_TOGGLE_SELECTOR = '.sidebar-toggle'
 const smallScreenQuery = window.matchMedia(`screen and (max-width: ${SMALL_SCREEN_BREAKPOINT}px)`)
 
 if (!isEmbedded) {
-  setDefaultSidebarState()
-
-  window.addEventListener('swup:page:view', setDefaultSidebarState)
+  window.addEventListener('exdoc:loaded', setDefaultSidebarState)
 
   const sidebar = document.getElementById('sidebar')
   const sidebarToggle = qs(SIDEBAR_TOGGLE_SELECTOR)
@@ -49,6 +47,7 @@ if (!isEmbedded) {
     sessionStorage.setItem(SIDEBAR_WIDTH_KEY, width)
     document.body.style.setProperty('--sidebarWidth', `${width}px`)
   })
+
   // We observe on mousedown because we only care about user resize.
   sidebar.addEventListener('mousedown', () => resizeObserver.observe(sidebar))
   sidebar.addEventListener('mouseup', () => resizeObserver.unobserve(sidebar))

assets/js/sidebar/sidebar-list.js

@@ -89,9 +89,12 @@ export function initialize () {
   })
 
   window.addEventListener('hashchange', markCurrentHashInSidebar)
-  window.addEventListener('swup:page:view', markCurrentHashInSidebar)
 
+  // We listen to swup:page:view event because we need to trigger
+  // markCurrentHashInSidebar() before scollNodeListToCurrentCategory.
+  window.addEventListener('swup:page:view', markCurrentHashInSidebar)
   markCurrentHashInSidebar()
+
   // Triggers layout, defer.
   requestAnimationFrame(scrollNodeListToCurrentCategory)
 }