diff --git a/_config.yml b/_config.yml
index b9571a0..68098e5 100644
--- a/_config.yml
+++ b/_config.yml
@@ -82,8 +82,6 @@ search:
 # For copy button on code
 enable_copy_code_button: true
 
-# To disable support for mermaid diagrams (https://mermaid.js.org),
-# comment out the `mermaid` and `version` keys below
 # By default, consuming the theme as a gem leaves mermaid disabled; it is opt-in
 mermaid:
   # Version of mermaid library
@@ -91,8 +89,12 @@ mermaid:
   version: "9.1.6"
   # Put any additional configuration, such as setting the theme, in _includes/mermaid_config.js
   # See also docs/ui-components/code
-  # To load mermaid from a local file use the `path` key to specify the location of the library instead; e.g.
+  # To load mermaid from a local library, also use the `path` key to specify the location of the library; e.g.
+  # for (v10+):
+  # path: "/assets/js/mermaid.esm.min.mjs"
+  # for (<v10):
   # path: "/assets/js/mermaid.min.js"
+  # Note: copy both `mermaid.esm.min.mjs` (v10+) or `mermaid.min.js` (<v10) and the associated `.map` file from the specified version of `mermaid/dist` to `/assets/js/`.
 
 # Enable or disable heading anchors
 heading_anchors: true
diff --git a/_includes/components/mermaid.html b/_includes/components/mermaid.html
index d6923e0..a99a563 100644
--- a/_includes/components/mermaid.html
+++ b/_includes/components/mermaid.html
@@ -1,5 +1,45 @@
+{% comment %}
+The complexity of this file comes from a breaking change in Mermaid v10; mermaid.init has been deprecated (and supposedly, didn't work earlier?).
+
+So, we check whether the user's Mermaid version is >= 10; if not, we fall back to the previous init syntax.
+
+If a user is using a custom mermaid file and doesn't specify a version, we default to the < v10 behaviour. Users who use version v10 or above should specify this in the version key.
+{% endcomment %}
+
+{% if site.mermaid.version %}
+  {% assign mermaid_major_version = site.mermaid.version | split: "." | first | plus: 0 %}
+{% else %}
+  {% assign mermaid_major_version = 9 %}
+{% endif %}
+
+{% if mermaid_major_version > 9 %}
+
+<script type="module">
+  {% if site.mermaid.path %}
+  import mermaid from '{{ site.mermaid.path | relative_url }}';
+  {% else %}
+  import mermaid from 'https://cdn.jsdelivr.net/npm/mermaid@{{ site.mermaid.version }}/dist/mermaid.esm.min.mjs';
+  {% endif %}
+
+  var config = {% include mermaid_config.js %};
+  mermaid.initialize(config);
+  mermaid.run({
+    querySelector: '.language-mermaid',
+  });
+</script>
+
+{% else %}
+
+{% if site.mermaid.path %}
+  <script src="{{ site.mermaid.path | relative_url }}"></script>
+{% else %}
+  <script src="https://cdn.jsdelivr.net/npm/mermaid@{{ site.mermaid.version }}/dist/mermaid.min.js"></script>
+{% endif %}
+
 <script>
   var config = {% include mermaid_config.js %};
   mermaid.initialize(config);
   window.mermaid.init(undefined, document.querySelectorAll('.language-mermaid'));
 </script>
+
+{% endif %}
diff --git a/_includes/head.html b/_includes/head.html
index 9f38d0f..d61f53f 100644
--- a/_includes/head.html
+++ b/_includes/head.html
@@ -22,14 +22,6 @@
     <script src="{{ '/assets/js/vendor/lunr.min.js' | relative_url }}"></script>
   {% endif %}
 
-  {% if site.mermaid %}
-    {% if site.mermaid.path %}
-      <script src="{{ site.mermaid.path | relative_url }}"></script>
-    {% else %}
-      <script src="https://cdn.jsdelivr.net/npm/mermaid@{{ site.mermaid.version }}/dist/mermaid.min.js"></script>
-    {% endif %}
-  {% endif %}
-
   <script src="{{ '/assets/js/just-the-docs.js' | relative_url }}"></script>
 
   <meta name="viewport" content="width=device-width, initial-scale=1">
diff --git a/docs/ui-components/code.md b/docs/ui-components/code.md
index 9a4df73..e907e2f 100644
--- a/docs/ui-components/code.md
+++ b/docs/ui-components/code.md
@@ -150,14 +150,24 @@ graph TD;
 
 ### Using a local mermaid library
 
-In order to use a local version of the mermaid library instead of one provided by jsDelivr, you can specify a `path` key in the mermaid configuration instead of a `version` key.
+To load a local version of mermaid, also use the `path` key to specify the location of the library; e.g.
 
 ```yaml
 mermaid:
-  # To load mermaid from a local file use the `path` key to specify the location of the library instead; e.g.
-  path: "/assets/js/mermaid.min.js"
+  version: "10.1.0"
+  # for (v10+)
+  path: "/assets/js/mermaid.esm.min.mjs"
+  # for (<v10):
+  # path: "/assets/js/mermaid.min.js"
+  # Note: copy both `mermaid.esm.min.mjs` (v10+) or `mermaid.min.js` (<v10) and the associated
+  # `.map` file from the specified version of `mermaid/dist` to `/assets/js/`.
 ```
 
+For mermaid versions `>=10`, this file is imported directly as an ESM module (rather than as a plain `<script>` tag); users should use the `mermaid.esm.min.mjs` file. In contrast, for mermaid versions `<10`, this file is loaded as a script tag; it should be a standalone CJS file (i.e. `mermaid.min.js`).
+
+{: .warning }
+Mermaid versions `10.0` - `10.1` (and possibly, future releases) still encode relative imports in `mermaid.esm.min.mjs`. Local users must copy *all* of the contents of the `dist` folder to the specified path (preserving the relative location of the files). Just the Docs is actively monitoring mermaid releases; an upstream fix is planned.
+
 ### Using mermaid with AsciiDoc
 
 Users of [AsciiDoc](https://asciidoc.org/) (e.g. via [jekyll-asciidoc](https://github.com/asciidoctor/jekyll-asciidoc)) may need additional configuration to use mermaid.