Added new code block styles to reference documentation

Author: squidfunk

docs/reference/abbreviations.md

@@ -36,40 +36,38 @@ 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
+``` markdown title="Text with abbreviations"
 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
     abbreviations outside of the `docs` folder (here, a folder with the name 
     `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
+        ``` yaml title="Admonition with alternate icon set"
         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_:
+    === ":fontawesome-brands-font-awesome: FontAwesome"
 
-        ``` yaml
+        ``` yaml title="Admonition with alternate icon set"
         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,136 +118,134 @@ 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
+``` markdown title="Admonition"
 !!! note
 
     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>
 
 !!! note
 
     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>
+
   [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
+``` markdown title="Admonition with custom title"
 !!! note "Phasellus posuere in sem ut cursus"
 
     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>
 
 !!! note "Phasellus posuere in sem ut cursus"
 
     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>
+
 ### 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
+``` markdown title="Admonition without title"
 !!! note ""
 
     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>
 
 !!! note ""
 
     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>
+
   [changing the title]: #changing-the-title
   [collapsible blocks]: #collapsible-blocks
 
 ### Collapsible blocks
 
 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
+``` markdown title="Admonition, collapsible"
 ??? note
 
     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>
 
 ??? note
 
     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.
 
-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
     nulla. Curabitur feugiat, tortor non consequat finibus, justo purus auctor
     massa, nec semper lorem quam in massa.
 ```
 
-_Result_:
+<div class="result" markdown>
 
 ???+ note
 
     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>
+
 ### Inline blocks
 
 [:octicons-tag-24: 7.0.0][Inline support] ·
 :octicons-beaker-24: Experimental
 
 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,13 +451,25 @@ _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"
 
     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>
+
   [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
+``` markdown title="Button"
 [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,32 +54,32 @@ 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
+``` markdown title="Button, primary"
 [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
 
 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
-[Send :fontawesome-solid-paper-plane:](#){ .md-button .md-button--primary }
+``` markdown title="Button with icon"
+[Send :fontawesome-solid-paper-plane:](#){ .md-button }
 ```
 
-_Result_:
+<div class="result" markdown>
+
+[Send :fontawesome-solid-paper-plane:][Demo]{ .md-button }
 
-[Send :fontawesome-solid-paper-plane:][Demo]{ .md-button .md-button--primary }
+</div>
 
   [icon syntax]: icons-emojis.md#using-icons
   [icon search]: icons-emojis.md#search