Added new code block styles to reference documentation

docs/reference/abbreviations.md

@@ -36,31 +36,31 @@ See additional configuration options:
 
 Abbreviations can be defined by using a special syntax similar to URLs and 
 [footnotes], starting with a `*` and immediately followed by the term or
-acronym to be associated in square brackets.
+acronym to be associated in square brackets:
 
-_Example_:
+``` markdown title="Text with abbreviations"
-
-``` markdown
 The HTML specification is maintained by the W3C.
 
 *[HTML]: Hyper Text Markup Language
 *[W3C]: World Wide Web Consortium
 ```
 
-_Result_:
+<div class="result" markdown>
 
 The HTML specification is maintained by the W3C.
 
 *[HTML]: Hyper Text Markup Language
 *[W3C]: World Wide Web Consortium
 
+</div>
+
   [footnotes]: footnotes.md
 
 ### Adding a glossary
 
 The [Snippets] extension can be used to implement a simple glossary by moving
 all abbreviations in a dedicated file[^1], and embedding it with the
-[`--8<--` notation][Snippets notation] at the end of each document.
+[`--8<--` notation][Snippets notation] at the end of each document:
 
   [^1]:
     It's highly recommended to put the Markdown file containing the
@@ -68,8 +68,6 @@ all abbreviations in a dedicated file[^1], and embedding it with the
     `includes` is used), as MkDocs might otherwise complain about an
     unreferenced file.
 
-_Example_:
-
 === ":octicons-file-code-16: docs/example.md"
 
     ```` markdown
@@ -85,8 +83,4 @@ _Example_:
     *[W3C]: World Wide Web Consortium
     ````
 
-_Result_:
-
-The HTML specification is maintained by the W3C.
-
   [Snippets notation]: https://facelessuser.github.io/pymdown-extensions/extensions/snippets/#snippets-notation

docs/reference/admonitions.md

@@ -52,13 +52,11 @@ theme:
 1.  Set `<type`> to any of the [supported types] and `<icon>` to any valid icon 
     shortcode, which you can find by using the [icon search].
 
-??? example "Example: using alternative icon sets"
+??? example "Expand to show alternate icon sets"
 
     === ":octicons-mark-github-16: Octicons"
 
-        _Example_:
+        ``` yaml title="Admonition with alternate icon set"
-
-        ``` yaml
         theme:
           icon:
             admonition:
@@ -76,16 +74,16 @@ theme:
               quote: octicons/quote-16
         ```
 
-        _Result_:
+        <div class="result" markdown>
 
         [![Octicons]][Octicons]
 
+        </div>
+
 
     === ":fontawesome-brands-font-awesome: FontAwesome"
 
-        _Example_:
+        ``` yaml title="Admonition with alternate icon set"
-
-        ``` yaml
         theme:
           icon:
             admonition:
@@ -103,10 +101,12 @@ theme:
               quote: fontawesome/solid/quote-left
         ```
 
-        _Result_:
+        <div class="result" markdown>
 
         [![FontAwesome]][FontAwesome]
 
+        </div>
+
   [Insiders]: ../insiders/index.md
   [custom icon]: icons-emojis.md#additional-icons
   [supported types]: #supported-types
@@ -118,11 +118,9 @@ theme:
 
 Admonitions follow a simple syntax: a block starts with `!!!`, followed by a
 single keyword used as a [type qualifier]. The content of the block follows on
-the next line, indented by four spaces.
+the next line, indented by four spaces:
 
-_Example_:
+``` markdown title="Admonition"
-
-``` markdown
 !!! note
 
     Lorem ipsum dolor sit amet, consectetur adipiscing elit. Nulla et euismod
@@ -130,7 +128,7 @@ _Example_:
     massa, nec semper lorem quam in massa.
 ```
 
-_Result_:
+<div class="result" markdown>
 
 !!! note
 
@@ -138,17 +136,17 @@ _Result_:
     nulla. Curabitur feugiat, tortor non consequat finibus, justo purus auctor
     massa, nec semper lorem quam in massa.
 
+</div>
+
   [type qualifier]: #supported-types
 
 ### Changing the title
 
 By default, the title will equal the type qualifier in titlecase. However, it
 can be changed by adding a quoted string containing valid Markdown (including
-links, formatting, ...) after the type qualifier.
+links, formatting, ...) after the type qualifier:
 
-_Example_:
+``` markdown title="Admonition with custom title"
-
-``` markdown
 !!! note "Phasellus posuere in sem ut cursus"
 
     Lorem ipsum dolor sit amet, consectetur adipiscing elit. Nulla et euismod
@@ -156,7 +154,7 @@ _Example_:
     massa, nec semper lorem quam in massa.
 ```
 
-_Result_:
+<div class="result" markdown>
 
 !!! note "Phasellus posuere in sem ut cursus"
 
@@ -164,15 +162,15 @@ _Result_:
     nulla. Curabitur feugiat, tortor non consequat finibus, justo purus auctor
     massa, nec semper lorem quam in massa.
 
+</div>
+
 ### Removing the title
 
 Similar to [changing the title], the icon and title can be omitted entirely by
 adding an empty string directly after the type qualifier. Note that this will
-not work for [collapsible blocks].
+not work for [collapsible blocks]:
 
-_Example_:
+``` markdown title="Admonition without title"
-
-``` markdown
 !!! note ""
 
     Lorem ipsum dolor sit amet, consectetur adipiscing elit. Nulla et euismod
@@ -180,7 +178,7 @@ _Example_:
     massa, nec semper lorem quam in massa.
 ```
 
-_Result_:
+<div class="result" markdown>
 
 !!! note ""
 
@@ -188,6 +186,8 @@ _Result_:
     nulla. Curabitur feugiat, tortor non consequat finibus, justo purus auctor
     massa, nec semper lorem quam in massa.
 
+</div>
+
   [changing the title]: #changing-the-title
   [collapsible blocks]: #collapsible-blocks
 
@@ -195,11 +195,9 @@ _Result_:
 
 When [Details] is enabled and an admonition block is started with `???` instead
 of `!!!`, the admonition is rendered as a collapsible block with a small toggle
-on the right side.
+on the right side:
 
-_Example_:
+``` markdown title="Admonition, collapsible"
-
-``` markdown
 ??? note
 
     Lorem ipsum dolor sit amet, consectetur adipiscing elit. Nulla et euismod
@@ -207,7 +205,7 @@ _Example_:
     massa, nec semper lorem quam in massa.
 ```
 
-_Result_:
+<div class="result" markdown>
 
 ??? note
 
@@ -215,11 +213,11 @@ _Result_:
     nulla. Curabitur feugiat, tortor non consequat finibus, justo purus auctor
     massa, nec semper lorem quam in massa.
 
-Adding a `+` after the `???` token will render the block as open.
+</div>
 
-_Example_:
+Adding a `+` after the `???` token renders the block expanded:
 
-``` markdown
+``` markdown title="Admonition, collapsible and initially expanded"
 ???+ note
 
     Lorem ipsum dolor sit amet, consectetur adipiscing elit. Nulla et euismod
@@ -227,7 +225,7 @@ _Example_:
     massa, nec semper lorem quam in massa.
 ```
 
-_Result_:
+<div class="result" markdown>
 
 ???+ note
 
