` 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_:
+
[![Octicons]][Octicons]
+
+
=== ":fontawesome-brands-font-awesome: FontAwesome"
- _Example_:
-
- ``` yaml
+ ``` yaml title="Admonition with alternate icon set"
theme:
icon:
admonition:
@@ -103,10 +101,12 @@ theme:
quote: fontawesome/solid/quote-left
```
- _Result_:
+
[![FontAwesome]][FontAwesome]
+
+
[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
+``` markdown title="Admonition"
!!! 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_:
+
!!! note
@@ -138,17 +136,17 @@ _Result_:
nulla. Curabitur feugiat, tortor non consequat finibus, justo purus auctor
massa, nec semper lorem quam in massa.
+
+
[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
@@ -156,7 +154,7 @@ _Example_:
massa, nec semper lorem quam in massa.
```
-_Result_:
+
!!! 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.
+
+
### 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
@@ -180,7 +178,7 @@ _Example_:
massa, nec semper lorem quam in massa.
```
-_Result_:
+
!!! note ""
@@ -188,6 +186,8 @@ _Result_:
nulla. Curabitur feugiat, tortor non consequat finibus, justo purus auctor
massa, nec semper lorem quam in massa.
+
+
[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
+``` markdown title="Admonition, collapsible"
??? 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_:
+
??? 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.
+
-_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_:
+
???+ note
@@ -235,6 +233,8 @@ _Result_:
nulla. Curabitur feugiat, tortor non consequat finibus, justo purus auctor
massa, nec semper lorem quam in massa.
+
+
### 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]:
}
-_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.
+```
+
+
!!! 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.
+
+
[custom icons]: https://github.com/squidfunk/mkdocs-material/tree/master/material/.icons
[additional style sheet]: ../customization.md#additional-css
diff --git a/docs/reference/buttons.md b/docs/reference/buttons.md
index 25592a423..9e201eace 100644
--- a/docs/reference/buttons.md
+++ b/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_:
+
[Subscribe to our newsletter][Demo]{ .md-button }
+
+
[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
+``` markdown title="Button, primary"
[Subscribe to our newsletter](#){ .md-button .md-button--primary }
```
-_Result_:
+
[Subscribe to our newsletter][Demo]{ .md-button .md-button--primary }
+
+
[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
-[Send :fontawesome-solid-paper-plane:](#){ .md-button .md-button--primary }
+``` markdown title="Button with icon"
+[Send :fontawesome-solid-paper-plane:](#){ .md-button }
```
-_Result_:
+
-[Send :fontawesome-solid-paper-plane:][Demo]{ .md-button .md-button--primary }
+[Send :fontawesome-solid-paper-plane:][Demo]{ .md-button }
+
+
[icon syntax]: icons-emojis.md#using-icons
[icon search]: icons-emojis.md#search
diff --git a/docs/reference/code-blocks.md b/docs/reference/code-blocks.md
index 01d28db33..5ea72edd5 100644
--- a/docs/reference/code-blocks.md
+++ b/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
+```` markdown title="Code block"
``` py
import tensorflow as tf
```
````
-_Result_:
+
``` py
import tensorflow as tf
```
+
+
[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=""` option directly after the shortcode,
e.g. to display the name of a file:
-_Example_:
-
-```` markdown
+```` markdown title="Code block with title"
``` py title="bubble_sort.py"
def bubble_sort(items):
for i in range(len(items)):
@@ -146,7 +144,7 @@ def bubble_sort(items):
```
````
-_Result_:
+
``` 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]
```
+
+
[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
+```` markdown title="Code block with annotation"
``` yaml
theme:
features:
@@ -184,7 +182,7 @@ theme:
text__, images, ... basically anything that can be written in Markdown.
````
-_Result_:
+
``` 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.
+
+
#### 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
+```` markdown title="Code block with annotation, stripped"
``` yaml
# (1)!
```
@@ -215,7 +213,7 @@ _Example_:
1. Look ma, less line noise!
````
-_Result_:
+
``` yaml
# (1)!
@@ -223,6 +221,8 @@ _Result_:
1. Look ma, less line noise!
+
+
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=""`
option directly after the shortcode, whereas `` 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
+```` markdown title="Code block with line numbers"
``` py linenums="1"
def bubble_sort(items):
for i in range(len(items)):
@@ -246,7 +244,7 @@ def bubble_sort(items):
```
````
-_Result_:
+
``` 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]
```
+
+
### 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_:
+
- ```` markdown
- ``` 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]
- ```
- ````
+``` 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]
+```
- _Result_:
-
- ``` 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
+``` markdown title="Inline code block"
The `#!python range()` function is used to generate a sequence of numbers.
```
-_Result_:
+
The `#!python range()` function is used to generate a sequence of numbers.
+
+
### 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
+```` markdown title="Code block with external content"
``` title=".browserslistrc"
--8<-- ".browserslistrc"
```
````
-_Result_:
+
``` title=".browserslistrc"
last 4 years
```
+
+
[Snippets notation]: https://facelessuser.github.io/pymdown-extensions/extensions/snippets/#snippets-notation
## Customization
diff --git a/docs/reference/content-tabs.md b/docs/reference/content-tabs.md
index 93da1b40b..41634701e 100644
--- a/docs/reference/content-tabs.md
+++ b/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_:
+
=== "C"
@@ -124,15 +122,15 @@ _Result_:
}
```
+
+
### 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_:
+
=== "Unordered list"
@@ -160,84 +158,54 @@ _Result_:
2. Donec vitae suscipit est
3. Nulla tempor lobortis orci
+
+
### 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_:
-
-``` markdown
+``` title="Content tabs in admonition"
!!! example
=== "Unordered List"
- _Example_:
-
- ``` markdown
+ ``` markdown title="List, unordered"
* 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
+ ``` markdown title="List, ordered"
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_:
+
!!! example
=== "Unordered List"
- _Example_:
-
- ``` markdown
+ ``` markdown title="List, unordered"
* 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
+ ``` markdown title="List, ordered"
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
+
[admonitions]: admonitions.md
diff --git a/docs/reference/data-tables.md b/docs/reference/data-tables.md
index 50056ab7f..6f0731f38 100644
--- a/docs/reference/data-tables.md
+++ b/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
+``` markdown title="Data table"
| Method | Description |
| ----------- | ------------------------------------ |
| `GET` | :material-check: Fetch resource |
@@ -45,7 +43,7 @@ _Example_:
| `DELETE` | :material-close: Delete resource |
```
-_Result_:
+
| Method | Description |
| ----------- | ------------------------------------ |
@@ -53,6 +51,8 @@ _Result_:
| `PUT` | :material-check-all: Update resource |
| `DELETE` | :material-close: Delete resource |
+
+
[icons and emojis]: icons-emojis.md
### Column alignment
@@ -63,9 +63,7 @@ and/or end of the divider.
=== "Left"
- _Example_:
-
- ``` markdown hl_lines="2"
+ ``` markdown hl_lines="2" title="Data table, aligned to left"
| Method | Description |
| :---------- | :----------------------------------- |
| `GET` | :material-check: Fetch resource |
@@ -73,7 +71,7 @@ and/or end of the divider.
| `DELETE` | :material-close: Delete resource |
```
- _Result_:
+
| Method | Description |
| :---------- | :----------------------------------- |
@@ -81,11 +79,11 @@ and/or end of the divider.
| `PUT` | :material-check-all: Update resource |
| `DELETE` | :material-close: Delete resource |
+
+
=== "Center"
- _Example_:
-
- ``` markdown hl_lines="2"
+ ``` markdown hl_lines="2" title="Data table, centered"
| Method | Description |
| :---------: | :----------------------------------: |
| `GET` | :material-check: Fetch resource |
@@ -93,7 +91,7 @@ and/or end of the divider.
| `DELETE` | :material-close: Delete resource |
```
- _Result_:
+
| Method | Description |
| :---------: | :----------------------------------: |
@@ -101,11 +99,11 @@ and/or end of the divider.
| `PUT` | :material-check-all: Update resource |
| `DELETE` | :material-close: Delete resource |
+
+
=== "Right"
- _Example_:
-
- ``` markdown hl_lines="2"
+ ``` markdown hl_lines="2" title="Data table, aligned to right"
| Method | Description |
| ----------: | -----------------------------------: |
| `GET` | :material-check: Fetch resource |
@@ -113,7 +111,7 @@ and/or end of the divider.
| `DELETE` | :material-close: Delete resource |
```
- _Result_:
+
| Method | Description |
| ----------: | -----------------------------------: |
@@ -121,6 +119,8 @@ and/or end of the divider.
| `PUT` | :material-check-all: Update resource |
| `DELETE` | :material-close: Delete resource |
+
+
[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
-numbers, filesizes, dates and month names. See the [tablesort documentation]
-[tablesort] for more information.
+After applying the customization, data tables can be sorted by clicking on a
+column:
-_Example_:
-
-``` markdown
+``` markdown title="Data table"
| Method | Description |
| ----------- | ------------------------------------ |
| `GET` | :material-check: Fetch resource |
@@ -164,7 +161,7 @@ _Example_:
| `DELETE` | :material-close: Delete resource |
```
-_Result_:
+
| Method | Description |
| ----------- | ------------------------------------ |
@@ -172,6 +169,12 @@ _Result_:
| `PUT` | :material-check-all: Update resource |
| `DELETE` | :material-close: Delete resource |
+
+
+Note that [tablesort] provides alternative comparison implementations like
+numbers, filesizes, dates and month names. See the [tablesort documentation]
+[tablesort] for more information.
+