mirror of
https://github.com/squidfunk/mkdocs-material.git
synced 2024-06-14 11:52:32 +03:00
Added new code block styles to reference documentation
This commit is contained in:
squidfunk
parent
ca1996b668
commit
50408bf984
@ -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
|
||||
``` 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
|
||||
@ -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
|
||||
|
||||
@ -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_:
|
||||
|
||||
``` 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,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_:
|
||||
<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
|
||||
``` 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_:
|
||||
<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
|
||||
``` 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_:
|
||||
<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
|
||||
``` 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_:
|
||||
<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
|
||||
|
||||
@ -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,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_:
|
||||
<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
|
||||
[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 .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
|
||||
|
||||
@ -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_:
|
||||
<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
|
||||
```` 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_:
|
||||
<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
|
||||
```` 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_:
|
||||
<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
|
||||
```` markdown title="Code block with annotation, stripped"
|
||||
``` 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
|
||||
```` 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_:
|
||||
<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"
|
||||
|
||||
_Example_:
|
||||
|
||||
```` markdown
|
||||
``` py hl_lines="2 3"
|
||||
def bubble_sort(items):
|
||||
```` 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]
|
||||
```
|
||||
````
|
||||
```
|
||||
````
|
||||
|
||||
_Result_:
|
||||
<div class="result" markdown>
|
||||
|
||||
``` py linenums="1" hl_lines="2 3"
|
||||
def bubble_sort(items):
|
||||
``` 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]
|
||||
```
|
||||
</div>
|
||||
|
||||
[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_:
|
||||
<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
|
||||
```` markdown title="Code block with external content"
|
||||
``` 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
|
||||
|
||||
@ -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_:
|
||||
|
||||
``` 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_:
|
||||
<div class="result" markdown>
|
||||
|
||||
!!! 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
|
||||
</div>
|
||||
|
||||
[admonitions]: admonitions.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_:
|
||||
<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"
|
||||
``` 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_:
|
||||
<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"
|
||||
``` 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_:
|
||||
<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"
|
||||
``` 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_:
|
||||
<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
|
||||
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_:
|
||||
<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")
|
||||
|
||||
@ -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
|
||||
```` markdown title="Mermaid.js flow chart"
|
||||
``` 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
|
||||
```` markdown title="Mermaid.js sequence diagram"
|
||||
``` 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
|
||||
```` markdown title="Mermaid.js state diagram"
|
||||
``` mermaid
|
||||
stateDiagram-v2
|
||||
[*] --> Active
|
||||
state fork_state <<fork>>
|
||||
[*] --> fork_state
|
||||
fork_state --> State2
|
||||
fork_state --> State3
|
||||
|
||||
state Active {
|
||||
[*] --> NumLockOff
|
||||
NumLockOff --> NumLockOn : EvNumLockPressed
|
||||
NumLockOn --> NumLockOff : EvNumLockPressed
|
||||
--
|
||||
[*] --> CapsLockOff
|
||||
CapsLockOff --> CapsLockOn : EvCapsLockPressed
|
||||
CapsLockOn --> CapsLockOff : EvCapsLockPressed
|
||||
--
|
||||
[*] --> ScrollLockOff
|
||||
ScrollLockOff --> ScrollLockOn : EvScrollLockPressed
|
||||
ScrollLockOn --> ScrollLockOff : EvScrollLockPressed
|
||||
}
|
||||
state join_state <<join>>
|
||||
State2 --> join_state
|
||||
State3 --> join_state
|
||||
join_state --> State4
|
||||
State4 --> [*]
|
||||
```
|
||||
````
|
||||
|
||||
_Result_:
|
||||
<div class="result" markdown>
|
||||
|
||||
``` mermaid
|
||||
stateDiagram-v2
|
||||
[*] --> Active
|
||||
state fork_state <<fork>>
|
||||
[*] --> fork_state
|
||||
fork_state --> State2
|
||||
fork_state --> State3
|
||||
|
||||
state Active {
|
||||
[*] --> NumLockOff
|
||||
NumLockOff --> NumLockOn : EvNumLockPressed
|
||||
NumLockOn --> NumLockOff : EvNumLockPressed
|
||||
--
|
||||
[*] --> CapsLockOff
|
||||
CapsLockOff --> CapsLockOn : EvCapsLockPressed
|
||||
CapsLockOn --> CapsLockOff : EvCapsLockPressed
|
||||
--
|
||||
[*] --> ScrollLockOff
|
||||
ScrollLockOff --> ScrollLockOn : EvScrollLockPressed
|
||||
ScrollLockOn --> ScrollLockOff : EvScrollLockPressed
|
||||
}
|
||||
state join_state <<join>>
|
||||
State2 --> join_state
|
||||
State3 --> join_state
|
||||
join_state --> State4
|
||||
State4 --> [*]
|
||||
```
|
||||
|
||||
</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
|
||||
```` markdown title="Mermaid.js class diagram"
|
||||
``` 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
|
||||
```` markdown title="Mermaid.js entity-relationship diagram"
|
||||
``` 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
|
||||
|
||||
@ -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_:
|
||||
|
||||
``` markdown
|
||||
``` title="Text with footnote references"
|
||||
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_:
|
||||
|
||||
``` markdown
|
||||
``` title="Footnote"
|
||||
[^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_:
|
||||
|
||||
``` markdown
|
||||
``` title="Footnote"
|
||||
[^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)
|
||||
|
||||
@ -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_:
|
||||
|
||||
``` markdown
|
||||
``` title="Text with suggested changes"
|
||||
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_:
|
||||
|
||||
``` markdown
|
||||
``` title="Text with highlighting"
|
||||
- ==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
|
||||
@ -107,18 +107,18 @@ 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:
|
||||
|
||||
_Example_:
|
||||
|
||||
``` markdown
|
||||
``` markdown title="Text with sub- und superscripts"
|
||||
- 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
|
||||
``` markdown title="Keyboard keys"
|
||||
++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
|
||||
|
||||
@ -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_:
|
||||
|
||||
```
|
||||
- :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`
|
||||
``` title="Icon"
|
||||
:fontawesome-regular-laugh-wink:
|
||||
```
|
||||
|
||||
_Result_:
|
||||
<div class="result" markdown>
|
||||
|
||||
- :material-account-circle: – [`material/account-circle.svg`][icon Material]
|
||||
- :fontawesome-regular-laugh-wink: – [`fontawesome/regular/laugh-wink.svg`][icon FontAwesome]
|
||||
- :octicons-repo-push-16: – [`octicons/repo-push-16.svg`][icon Octicons]
|
||||
:fontawesome-regular-laugh-wink:
|
||||
|
||||
</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
|
||||
suffixing the icon with a special syntax. While HTML allows to use
|
||||
[inline styles], it's always recommended to add an [additional style sheet] and
|
||||
move declarations into dedicated CSS classes.
|
||||
Custom CSS classes can be added to icons by suffixing the icon with a special
|
||||
syntax. While HTML allows to use [inline styles], it's always recommended to
|
||||
add an [additional style sheet] and move declarations into dedicated CSS
|
||||
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
|
||||
- :fontawesome-brands-twitter:{ .twitter } – Twitter
|
||||
- :fontawesome-brands-facebook:{ .facebook } – Facebook
|
||||
``` markdown title="Icon with color"
|
||||
:fontawesome-brands-twitter:{ .twitter }
|
||||
```
|
||||
|
||||
<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.
|
||||
|
||||
_Example_:
|
||||
|
||||
=== ":octicons-file-code-16: docs/example.md"
|
||||
|
||||
``` markdown
|
||||
:octicons-heart-fill-24:{ .heart }
|
||||
```
|
||||
dedicated CSS class to the icon:
|
||||
|
||||
=== ":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
|
||||
|
||||
|
||||
@ -40,13 +40,11 @@ respective alignment directions via the `align` attribute, i.e. `align=left` or
|
||||
|
||||
=== "Left"
|
||||
|
||||
_Example_:
|
||||
|
||||
``` markdown
|
||||
``` markdown title="Image, aligned to left"
|
||||
{ align=left }
|
||||
```
|
||||
|
||||
_Result_:
|
||||
<div class="result" markdown>
|
||||
|
||||
{ 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
|
||||
``` markdown title="Image, aligned to right"
|
||||
{ align=right }
|
||||
```
|
||||
|
||||
_Result_:
|
||||
<div class="result" markdown>
|
||||
|
||||
{ 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
|
||||
can be added to images.
|
||||
but it's always possible to use the [Markdown in HTML] extension with literal
|
||||
`figure` and `figcaption` tags:
|
||||
|
||||
_Example_:
|
||||
|
||||
```html
|
||||
<figure markdown> <!-- (1)! -->
|
||||
``` html title="Image with caption"
|
||||
<figure markdown>
|
||||
{ width="300" }
|
||||
<figcaption>Image caption</figcaption>
|
||||
</figure>
|
||||
```
|
||||
|
||||
1. :man_raising_hand: Remember to enable the [Markdown in HTML] extension.
|
||||
|
||||
_Result_:
|
||||
|
||||
<figure markdown>
|
||||
![Placeholder]{ width="300" }
|
||||
<div class="result">
|
||||
<figure>
|
||||
<img src="https://dummyimage.com/600x400/f5f5f5/aaaaaa&text=–%20Image%20–" width="300" />
|
||||
<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
|
||||
</figure>
|
||||
</div>
|
||||
|
||||
### 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"
|
||||
{ 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
|
||||
``` markdown title="Image, different for light and dark mode"
|
||||
|
||||
|
||||
```
|
||||
|
||||
_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
|
||||
|
||||
@ -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
|
||||
``` markdown title="List, unordered"
|
||||
- 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
|
||||
``` markdown title="List, ordered"
|
||||
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
|
||||
``` markdown title="Definition list"
|
||||
`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
|
||||
``` markdown title="Task list"
|
||||
- [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>
|
||||
|
||||
@ -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
|
||||
``` latex title="MathJax, block syntax"
|
||||
$$
|
||||
\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
|
||||
``` latex title="MathJax, inline syntax"
|
||||
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>
|
||||
|
||||
File diff suppressed because one or more lines are too long
File diff suppressed because one or more lines are too long
15
material/assets/stylesheets/main.b9f2424c.min.css
vendored
Normal file
15
material/assets/stylesheets/main.b9f2424c.min.css
vendored
Normal file
File diff suppressed because one or more lines are too long
1
material/assets/stylesheets/main.b9f2424c.min.css.map
Normal file
1
material/assets/stylesheets/main.b9f2424c.min.css.map
Normal file
File diff suppressed because one or more lines are too long
@ -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 }}">
|
||||
|
||||
@ -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;
|
||||
}
|
||||
|
||||
|
||||
@ -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
|
||||
|
||||
@ -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;
|
||||
|
||||
Loading…
Reference in New Issue
Block a user