@@ -235,6 +233,8 @@ _Result_:
     nulla. Curabitur feugiat, tortor non consequat finibus, justo purus auctor
     massa, nec semper lorem quam in massa.
 
+</div>
+
 ### Inline blocks
 
 [:octicons-tag-24: 7.0.0][Inline support] ·
@@ -242,12 +242,10 @@ _Result_:
 
 Admonitions can also be rendered as inline blocks (i.e. for sidebars), placing
 them to the right using the `inline` + `end` modifiers, or to the left using
-only the `inline` modifier.
+only the `inline` modifier:
 
 === ":octicons-arrow-right-16: inline end"
 
-    _Example_ / _Result_:
-
     !!! info inline end
 
         Lorem ipsum dolor sit amet, consectetur adipiscing elit. Nulla et
@@ -268,8 +266,6 @@ only the `inline` modifier.
 
 === ":octicons-arrow-left-16: inline"
 
-    _Example_ / _Result_:
-
     !!! info inline
 
         Lorem ipsum dolor sit amet, consectetur adipiscing elit. Nulla et
@@ -425,18 +421,6 @@ and add the following CSS to an [additional style sheet]:
   }
 </style>
 
-_Example_:
-
-=== ":octicons-file-code-16: docs/example.md"
-
-    ``` markdown
-    !!! pied-piper "Pied Piper"
-
-        Lorem ipsum dolor sit amet, consectetur adipiscing elit. Nulla et
-        euismod nulla. Curabitur feugiat, tortor non consequat finibus, justo
-        purus auctor massa, nec semper lorem quam in massa.
-    ```
-
 === ":octicons-file-code-16: docs/stylesheets/extra.css"
 
     ``` css
@@ -467,7 +451,17 @@ _Example_:
       - stylesheets/extra.css
     ```
 
-_Result_:
+After applying the customization, you can use the custom admonition type:
+
+``` markdown title="Admonition with custom type"
+!!! pied-piper "Pied Piper"
+
+    Lorem ipsum dolor sit amet, consectetur adipiscing elit. Nulla et
+    euismod nulla. Curabitur feugiat, tortor non consequat finibus, justo
+    purus auctor massa, nec semper lorem quam in massa.
+```
+
+<div class="result" markdown>
 
 !!! pied-piper "Pied Piper"
 
@@ -475,5 +469,7 @@ _Result_:
     nulla. Curabitur feugiat, tortor non consequat finibus, justo purus auctor
     massa, nec semper lorem quam in massa.
 
+</div>
+
   [custom icons]: https://github.com/squidfunk/mkdocs-material/tree/master/material/.icons
   [additional style sheet]: ../customization.md#additional-css

docs/reference/buttons.md

@@ -34,16 +34,16 @@ In order to render a link as a button, suffix it with curly braces and add the
 `.md-button` class selector to it. The button will receive the selected
 [primary color] and [accent color] if active.
 
