diff --git a/docs/assets/screenshots/diagram.png b/docs/assets/screenshots/diagram.png
deleted file mode 100644
index f2d57d949..000000000
Binary files a/docs/assets/screenshots/diagram.png and /dev/null differ
diff --git a/docs/reference/code-blocks.md b/docs/reference/code-blocks.md
index da58c01d7..c686d8a3f 100644
--- a/docs/reference/code-blocks.md
+++ b/docs/reference/code-blocks.md
@@ -247,19 +247,56 @@ document$.subscribe(function() { // (1)
 
 _Result_:
 
-<figure markdown="1">
+``` {: .js .annotate }
+document$.subscribe(function() { // (1)
+  var tables = document.querySelectorAll(/* (2) */ "article table")
+  tables.forEach(function(table) {
+    new Tablesort(table) // (3)
+  })
+})
+```
 
-[![Annotations][19]][19]
+1. Annotations can contain __arbitrary content__ which is shown when the marker
+   is focussed, including any kind of formatting, links, admonitions, details,
+   and even diagrams:
 
-  <figcaption markdown="1">
+    ``` mermaid
+    graph LR
+      A[I'm] --> B{a} --> C[diagram];
+    ```
 
-A demo is worth a thousand words — check it out at
-[squidfunk.github.io/mkdocs-material-insiders][20]
+    :octicons-light-bulb-16:
+    **Tip:** You can use ++tab++ to navigate annotations.
 
-  </figcaption>
-</figure>
+2. Annotations can be __placed anywhere__ in a code block were a comment for the
+   underlying language can be placed. 
 
-_Annotations require syntax highlighting with [Pygments][24] – they're currently
+    === "Python"
+
+        ``` python
+        # (1)
+        ```
+
+    === "JavaScript"
+
+        ``` js
+        // (2)
+        /* (2) */
+        ```
+
+    === "Lua"
+
+        ``` lua
+        -- (3)
+        ```
+
+    _We're working on a solution for languages without comments, which will be
+    available shortly._
+
+  1. Of course, this can be combined with [line numbers][10], highlighting and
+     all other code block related features.
+
+_Annotations require syntax highlighting with [Pygments][26] – they're currently
 not compatible with other JavaScript-based syntax highlighters. Support may be
 added later on._
 
diff --git a/docs/reference/diagrams.md b/docs/reference/diagrams.md
index bcb4cdc93..590991776 100644
--- a/docs/reference/diagrams.md
+++ b/docs/reference/diagrams.md
@@ -89,11 +89,17 @@ graph LR
 
 _Result_:
 
-[![Diagram][12]{ style="width: 100%; max-width: 594px" }][12]
+``` mermaid
+graph LR
+  A[Start] --> B{Error?};
+  B -->|Yes| C[Hmm...];
+  C --> D[Debug];
+  D --> B;
+  B ---->|No| E[Yay!];
+```
 
 _See the [official documentation][1] to learn about all available diagram 
 types._
 
   [10]: code-blocks.md
   [11]: #superfences
-  [12]: ../assets/screenshots/diagram.png