-_Example_:
+``` markdown title="Button"
-
-``` markdown
 [Subscribe to our newsletter](#){ .md-button }
 ```
 
-_Result_:
+<div class="result" markdown>
 
 [Subscribe to our newsletter][Demo]{ .md-button }
 
+</div>
+
   [primary color]: ../setup/changing-the-colors.md#primary-color
   [accent color]: ../setup/changing-the-colors.md#accent-color 
   [Demo]: javascript:alert$.next("Demo")
@@ -54,16 +54,16 @@ If you want to display a filled, primary button (like on the [landing page]
 of Material for MkDocs), add both, the `.md-button` and `.md-button--primary`
 CSS class selectors.
 
-_Example_:
+``` markdown title="Button, primary"
-
-``` markdown
 [Subscribe to our newsletter](#){ .md-button .md-button--primary }
 ```
 
-_Result_:
+<div class="result" markdown>
 
 [Subscribe to our newsletter][Demo]{ .md-button .md-button--primary }
 
+</div>
+
   [landing page]: ../index.md
 
 ### Adding icon buttons
@@ -71,15 +71,15 @@ _Result_:
 Of course, icons can be added to all types of buttons by using the [icon syntax]
 together with any valid icon shortcode, which can be easily found with a few keystrokes through the [icon search].
 
-_Example_:
+``` markdown title="Button with icon"
-
+[Send :fontawesome-solid-paper-plane:](#){ .md-button }
-``` markdown
-[Send :fontawesome-solid-paper-plane:](#){ .md-button .md-button--primary }
 ```
 
-_Result_:
+<div class="result" markdown>
 
-[Send :fontawesome-solid-paper-plane:][Demo]{ .md-button .md-button--primary }
+[Send :fontawesome-solid-paper-plane:][Demo]{ .md-button }
+
+</div>
 
   [icon syntax]: icons-emojis.md#using-icons
   [icon search]: icons-emojis.md#search

docs/reference/code-blocks.md

@@ -107,22 +107,22 @@ click or open in a new tab:
 Code blocks must be enclosed with two separate lines containing three backticks.
 To add syntax highlighting to those blocks, add the language shortcode directly
 after the opening block. See the [list of available lexers] to find the
-shortcode for a given language.
+shortcode for a given language:
 
-_Example_:
+```` markdown title="Code block"
-
-```` markdown
 ``` py
 import tensorflow as tf
 ```
 ````
 
-_Result_:
+<div class="result" markdown>
 
 ``` py
 import tensorflow as tf
 ```
 
+</div>
+
   [list of available lexers]: https://pygments.org/docs/lexers/
 
 ### Adding a title
@@ -134,9 +134,7 @@ In order to provide additional context, a custom title can be added to a code
 block by using the `title="<custom title>"` option directly after the shortcode,
 e.g. to display the name of a file:
 
-_Example_:
+```` markdown title="Code block with title"
-
-```` markdown
 ``` py title="bubble_sort.py"
 def bubble_sort(items):
     for i in range(len(items)):
@@ -146,7 +144,7 @@ def bubble_sort(items):
 ```
 ````
 
-_Result_:
+<div class="result" markdown>
 
 ``` py title="bubble_sort.py"
 def bubble_sort(items):
@@ -156,13 +154,15 @@ def bubble_sort(items):
                 items[j], items[j + 1] = items[j + 1], items[j]
 ```
 
+</div>
+
   [Title support]: https://github.com/squidfunk/mkdocs-material/releases/tag/7.3.6
 
 ### Adding annotations
 
 Code annotations can be placed anywhere in a code block where a comment for the
 language of the block can be placed, e.g. for JavaScript in `#!js // ...` and
-`#!js /* ... */`, for YAML in `#!yaml # ...`, etc.[^1]
+`#!js /* ... */`, for YAML in `#!yaml # ...`, etc.[^1]:
 
   [^1]:
     Code annotations require syntax highlighting with [Pygments] – they're
@@ -171,9 +171,7 @@ language of the block can be placed, e.g. for JavaScript in `#!js // ...` and
     on supporting alternate ways of defining code annotations, allowing to
     always place code annotations at the end of lines.
 
-_Example_:
+```` markdown title="Code block with annotation"
-
-```` markdown
 ``` yaml
 theme:
   features:
@@ -184,7 +182,7 @@ theme:
     text__, images, ... basically anything that can be written in Markdown.
 ````
 
-_Result_:
+<div class="result" markdown>
 
 ``` yaml
 theme:
@@ -195,6 +193,8 @@ theme:
 1.  :man_raising_hand: I'm a code annotation! I can contain `code`, __formatted
     text__, images, ... basically anything that can be written in Markdown.
 
+</div>
+
 #### Stripping comments
 
 [:octicons-heart-fill-24:{ .mdx-heart } Insiders][Insiders]{ .mdx-insiders } ·
@@ -205,9 +205,7 @@ If you wish to strip the comment characters surrounding a code annotation,
 [Insiders] adds a new syntax that allows for just that. Simply add an `!` after
 the closing parens of the code annotation:
 
-_Example_:
+```` markdown title="Code block with annotation, stripped"
-
-```` markdown
 ``` yaml
 # (1)!
 ```
@@ -215,7 +213,7 @@ _Example_:
 1.  Look ma, less line noise!
 ````
 
-_Result_:
+<div class="result" markdown>
 
 ``` yaml
 # (1)!
@@ -223,6 +221,8 @@ _Result_:
 
 1.  Look ma, less line noise!
 
+</div>
+
 Note that this only allows for a single code annotation to be rendered per
 comment. If you want to add multiple code annotations, comments cannot be
 stripped for technical reasons.
@@ -232,11 +232,9 @@ stripped for technical reasons.
 Line numbers can be added to a code block by using the `linenums="<start>"`
 option directly after the shortcode, whereas `<start>` represents the starting
 line number. A code block can start from a line number other than `1`, which
-allows to split large code blocks for readability.
+allows to split large code blocks for readability:
 
-_Example_:
+```` markdown title="Code block with line numbers"
-
-```` markdown
 ``` py linenums="1"
 def bubble_sort(items):
     for i in range(len(items)):
@@ -246,7 +244,7 @@ def bubble_sort(items):
 ```
 ````
 
-_Result_:
+<div class="result" markdown>
 
 ``` py linenums="1"
 def bubble_sort(items):
@@ -256,60 +254,36 @@ def bubble_sort(items):
                 items[j], items[j + 1] = items[j + 1], items[j]
 ```
 
+</div>
+
 ### Highlighting specific lines
 
 Specific lines can be highlighted by passing the line numbers to the `hl_lines`
 argument placed right after the language shortcode. Note that line counts start
 at `1`, regardless of the starting line number specified as part of
-[`linenums`][Adding line numbers].
+[`linenums`][Adding line numbers]:
 
-=== "Line numbers"
+```` markdown title="Code block with highlighted lines"
+``` py hl_lines="2 3"
+def bubble_sort(items):
+    for i in range(len(items)):
+        for j in range(len(items) - 1 - i):
+            if items[j] > items[j + 1]:
+                items[j], items[j + 1] = items[j + 1], items[j]
+```
+````
 
-    _Example_:
+<div class="result" markdown>
 
-    ```` markdown 
+``` py linenums="1" hl_lines="2 3"
-    ``` py hl_lines="2 3"
+def bubble_sort(items):
-    def bubble_sort(items):
+    for i in range(len(items)):
-        for i in range(len(items)):
+        for j in range(len(items) - 1 - i):
-            for j in range(len(items) - 1 - i):
+            if items[j] > items[j + 1]:
-                if items[j] > items[j + 1]:
+                items[j], items[j + 1] = items[j + 1], items[j]
-                    items[j], items[j + 1] = items[j + 1], items[j]
+```
-    ```
-    ````
 
-    _Result_:
+</div>
-
-    ``` py linenums="1" hl_lines="2 3"
-    def bubble_sort(items):
-        for i in range(len(items)):
-            for j in range(len(items) - 1 - i):
-                if items[j] > items[j + 1]:
-                    items[j], items[j + 1] = items[j + 1], items[j]
-    ```
-
-=== "Line number ranges"
-
-    _Example_:
-
-    ```` markdown
-    ``` py hl_lines="2-5"
-    def bubble_sort(items):
-        for i in range(len(items)):
-            for j in range(len(items) - 1 - i):
-                if items[j] > items[j + 1]:
-                    items[j], items[j + 1] = items[j + 1], items[j]
-    ```
-    ````
-
-    _Result_:
-
-    ``` py linenums="1" hl_lines="2-5"
-    def bubble_sort(items):
-        for i in range(len(items)):
-            for j in range(len(items) - 1 - i):
-                if items[j] > items[j + 1]:
-                    items[j], items[j + 1] = items[j + 1], items[j]
-    ```
 
   [Adding line numbers]: #adding-line-numbers
 
@@ -319,36 +293,36 @@ When [InlineHilite] is enabled, syntax highlighting can be applied to inline
 code blocks by prefixing them with a shebang, i.e. `#!`, directly followed by
 the corresponding [language shortcode][list of available lexers].
 
-_Example_:
+``` markdown title="Inline code block"
-
-``` markdown
 The `#!python range()` function is used to generate a sequence of numbers.
 ```
 
-_Result_:
+<div class="result" markdown>
 
 The `#!python range()` function is used to generate a sequence of numbers.
 
+</div>
+
 ### Embedding external files
 
 When [Snippets] is enabled, content from other files (including source files)
 can be embedded by using the [`--8<--` notation][Snippets notation] directly
 from within a code block:
 
-_Example_:
+```` markdown title="Code block with external content"
-
-```` markdown
 ``` title=".browserslistrc"
 --8<--​ ".browserslistrc"
 ```
 ````
 
-_Result_:
+<div class="result" markdown>
 
 ``` title=".browserslistrc"
 last 4 years
 ```
 
+</div>
+
   [Snippets notation]: https://facelessuser.github.io/pymdown-extensions/extensions/snippets/#snippets-notation
 
 ## Customization

docs/reference/content-tabs.md

@@ -72,11 +72,9 @@ integrated with [instant loading] and persisted across page loads.
 
 Code blocks are one of the primary targets to be grouped, and can be considered
 a special case of content tabs, as tabs with a single code block are always
-rendered without horizontal spacing.
+rendered without horizontal spacing:
 
-_Example_:
+``` title="Content tabs with code blocks"
-
-```
 === "C"
 
     ``` c
@@ -100,7 +98,7 @@ _Example_:
     ```
 ```
 
-_Result_:
+<div class="result" markdown>
 
 === "C"
 
@@ -124,15 +122,15 @@ _Result_:
     }
     ```
 
+</div>
+
 ### Grouping other content
 
 When a content tab contains more than one code block, it is rendered with
 horizontal spacing. Vertical spacing is never added, but can be achieved
-by nesting tabs in other blocks.
+by nesting tabs in other blocks:
 
-_Example_:
+``` title="Content tabs"
-
-```
 === "Unordered list"
 
     * Sed sagittis eleifend rutrum
@@ -146,7 +144,7 @@ _Example_:
     3. Nulla tempor lobortis orci
 ```
 
-_Result_:
+<div class="result" markdown>
 
 === "Unordered list"
 
@@ -160,84 +158,54 @@ _Result_:
     2. Donec vitae suscipit est
     3. Nulla tempor lobortis orci
 
+</div>
+
 ### Embedded content
 
 When [SuperFences] is enabled, content tabs can contain arbitrary nested
 content, including further content tabs, and can be nested in other blocks like
 [admonitions] or blockquotes:
 
-_Example_:
+``` title="Content tabs in admonition"
-
-``` markdown
 !!! example
 
     === "Unordered List"
 
-        _Example_:
+        ``` markdown title="List, unordered"
-
-        ``` markdown
         * Sed sagittis eleifend rutrum
         * Donec vitae suscipit est
         * Nulla tempor lobortis orci
         ```
 
-        _Result_:
-
-        * Sed sagittis eleifend rutrum
-        * Donec vitae suscipit est
-        * Nulla tempor lobortis orci
-
     === "Ordered List"
 
-        _Example_:
+        ``` markdown title="List, ordered"
-
-        ``` markdown
         1. Sed sagittis eleifend rutrum
         2. Donec vitae suscipit est
         3. Nulla tempor lobortis orci
         ```
-
-        _Result_:
-
-        1. Sed sagittis eleifend rutrum
-        2. Donec vitae suscipit est
-        3. Nulla tempor lobortis orci
 ```
 
-_Result_:
+<div class="result" markdown>
 
 !!! example
 
     === "Unordered List"
 
-        _Example_:
+        ``` markdown title="List, unordered"
-
-        ``` markdown
         * Sed sagittis eleifend rutrum
         * Donec vitae suscipit est
         * Nulla tempor lobortis orci
         ```
 
-        _Result_:
-
-        * Sed sagittis eleifend rutrum
-        * Donec vitae suscipit est
-        * Nulla tempor lobortis orci
-
     === "Ordered List"
 
-        _Example_:
+        ``` markdown title="List, ordered"
-
-        ``` markdown
         1. Sed sagittis eleifend rutrum
         2. Donec vitae suscipit est
         3. Nulla tempor lobortis orci
         ```
 
-        _Result_:
+</div>
-
-        1. Sed sagittis eleifend rutrum
-        2. Donec vitae suscipit est
-        3. Nulla tempor lobortis orci
 
   [admonitions]: admonitions.md

docs/reference/data-tables.md

@@ -33,11 +33,9 @@ See additional configuration options:
 
 Data tables can be used at any position in your project documentation and can
 contain arbitrary Markdown, including inline code blocks, as well as [icons and
-emojis].
+emojis]:
 
-_Example_:
+``` markdown title="Data table"
-
-``` markdown
 | Method      | Description                          |
 | ----------- | ------------------------------------ |
 | `GET`       | :material-check:     Fetch resource  |
@@ -45,7 +43,7 @@ _Example_:
 | `DELETE`    | :material-close:     Delete resource |
 ```
 
-_Result_:
+<div class="result" markdown>
 
 | Method      | Description                          |
 | ----------- | ------------------------------------ |
@@ -53,6 +51,8 @@ _Result_:
 | `PUT`       | :material-check-all: Update resource |
 | `DELETE`    | :material-close:     Delete resource |
 
+</div>
+
   [icons and emojis]: icons-emojis.md
 
 ### Column alignment
@@ -63,9 +63,7 @@ and/or end of the divider.
 
 === "Left"
 
-    _Example_:
+    ``` markdown hl_lines="2" title="Data table, aligned to left"
-
-    ``` markdown hl_lines="2"
     | Method      | Description                          |
     | :---------- | :----------------------------------- |
     | `GET`       | :material-check:     Fetch resource  |
@@ -73,7 +71,7 @@ and/or end of the divider.
     | `DELETE`    | :material-close:     Delete resource |
     ```
 
-    _Result_:
+    <div class="result" markdown>
 
     | Method      | Description                          |
     | :---------- | :----------------------------------- |
@@ -81,11 +79,11 @@ and/or end of the divider.
     | `PUT`       | :material-check-all: Update resource |
     | `DELETE`    | :material-close:     Delete resource |
 
+    </div>
+
 === "Center"
 
-    _Example_:
+    ``` markdown hl_lines="2" title="Data table, centered"
-
-    ``` markdown hl_lines="2"
     | Method      | Description                          |
     | :---------: | :----------------------------------: |
     | `GET`       | :material-check:     Fetch resource  |
@@ -93,7 +91,7 @@ and/or end of the divider.
     | `DELETE`    | :material-close:     Delete resource |
     ```
 
-    _Result_:
+    <div class="result" markdown>
 
     | Method      | Description                          |
     | :---------: | :----------------------------------: |
@@ -101,11 +99,11 @@ and/or end of the divider.
     | `PUT`       | :material-check-all: Update resource |
     | `DELETE`    | :material-close:     Delete resource |
 
+    </div>
+
 === "Right"
 
-    _Example_:
+    ``` markdown hl_lines="2" title="Data table, aligned to right"
-
-    ``` markdown hl_lines="2"
     | Method      | Description                          |
     | ----------: | -----------------------------------: |
     | `GET`       | :material-check:     Fetch resource  |
@@ -113,7 +111,7 @@ and/or end of the divider.
     | `DELETE`    | :material-close:     Delete resource |
     ```
 
-    _Result_:
+    <div class="result" markdown>
 
     | Method      | Description                          |
     | ----------: | -----------------------------------: |
@@ -121,6 +119,8 @@ and/or end of the divider.
     | `PUT`       | :material-check-all: Update resource |
     | `DELETE`    | :material-close:     Delete resource |
 
+    </div>
+
   [regular Markdown syntax]: https://www.markdownguide.org/extended-syntax/#tables
 
 ## Customization
@@ -150,13 +150,10 @@ loading] via [additional JavaScript]:
       - javascripts/tablesort.js
     ```
 
-Note that [tablesort] provides alternative comparison implementations like
+After applying the customization, data tables can be sorted by clicking on a
-numbers, filesizes, dates and month names. See the [tablesort documentation]
+column:
-[tablesort] for more information.
 
-_Example_:
+``` markdown title="Data table"
-
-``` markdown
 | Method      | Description                          |
 | ----------- | ------------------------------------ |
 | `GET`       | :material-check:     Fetch resource  |
@@ -164,7 +161,7 @@ _Example_:
 | `DELETE`    | :material-close:     Delete resource |
 ```
 
-_Result_:
+<div class="result" markdown>
 
 | Method      | Description                          |
 | ----------- | ------------------------------------ |
@@ -172,6 +169,12 @@ _Result_:
 | `PUT`       | :material-check-all: Update resource |
 | `DELETE`    | :material-close:     Delete resource |
 
+</div>
+
+Note that [tablesort] provides alternative comparison implementations like
+numbers, filesizes, dates and month names. See the [tablesort documentation]
+[tablesort] for more information.
+
 <script src="https://cdnjs.cloudflare.com/ajax/libs/tablesort/5.2.1/tablesort.min.js"></script>
 <script>
   var tables = document.querySelectorAll("article table")

docs/reference/diagrams.md

@@ -54,11 +54,9 @@ No further configuration is necessary. Advantages over a custom integration:
 
 [Flowcharts] are diagrams that represent workflows or processes. The steps
 are rendered as nodes of various kinds and are connected by edges, describing
-the necessary order of steps.
+the necessary order of steps:
 
-_Example_:
+```` markdown title="Mermaid.js flow chart"
-
-```` markdown
 ``` mermaid
 graph LR
   A[Start] --> B{Error?};
@@ -69,7 +67,7 @@ graph LR
 ```
 ````
 
-_Result_:
+<div class="result" markdown>
 
 ``` mermaid
 graph LR
@@ -80,17 +78,17 @@ graph LR
   B ---->|No| E[Yay!];
 ```
 
+</div>
+
   [Flowcharts]: https://mermaid-js.github.io/mermaid/#/flowchart
 
 ### Using sequence diagrams
 
 [Sequence diagrams] describe a specific scenario as sequential interactions 
 between multiple objects or actors, including the messages that are exchanged
-between those actors.
+between those actors:
 
-_Example_:
+```` markdown title="Mermaid.js sequence diagram"
-
-```` markdown
 ``` mermaid
 sequenceDiagram
   Alice->>John: Hello John, how are you?
@@ -104,7 +102,7 @@ sequenceDiagram
 ```
 ````
 
-_Result_:
+<div class="result" markdown>
 
 ``` mermaid
 sequenceDiagram
@@ -118,69 +116,59 @@ sequenceDiagram
   Bob-->>John: Jolly good!
 ```
 
+</div>
+
   [Sequence diagrams]: https://mermaid-js.github.io/mermaid/#/sequenceDiagram
 
 ### Using state diagrams
 
 [State diagrams] are a great tool to describe the behavior of a system,
 decomposing it into a finite number of states, and transitions between those
-states.
+states:
 
-_Example_:
+```` markdown title="Mermaid.js state diagram"
-
-```` markdown
 ``` mermaid
 stateDiagram-v2
-  [*] --> Active
+  state fork_state <<fork>>
+    [*] --> fork_state
+    fork_state --> State2
+    fork_state --> State3
 
-  state Active {
+    state join_state <<join>>
-    [*] --> NumLockOff
+    State2 --> join_state
-    NumLockOff --> NumLockOn : EvNumLockPressed
+    State3 --> join_state
-    NumLockOn --> NumLockOff : EvNumLockPressed
+    join_state --> State4
-    --
+    State4 --> [*]
-    [*] --> CapsLockOff
-    CapsLockOff --> CapsLockOn : EvCapsLockPressed
-    CapsLockOn --> CapsLockOff : EvCapsLockPressed
-    --
-    [*] --> ScrollLockOff
-    ScrollLockOff --> ScrollLockOn : EvScrollLockPressed
-    ScrollLockOn --> ScrollLockOff : EvScrollLockPressed
-  }
 ```
 ````
 
-_Result_:
+<div class="result" markdown>
 
 ``` mermaid
 stateDiagram-v2
-  [*] --> Active
+  state fork_state <<fork>>
+    [*] --> fork_state
+    fork_state --> State2
+    fork_state --> State3
 
-  state Active {
+    state join_state <<join>>
-    [*] --> NumLockOff
+    State2 --> join_state
-    NumLockOff --> NumLockOn : EvNumLockPressed
+    State3 --> join_state
-    NumLockOn --> NumLockOff : EvNumLockPressed
+    join_state --> State4
-    --
+    State4 --> [*]
-    [*] --> CapsLockOff
-    CapsLockOff --> CapsLockOn : EvCapsLockPressed
-    CapsLockOn --> CapsLockOff : EvCapsLockPressed
-    --
-    [*] --> ScrollLockOff
-    ScrollLockOff --> ScrollLockOn : EvScrollLockPressed
-    ScrollLockOn --> ScrollLockOff : EvScrollLockPressed
-  }
 ```
 
+</div>
+
   [State diagrams]: https://mermaid-js.github.io/mermaid/#/stateDiagram
 
 ### Using class diagrams
 
 [Class diagrams] are central to object oriented programing, describing the
 structure of a system by modelling entities as classes and relationships between
-them.
+them:
 
-_Example_:
+```` markdown title="Mermaid.js class diagram"
-
-```` markdown
 ``` mermaid
 classDiagram
   Person <|-- Student
@@ -211,7 +199,7 @@ classDiagram
 ```
 ````
 
-_Result_:
+<div class="result" markdown>
 
 ``` mermaid
 classDiagram
@@ -242,17 +230,17 @@ classDiagram
   }
 ```
 
+</div>
+
   [Class diagrams]: https://mermaid-js.github.io/mermaid/#/classDiagram
 
 ### Using entity-relationship diagrams
 
 An [entity-relationship diagram] is composed of entity types and specifies
 relationships that exist between entities. It describes inter-related things in
-a specific domain of knowledge.
+a specific domain of knowledge:
 
-_Example_:
+```` markdown title="Mermaid.js entity-relationship diagram"
-
-```` markdown
 ``` mermaid
 erDiagram
   CUSTOMER ||--o{ ORDER : places
@@ -261,7 +249,7 @@ erDiagram
 ```
 ````
 
-_Result_:
+<div class="result" markdown>
 
 ``` mermaid
 erDiagram
@@ -270,4 +258,6 @@ erDiagram
   CUSTOMER }|..|{ DELIVERY-ADDRESS : uses
 ```
 
+</div>
+
   [entity-relationship diagram]: https://mermaid-js.github.io/mermaid/#/entityRelationshipDiagram

docs/reference/footnotes.md

@@ -35,16 +35,16 @@ A footnote reference must be enclosed in square brackets and must start with a
 caret `^`, directly followed by an arbitrary identifier, which is similar to
 the standard Markdown link syntax.
 
-_Example_:
+``` title="Text with footnote references"
-
-``` markdown
 Lorem ipsum[^1] dolor sit amet, consectetur adipiscing elit.[^2]
 ```
 
-_Result_:
+<div class="result" markdown>
 
 Lorem ipsum[^1] dolor sit amet, consectetur adipiscing elit.[^2]
 
+</div>
+
 ### Adding footnote content
 
 The footnote content must be declared with the same identifier as the reference.
@@ -54,38 +54,38 @@ reference is automatically added.
 
 #### on a single line
 
-Short footnotes can be written on the same line.
+Short footnotes can be written on the same line:
 
-_Example_:
+``` title="Footnote"
-
-``` markdown
 [^1]: Lorem ipsum dolor sit amet, consectetur adipiscing elit.
 ```
 
-_Result_:
+<div class="result" markdown>
 
 [:octicons-arrow-down-24: Jump to footnote](#fn:1)
 
+</div>
+
   [^1]: Lorem ipsum dolor sit amet, consectetur adipiscing elit.
 
 #### on multiple lines
 
-Paragraphs can be written on the next line and must be indented by four spaces.
+Paragraphs can be written on the next line and must be indented by four spaces:
 
-_Example_:
+``` title="Footnote"
-
-``` markdown
 [^2]:
     Lorem ipsum dolor sit amet, consectetur adipiscing elit. Nulla et euismod
     nulla. Curabitur feugiat, tortor non consequat finibus, justo purus auctor
     massa, nec semper lorem quam in massa.
 ```
 
-_Result_:
+<div class="result" markdown>
+
+[:octicons-arrow-down-24: Jump to footnote](#fn:2)
+
+</div>
 
 [^2]:
     Lorem ipsum dolor sit amet, consectetur adipiscing elit. Nulla et euismod
     nulla. Curabitur feugiat, tortor non consequat finibus, justo purus
     auctor massa, nec semper lorem quam in massa.
-
-[:octicons-arrow-down-24: Jump to footnote](#fn:2)

docs/reference/formatting.md

@@ -42,11 +42,9 @@ See additional configuration options:
 ### Highlighting changes
 
 When [Critic] is enabled, [Critic Markup] can be used, which adds the ability to 
-highlight suggested changes, as well as add inline comments to a document.
+highlight suggested changes, as well as add inline comments to a document:
 
-_Example_:
+``` title="Text with suggested changes"
-
-``` markdown
 Text can be {--deleted--} and replacement text {++added++}. This can also be
 combined into {~~one~>a single~~} operation. {==Highlighting==} is also
 possible {>>and comments can be added inline<<}.
@@ -59,7 +57,7 @@ tags on separate lines and adding new lines between the tags and the content.
 ==}
 ```
 
-_Result_:
+<div class="result" markdown>
 
 Text can be <del class="critic">deleted</del> and replacement text
 <ins class="critic">added</ins>. This can also be combined into
@@ -77,26 +75,28 @@ Text can be <del class="critic">deleted</del> and replacement text
   </mark>
 </div>
 
+</div>
+
 ### Highlighting text
 
 When [Caret, Mark & Tilde] are enabled, text can be highlighted with a simple 
 syntax, which is more convenient that directly using the corresponding
-[`mark`][mark], [`ins`][ins] and [`del`][del] HTML tags.
+[`mark`][mark], [`ins`][ins] and [`del`][del] HTML tags:
 
-_Example_:
+``` title="Text with highlighting"
-
-``` markdown 
 - ==This was marked==
 - ^^This was inserted^^
 - ~~This was deleted~~
 ```
 
-_Result_:
+<div class="result" markdown>
 
 - ==This was marked==
 - ^^This was inserted^^
 - ~~This was deleted~~
 
+</div>
+
   [mark]: https://developer.mozilla.org/en-US/docs/Web/HTML/Element/mark
   [ins]: https://developer.mozilla.org/en-US/docs/Web/HTML/Element/ins
   [del]: https://developer.mozilla.org/en-US/docs/Web/HTML/Element/del
@@ -105,20 +105,20 @@ _Result_:
 
 When [Caret & Tilde][Caret, Mark & Tilde] are enabled, text can be sub- and 
 superscripted with a simple syntax, which is more convenient that directly
-using the corresponding [`sub`][sub] and [`sup`][sup]  HTML tags:
+using the corresponding [`sub`][sub] and [`sup`][sup] HTML tags:
 
-_Example_:
+``` markdown title="Text with sub- und superscripts"
-
-``` markdown 
 - H~2~0
 - A^T^A
 ```
 
-_Result_:
+<div class="result" markdown>
 
 - H~2~0
 - A^T^A
 
+</div>
+
   [sub]: https://developer.mozilla.org/en-US/docs/Web/HTML/Element/sub
   [sup]: https://developer.mozilla.org/en-US/docs/Web/HTML/Element/sup
 
@@ -126,16 +126,16 @@ _Result_:
 
 When [Keys] is enabled, keyboard keys can be rendered with a simple syntax.
 Consult the [Python Markdown Extensions] documentation to learn about all
-available shortcodes.
+available shortcodes:
 
-_Example_:
+``` markdown title="Keyboard keys"
-
-``` markdown
 ++ctrl+alt+del++
 ```
 
-_Result_:
+<div class="result" markdown>
 
 ++ctrl+alt+del++
 
+</div>
+
   [Python Markdown Extensions]: https://facelessuser.github.io/pymdown-extensions/extensions/keys/#extendingmodifying-key-map-index

docs/reference/icons-emojis.md

@@ -67,18 +67,18 @@ See additional configuration options:
 
 Emojis can be integrated in Markdown by putting the shortcode of the emoji
 between two colons. If you're using [Twemoji] (recommended), you can look up
-the shortcodes at [Emojipedia].
+the shortcodes at [Emojipedia]:
 
-_Example_:
+``` title="Emoji"
-
-```
 :smile: 
 ```
 
-_Result_:
+<div class="result" markdown>
 
 :smile:
 
+</div>
+
   [Twemoji]: https://twemoji.twitter.com/
   [Emojipedia]: https://emojipedia.org/twitter/
 
@@ -88,66 +88,37 @@ When [Emoji] is enabled, icons can be used similar to emojis, by referencing
 a valid path to any icon bundled with the theme, which are located in the
 [`.icons`][custom icons] directory, and replacing `/` with `-`:
 
-_Example_:
+``` title="Icon"
-
+:fontawesome-regular-laugh-wink:
-```
-- :material-account-circle: – `material/account-circle.svg`
-- :fontawesome-regular-laugh-wink: – `fontawesome/regular/laugh-wink.svg`
-- :octicons-repo-push-16: – `octicons/repo-push-16.svg`
 ```
 
-_Result_:
+<div class="result" markdown>
 
-- :material-account-circle: – [`material/account-circle.svg`][icon Material]
+:fontawesome-regular-laugh-wink:
-- :fontawesome-regular-laugh-wink: – [`fontawesome/regular/laugh-wink.svg`][icon FontAwesome]
+
-- :octicons-repo-push-16: – [`octicons/repo-push-16.svg`][icon Octicons]
+</div>
 
   [custom icons]: https://github.com/squidfunk/mkdocs-material/tree/master/material/.icons
-  [icon Material]: https://raw.githubusercontent.com/squidfunk/mkdocs-material/master/material/.icons/material/account-circle.svg
-  [icon FontAwesome]: https://raw.githubusercontent.com/squidfunk/mkdocs-material/master/material/.icons/fontawesome/regular/laugh-wink.svg
-  [icon Octicons]: https://raw.githubusercontent.com/squidfunk/mkdocs-material/master/material/.icons/octicons/repo-push-16.svg
 
 #### with colors
 
-When [Attribute Lists] is enabled, custom CSS classes can be added to icons by
+Custom CSS classes can be added to icons by suffixing the icon with a special
-suffixing the icon with a special syntax. While HTML allows to use
+syntax. While HTML allows to use [inline styles], it's always recommended to
-[inline styles], it's always recommended to add an [additional style sheet] and
+add an [additional style sheet] and move declarations into dedicated CSS
-move declarations into dedicated CSS classes.
+classes:
 
 <style>
-  .medium {
-    color: #00AB6C;
-  }
   .twitter {
     color: #1DA1F2;
   }
-  .facebook {
-    color: #4267B2;
-  }
 </style>
 
-_Example_:
-
-=== ":octicons-file-code-16: docs/example.md"
-
-    ``` markdown
-    - :fontawesome-brands-medium:{ .medium } – Medium
-    - :fontawesome-brands-twitter:{ .twitter } – Twitter
-    - :fontawesome-brands-facebook:{ .facebook } – Facebook
-    ```
-
 === ":octicons-file-code-16: docs/stylesheets/extra.css"
 
     ``` css
-    .medium {
-      color: #00AB6C;
-    }
     .twitter {
       color: #1DA1F2;
     }
-    .facebook {
-      color: #4267B2;
-    }
     ```
 
 === ":octicons-file-code-16: mkdocs.yml"
@@ -157,11 +128,17 @@ _Example_:
       - stylesheets/extra.css
     ```
 
-_Result_:
+After applying the customization, add the CSS class to the icon shortcode:
 
-- :fontawesome-brands-medium:{ .medium } – Medium
+``` markdown title="Icon with color"
-- :fontawesome-brands-twitter:{ .twitter } – Twitter
+:fontawesome-brands-twitter:{ .twitter }
-- :fontawesome-brands-facebook:{ .facebook } – Facebook
+```
+
+<div class="result" markdown>
+
+:fontawesome-brands-twitter:{ .twitter }
+
+</div>
 
   [Attribute Lists]: ../setup/extensions/python-markdown.md#attribute-lists
   [inline styles]: https://developer.mozilla.org/en-US/docs/Web/HTML/Global_attributes/style
@@ -171,15 +148,7 @@ _Result_:
 
 Similar to adding [colors], it's just as easy to add [animations] to icons by
 using an [additional style sheet], defining a `@keyframes` rule and adding a
-dedicated CSS class to the icon.
+dedicated CSS class to the icon:
-
-_Example_:
-
-=== ":octicons-file-code-16: docs/example.md"
-
-    ``` markdown
-    :octicons-heart-fill-24:{ .heart }
-    ```
 
 === ":octicons-file-code-16: docs/stylesheets/extra.css"
 
@@ -204,10 +173,18 @@ _Example_:
       - stylesheets/extra.css
     ```
 
-_Result_:
+After applying the customization, add the CSS class to the icon shortcode:
+
+``` markdown title="Icon with animation"
+:octicons-heart-fill-24:{ .heart }
+```
+
+<div class="result" markdown>
 
 :octicons-heart-fill-24:{ .mdx-heart }
 
+</div>
+
   [colors]: #with-colors
   [animations]: https://developer.mozilla.org/en-US/docs/Web/CSS/animation
 

docs/reference/images.md

@@ -40,13 +40,11 @@ respective alignment directions via the `align` attribute, i.e. `align=left` or
 
 === "Left"
 
-    _Example_:
+    ``` markdown title="Image, aligned to left"
-
-    ``` markdown
     ![Image title](https://dummyimage.com/600x400/eee/aaa){ align=left }
     ```
 
-    _Result_:
+    <div class="result" markdown>
 
     ![Image title](https://dummyimage.com/600x400/f5f5f5/aaaaaa&text=–%20Image%20–){ align=left width=300 }
 
@@ -54,15 +52,15 @@ respective alignment directions via the `align` attribute, i.e. `align=left` or
     nulla. Curabitur feugiat, tortor non consequat finibus, justo purus auctor
     massa, nec semper lorem quam in massa.
 
+    </div>
+
 === "Right"
 
-    _Example_:
+    ``` markdown title="Image, aligned to right"
-
-    ``` markdown
     ![Image title](https://dummyimage.com/600x400/eee/aaa){ align=right }
     ```
 
-    _Result_:
+    <div class="result" markdown>
 
     ![Image title](https://dummyimage.com/600x400/f5f5f5/aaaaaa&text=–%20Image%20–){ align=right width=300 }
 
@@ -70,6 +68,8 @@ respective alignment directions via the `align` attribute, i.e. `align=left` or
     nulla. Curabitur feugiat, tortor non consequat finibus, justo purus auctor
     massa, nec semper lorem quam in massa.
 
+    </div>
+
 If there's insufficient space to render the text next to the image, the image
 will stretch to the full width of the viewport, e.g. on mobile viewports.
 
@@ -93,29 +93,22 @@ will stretch to the full width of the viewport, e.g. on mobile viewports.
 ### Image captions
 
 Sadly, the Markdown syntax doesn't provide native support for image captions,
-but it's always possible to use HTML. Using `figure` and `figcaption`, captions
+but it's always possible to use the [Markdown in HTML] extension with literal
-can be added to images.
+`figure` and `figcaption` tags:
 
-_Example_:
+``` html title="Image with caption"
-
+<figure markdown>
-```html
-<figure markdown> <!-- (1)! -->
   ![Image title](https://dummyimage.com/600x400/){ width="300" }
   <figcaption>Image caption</figcaption>
 </figure>
 ```
 
-1.  :man_raising_hand: Remember to enable the [Markdown in HTML] extension.
+<div class="result">
-
+  <figure>
-_Result_:
+    <img src="https://dummyimage.com/600x400/f5f5f5/aaaaaa&text=–%20Image%20–" width="300" />
-
+    <figcaption>Image caption</figcaption>
-<figure markdown>
+  </figure>
-  ![Placeholder]{ width="300" }
+</div>
-  <figcaption>Image caption</figcaption>
-</figure>
-
-  [Placeholder]: https://dummyimage.com/600x400/f5f5f5/aaaaaa&text=–%20Image%20–
-  [Markdown in HTML]: ../setup/extensions/python-markdown.md#markdown-in-html
 
 ### Image lazy-loading
 
@@ -123,10 +116,14 @@ Modern browsers provide [native support for lazy-loading images][lazy-loading]
 through the `loading=lazy` directive, which degrades to eager-loading in
 browsers without support:
 
-``` markdown
+``` markdown title="Image, lazy-loaded"
 ![Image title](https://dummyimage.com/600x400/){ loading=lazy }
 ```
 
+<div class="result" markdown>
+  <img src="https://dummyimage.com/600x400/f5f5f5/aaaaaa&text=–%20Image%20–" width="300" />
+</div>
+
   [lazy-loading]: https://caniuse.com/#feat=loading-lazy-attr
 
 ### Light and dark mode
@@ -138,18 +135,19 @@ If you added a [color palette toggle] and want to show different images for
 light and dark color schemes, you can append a `#only-light` or `#only-dark`
 hash fragment to the image URL:
 
-_Example_:
+``` markdown title="Image, different for light and dark mode"
-
-``` markdown
 ![Image title](https://dummyimage.com/600x400/f5f5f5/aaaaaa#only-light)
 ![Image title](https://dummyimage.com/600x400/21222c/d5d7e2#only-dark)
 ```
 
-_Result_:
+<div class="result" markdown>
 
 ![Zelda light world]{ width="300" }
 ![Zelda dark world]{ width="300" }
 
+</div>
+
+
   [Light and dark mode support]: https://github.com/squidfunk/mkdocs-material/releases/tag/8.1.1
   [color palette toggle]: ../setup/changing-the-colors.md#color-palette-toggle
   [Zelda light world]: ../assets/images/zelda-light-world.png#only-light

docs/reference/lists.md

@@ -37,11 +37,9 @@ See additional configuration options:
 
 Unordered lists can be written by prefixing a line with a `-`, `*` or `+` list
 marker, all of which can be used interchangeably. Furthermore, all flavors
-of lists can be nested inside each other.
+of lists can be nested inside each other:
 
-_Example_:
+``` markdown title="List, unordered"
-
-``` markdown
 - Nulla et rhoncus turpis. Mauris ultricies elementum leo. Duis efficitur
   accumsan nibh eu mattis. Vivamus tempus velit eros, porttitor placerat nibh
   lacinia sed. Aenean in finibus diam.
@@ -51,7 +49,7 @@ _Example_:
     * Nullam dignissim ultrices urna non auctor.
 ```
 
-_Result_:
+<div class="result" markdown>
 
 - Nulla et rhoncus turpis. Mauris ultricies elementum leo. Duis efficitur
   accumsan nibh eu mattis. Vivamus tempus velit eros, porttitor placerat nibh
@@ -61,15 +59,15 @@ _Result_:
     * Nam vulputate tincidunt fringilla.
     * Nullam dignissim ultrices urna non auctor.
 
+</div>
+
 ### Using ordered lists
 
 Ordered lists must start with a number immediately followed by a dot. The 
 numbers do not need to be consecutive and can be all set to `1.`, as they will
-be re-numbered when rendered.
+be re-numbered when rendered:
 
-_Example_:
+``` markdown title="List, ordered"
-
-``` markdown
 1.  Vivamus id mi enim. Integer id turpis sapien. Ut condimentum lobortis
     sagittis. Aliquam purus tellus, faucibus eget urna at, iaculis venenatis
     nulla. Vivamus a pharetra leo.
@@ -86,7 +84,7 @@ _Example_:
         3.  Suspendisse ac eros arcu
 ```
 
-_Result_:
+<div class="result" markdown>
 
 1.  Vivamus id mi enim. Integer id turpis sapien. Ut condimentum lobortis
     sagittis. Aliquam purus tellus, faucibus eget urna at, iaculis venenatis
@@ -103,14 +101,14 @@ _Result_:
         2.  Ut sit amet placerat ante
         3.  Suspendisse ac eros arcu
 
+</div>
+
 ### Using definition lists
 
 When [Definition Lists] is enabled, lists of arbitrary key-value pairs, e.g. the
-parameters of functions or modules, can be enumerated with a simple syntax.
+parameters of functions or modules, can be enumerated with a simple syntax:
 
-_Example_:
+``` markdown title="Definition list"
-
-``` markdown
 `Lorem ipsum dolor sit amet`
 
 :   Sed sagittis eleifend rutrum. Donec vitae suscipit est. Nullam tempus
@@ -126,7 +124,7 @@ _Example_:
     Nullam dignissim ultrices urna non auctor.
 ```
 
-_Result_:
+<div class="result" markdown>
 
 `Lorem ipsum dolor sit amet`
 
@@ -142,15 +140,15 @@ _Result_:
     Nam vulputate tincidunt fringilla.
     Nullam dignissim ultrices urna non auctor.
 
+</div>
+
 ### Using task lists
 
 When [Tasklist] is enabled, unordered list items can be prefixed with `[ ]` to
 render an unchecked checkbox or `[x]` to render a checked checkbox, allowing
-for the definition of task lists.
+for the definition of task lists:
 
-_Example_:
+``` markdown title="Task list"
-
-``` markdown
 - [x] Lorem ipsum dolor sit amet, consectetur adipiscing elit
 - [ ] Vestibulum convallis sit amet nisi a tincidunt
     * [x] In hac habitasse platea dictumst
@@ -159,7 +157,7 @@ _Example_:
 - [ ] Aenean pretium efficitur erat, donec pharetra, ligula non scelerisque
 ```
 
-_Result_:
+<div class="result" markdown>
 
 - [x] Lorem ipsum dolor sit amet, consectetur adipiscing elit
 - [ ] Vestibulum convallis sit amet nisi a tincidunt
@@ -167,3 +165,5 @@ _Result_:
     * [x] In scelerisque nibh non dolor mollis congue sed et metus
     * [ ] Praesent sed risus massa
 - [ ] Aenean pretium efficitur erat, donec pharetra, ligula non scelerisque
+
+</div>

docs/reference/mathjax.md

@@ -85,36 +85,37 @@ See additional configuration options:
 
 ### Using block syntax
 
-Blocks must be enclosed in `#!latex $$...$$` or `#!latex \[...\]`on separate lines:
+Blocks must be enclosed in `#!latex $$...$$` or `#!latex \[...\]` on separate
+lines:
 
-_Example_:
+``` latex title="MathJax, block syntax"
-
-``` latex
 $$
 \operatorname{ker} f=\{g\in G:f(g)=e_{H}\}{\mbox{.}}
 $$
 ```
 
-_Result_:
+<div class="result" markdown>
 
 $$
 \operatorname{ker} f=\{g\in G:f(g)=e_{H}\}{\mbox{.}}
 $$
 
+</div>
+
 ### Using inline block syntax
 
 Inline blocks must be enclosed in `#!latex $...$` or `#!latex \(...\)`:
 
-_Example_:
+``` latex title="MathJax, inline syntax"
-
-``` latex
 The homomorphism $f$ is injective if and only if its kernel is only the 
 singleton set $e_G$, because otherwise $\exists a,b\in G$ with $a\neq b$ such 
 that $f(a)=f(b)$.
 ```
 
-_Result_:
+<div class="result" markdown>
 
 The homomorphism $f$ is injective if and only if its kernel is only the 
 singleton set $e_G$, because otherwise $\exists a,b\in G$ with $a\neq b$ such 
 that $f(a)=f(b)$.
+
+</div>

material/base.html

@@ -34,7 +34,7 @@
       {% endif %}
     {% endblock %}
     {% block styles %}
-      <link rel="stylesheet" href="{{ 'assets/stylesheets/main.3d1b0ff9.min.css' | url }}">
+      <link rel="stylesheet" href="{{ 'assets/stylesheets/main.b9f2424c.min.css' | url }}">
       {% if config.theme.palette %}
         {% set palette = config.theme.palette %}
         <link rel="stylesheet" href="{{ 'assets/stylesheets/palette.e6a45f82.min.css' | url }}">

src/assets/stylesheets/main/_typeset.scss

@@ -417,7 +417,7 @@ kbd {
     display: flow-root;
     width: fit-content;
     max-width: 100%;
-    margin: 0 auto;
+    margin: 1em auto;
     text-align: center;
 
     // Figure images
@@ -429,7 +429,7 @@ kbd {
   // Figure caption
   figcaption {
     max-width: px2rem(480px);
-    margin: 1em auto 2em;
+    margin: 1em auto;
     font-style: italic;
   }
 

src/assets/stylesheets/main/extensions/pymdownx/_highlight.scss

@@ -313,6 +313,16 @@
       border-bottom-right-radius: px2rem(2px);
     }
   }
+
+  // Code block result container
+  :is(.highlight, .highlighttable) + .result {
+    margin-top: calc(-1em + #{px2em(-2px)});
+    padding: 0 px2em(16px);
+    overflow: auto;
+    border: px2rem(1px) solid var(--md-code-bg-color);
+    border-bottom-right-radius: px2rem(2px);
+    border-bottom-left-radius: px2rem(2px);
+  }
 }
 
 // ----------------------------------------------------------------------------
@@ -336,6 +346,13 @@
     code {
       border-radius: 0;
     }
+
+    // Code block result container
+    + .result {
+      margin-inline: px2rem(-16px);
+      border-inline-width: 0;
+      border-radius: 0;
+    }
   }
 
   // Top-level code block with line numbers

src/assets/stylesheets/main/extensions/pymdownx/_tabbed.scss

@@ -193,6 +193,11 @@
       }
     }
 
+    // Code block result container is the second child
+    > .result:nth-child(2) {
+      margin-top: 0;
+    }
+
     // Adjust spacing for nested tabbed container
     > .tabbed-set {
       margin: 0;