OpenSourceArk/mkdocs-material
1
0
Fork 0
mirror of https://github.com/squidfunk/mkdocs-material.git synced 2024-06-14 11:52:32 +03:00
Code Issues Packages Projects Releases Wiki Activity

Updated Admonition documentation

Browse Source
This commit is contained in:
squidfunk 2021-10-03 15:32:50 +02:00
parent 8e527be8b2
commit b8becde3bb
2 changed files with 58 additions and 134 deletions
Show Stats Download Patch File Download Diff File Expand all files Collapse all files

190
docs/reference/admonitions.md
View File

@ -11,61 +11,38 @@ inclusion and nesting of arbitrary content.
## Configuration ## Configuration
### Admonition The following configuration enables admonitions, allows to make them collapsible
and to nest arbitrary content inside admonition bodies. Add the following lines
[:octicons-file-code-24: Source][1] · [:octicons-workflow-24: Extension][2] to `mkdocs.yml`:
The [Admonition][2] extension, which is part of the standard Markdown
library, is integrated with Material for MkDocs and can be enabled via
`mkdocs.yml`:
``` yaml ``` yaml
markdown_extensions: markdown_extensions:
- admonition - admonition
```
[1]: https://github.com/squidfunk/mkdocs-material/blob/master/src/assets/stylesheets/main/extensions/markdown/_admonition.scss
[2]: https://python-markdown.github.io/extensions/admonition/
### Details
[:octicons-file-code-24: Source][3] · [:octicons-workflow-24: Extension][4]
The [Details][4] extension, which is part of [Python Markdown Extensions][5],
adds the ability to __make admonitions collapsible__. It can be enabled via
`mkdocs.yml`:
``` yaml
markdown_extensions:
- pymdownx.details - pymdownx.details
```
[3]: https://github.com/squidfunk/mkdocs-material/blob/master/src/assets/stylesheets/main/extensions/pymdownx/_details.scss
[4]: https://facelessuser.github.io/pymdown-extensions/extensions/details/
[5]: https://facelessuser.github.io/pymdown-extensions/
### SuperFences
The [SuperFences][6] extension, which is also part of [Python Markdown
Extensions][5], allows for the __nesting of code and content blocks inside
admonitions__, and is therefore strongly recommended:
``` yaml
markdown_extensions:
- pymdownx.superfences - pymdownx.superfences
``` ```
[6]: https://facelessuser.github.io/pymdown-extensions/extensions/superfences/
See additional configuration options:
- [Admonition]
- [Details]
- [SuperFences]
[Admonition]: ../setup/extensions/python-markdown.md#admonition
[Details]: ../setup/extensions/python-markdown-extensions.md#details
[SuperFences]: ../setup/extensions/python-markdown-extensions.md#superfences
## Usage ## Usage
Admonitions follow a simple syntax: a block must start with `!!!`, followed Admonitions follow a simple syntax: a block starts with `!!!`, followed by a
by a single keyword which is used as the [type qualifier][7] of the block. The single keyword used as a [type qualifier]. The content of the block follows on
content of the block then follows on the next line, indented by four spaces. the next line, indented by four spaces.
_Example_: _Example_:
``` markdown ``` markdown
!!! note !!! note
Lorem ipsum dolor sit amet, consectetur adipiscing elit. Nulla et euismod Lorem ipsum dolor sit amet, consectetur adipiscing elit. Nulla et euismod
nulla. Curabitur feugiat, tortor non consequat finibus, justo purus auctor nulla. Curabitur feugiat, tortor non consequat finibus, justo purus auctor
massa, nec semper lorem quam in massa. massa, nec semper lorem quam in massa.
@ -79,7 +56,7 @@ _Result_:
nulla. Curabitur feugiat, tortor non consequat finibus, justo purus auctor nulla. Curabitur feugiat, tortor non consequat finibus, justo purus auctor
massa, nec semper lorem quam in massa. massa, nec semper lorem quam in massa.
[7]: #supported-types [type qualifier]: #supported-types
### Changing the title ### Changing the title
@ -91,6 +68,7 @@ _Example_:
``` markdown ``` markdown
!!! note "Phasellus posuere in sem ut cursus" !!! note "Phasellus posuere in sem ut cursus"
Lorem ipsum dolor sit amet, consectetur adipiscing elit. Nulla et euismod Lorem ipsum dolor sit amet, consectetur adipiscing elit. Nulla et euismod
nulla. Curabitur feugiat, tortor non consequat finibus, justo purus auctor nulla. Curabitur feugiat, tortor non consequat finibus, justo purus auctor
massa, nec semper lorem quam in massa. massa, nec semper lorem quam in massa.
@ -106,14 +84,15 @@ _Result_:
### Removing the title ### Removing the title
Similar to [changing the title][8], the icon and title can be omitted entirely Similar to [changing the title], the icon and title can be omitted entirely by
by adding an empty string directly after the type qualifier. Note that this adding an empty string directly after the type qualifier. Note that this will
will not work for [collapsible blocks][9]. not work for [collapsible blocks].
_Example_: _Example_:
``` markdown ``` markdown
!!! note "" !!! note ""
Lorem ipsum dolor sit amet, consectetur adipiscing elit. Nulla et euismod Lorem ipsum dolor sit amet, consectetur adipiscing elit. Nulla et euismod
nulla. Curabitur feugiat, tortor non consequat finibus, justo purus auctor nulla. Curabitur feugiat, tortor non consequat finibus, justo purus auctor
massa, nec semper lorem quam in massa. massa, nec semper lorem quam in massa.
@ -127,70 +106,20 @@ _Result_:
nulla. Curabitur feugiat, tortor non consequat finibus, justo purus auctor nulla. Curabitur feugiat, tortor non consequat finibus, justo purus auctor
massa, nec semper lorem quam in massa. massa, nec semper lorem quam in massa.
[8]: #changing-the-title [changing the title]: #changing-the-title
[9]: #collapsible-blocks [collapsible blocks]: #collapsible-blocks
### Embedded content
Admonitions can contain all kinds of text content, including headlines, lists,
paragraphs and other blocks. While the parser from the standard Markdown library
doesn't account for nested blocks, the [SuperFences][10] extension adds the
ability to nest arbitrary content inside admonitions.
_Example_:
``` 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.
``` python
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]
```
Nunc eu odio eleifend, blandit leo a, volutpat sapien. Phasellus posuere in
sem ut cursus. Nullam sit amet tincidunt ipsum, sit amet elementum turpis.
Etiam ipsum quam, mattis in purus vitae, lacinia fermentum enim.
```
_Result_:
!!! 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.
``` python
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]
```
Nunc eu odio eleifend, blandit leo a, volutpat sapien. Phasellus posuere in
sem ut cursus. Nullam sit amet tincidunt ipsum, sit amet elementum turpis.
Etiam ipsum quam, mattis in purus vitae, lacinia fermentum enim.
[10]: #superfences
### Collapsible blocks ### Collapsible blocks
The [Details][11] extension adds support for rendering collapsible admonition If the [Details] extension is enabled and an admonition is started with `???`
blocks. This is useful for FAQs or content that is of secondary nature. A instead of `!!!`, the admonition is rendered as a collapsible block with a
details block follows the syntax and semantics of admonition blocks, but must small marker on the right side.
start with `???`.
_Example_: _Example_:
``` markdown ``` markdown
??? note ??? note
Lorem ipsum dolor sit amet, consectetur adipiscing elit. Nulla et euismod Lorem ipsum dolor sit amet, consectetur adipiscing elit. Nulla et euismod
nulla. Curabitur feugiat, tortor non consequat finibus, justo purus auctor nulla. Curabitur feugiat, tortor non consequat finibus, justo purus auctor
massa, nec semper lorem quam in massa. massa, nec semper lorem quam in massa.
@ -204,12 +133,13 @@ _Result_:
nulla. Curabitur feugiat, tortor non consequat finibus, justo purus auctor nulla. Curabitur feugiat, tortor non consequat finibus, justo purus auctor
massa, nec semper lorem quam in massa. massa, nec semper lorem quam in massa.
Adding a `+` after `???` will render the block as open on page load: Adding a `+` after the `???` token will render the block as open.
_Example_: _Example_:
``` markdown ``` markdown
???+ note ???+ note
Lorem ipsum dolor sit amet, consectetur adipiscing elit. Nulla et euismod Lorem ipsum dolor sit amet, consectetur adipiscing elit. Nulla et euismod
nulla. Curabitur feugiat, tortor non consequat finibus, justo purus auctor nulla. Curabitur feugiat, tortor non consequat finibus, justo purus auctor
massa, nec semper lorem quam in massa. massa, nec semper lorem quam in massa.
@ -223,23 +153,13 @@ _Result_:
nulla. Curabitur feugiat, tortor non consequat finibus, justo purus auctor nulla. Curabitur feugiat, tortor non consequat finibus, justo purus auctor
massa, nec semper lorem quam in massa. massa, nec semper lorem quam in massa.
[11]: #details
### Inline blocks ### Inline blocks
[:octicons-file-code-24: Source][12] · Admonitions can also be rendered as inline blocks (i.e. for sidebars), placing
:octicons-beaker-24: Experimental them to the right using the `inline` + `end` modifiers, or to the left using
only the `inline` modifier.
Admonitions and [Details][11] can also be rendered as inline blocks (i.e. === ":octicons-arrow-right-16: inline end"
sidebars), placing them to the right using the `inline` + `end` modifiers, or
to the left using only the `inline` modifier.
__Important__: Admonitions that use the `inline` modifiers _must_ be declared
prior to the content block you want to place them beside. If there's
insufficient space to render the admonition next to the block, the admonition
will stretch to the full width of the viewport, e.g. on mobile viewports.
=== "inline end"
_Example_ / _Result_: _Example_ / _Result_:
@ -251,6 +171,7 @@ will stretch to the full width of the viewport, e.g. on mobile viewports.
``` markdown ``` markdown
!!! info inline end !!! info inline end
Lorem ipsum dolor sit amet, consectetur Lorem ipsum dolor sit amet, consectetur
adipiscing elit. Nulla et euismod nulla. adipiscing elit. Nulla et euismod nulla.
Curabitur feugiat, tortor non consequat Curabitur feugiat, tortor non consequat
@ -260,7 +181,7 @@ will stretch to the full width of the viewport, e.g. on mobile viewports.
Use `inline end` to align to the right (left for rtl languages). Use `inline end` to align to the right (left for rtl languages).
=== "inline" === ":octicons-arrow-left-16: inline"
_Example_ / _Result_: _Example_ / _Result_:
@ -272,6 +193,7 @@ will stretch to the full width of the viewport, e.g. on mobile viewports.
``` markdown ``` markdown
!!! info inline !!! info inline
Lorem ipsum dolor sit amet, consectetur Lorem ipsum dolor sit amet, consectetur
adipiscing elit. Nulla et euismod nulla. adipiscing elit. Nulla et euismod nulla.
Curabitur feugiat, tortor non consequat Curabitur feugiat, tortor non consequat
@ -281,7 +203,10 @@ will stretch to the full width of the viewport, e.g. on mobile viewports.
Use `inline` to align to the left (right for rtl languages). Use `inline` to align to the left (right for rtl languages).
[12]: https://github.com/squidfunk/mkdocs-material/blob/master/src/assets/stylesheets/main/_modifiers.scss __Important__: Admonitions that use the `inline` modifiers _must_ be declared
prior to the content block you want to place them beside. If there's
insufficient space to render the admonition next to the block, the admonition
will stretch to the full width of the viewport, e.g. on mobile viewports.
### Supported types ### Supported types
@ -389,18 +314,17 @@ the default type, and thus fallback for unknown type qualifiers, is `note`:
in order to make it easier for authors to migrate to Material for MkDocs. in order to make it easier for authors to migrate to Material for MkDocs.
However, when the title is omitted, the admonition extension will render it However, when the title is omitted, the admonition extension will render it
as `Seealso`, which is incorrect English. For this reason, it was deprecated as `Seealso`, which is incorrect English. For this reason, it was deprecated
as of 7.1.5 and will be removed in 8.x. in :octicons-tag-24: 7.1.5 and will be removed in :octicons-tag-24: 8.0.0.
### Changing the icons ### Changing the icons
[:octicons-file-code-24: Source][13] · > This feature is currently only available in [:octicons-heart-fill-24:{ .mdx-heart } Insiders][Insiders]{ .mdx-insiders }
[:octicons-heart-fill-24:{ .mdx-heart } Insiders only][13]{ .mdx-insiders }
Each of the supported admonition types has a distinct icon, which can be changed Each of the supported admonition types has a distinct icon, which can be changed
to any icon bundled with the theme. Just set the name of the admonition type to to any icon bundled with the theme. Just set the name of the admonition type to
a valid icon in `mkdocs.yml`: a valid icon in `mkdocs.yml`:
=== "Octicons" === ":octicons-mark-github-16: Octicons"
_Example_: _Example_:
@ -424,10 +348,10 @@ a valid icon in `mkdocs.yml`:
_Result_: _Result_:
[![Admonition with Octicons icons][14]][14] [![Admonition with Octicons icons][Octicons]][Octicons]
=== "FontAwesome" === ":fontawesome-brands-font-awesome: FontAwesome"
_Example_: _Example_:
@ -451,19 +375,19 @@ a valid icon in `mkdocs.yml`:
_Result_: _Result_:
[![Admonition with FontAwesome icons][15]][15] [![Admonition with FontAwesome icons][FontAwesome]][FontAwesome]
[13]: ../insiders/index.md [Insiders]: ../insiders/index.md
[14]: ../assets/screenshots/admonition-octicons.png [Octicons]: ../assets/screenshots/admonition-octicons.png
[15]: ../assets/screenshots/admonition-fontawesome.png [FontAwesome]: ../assets/screenshots/admonition-fontawesome.png
## Customization ## Customization
### Custom admonitions ### Custom admonitions
If you want to add a custom admonition type, all you need is a color and an If you want to add a custom admonition type, all you need is a color and an
`svg` icon. Copy the icon's `svg` code from the [`.icons`][16] folder and add the `*.svg` icon. Copy the icon's code from the [`.icons`][Custom icons] folder
following CSS to an [additional stylesheet][17]: and add the following CSS to an [additional stylesheet]:
``` css ``` css
:root { :root {
@ -488,7 +412,7 @@ following CSS to an [additional stylesheet][17]:
You should now be able to create an admonition of the `pied-piper` type. Note You should now be able to create an admonition of the `pied-piper` type. Note
that you can also use this technique to override existing admonition icons or that you can also use this technique to override existing admonition icons or
colors. [You can even add animations][18]. colors. [You can even add animations][Custom animations].
<style> <style>
:root { :root {
@ -528,6 +452,6 @@ _Result_:
nulla. Curabitur feugiat, tortor non consequat finibus, justo purus auctor nulla. Curabitur feugiat, tortor non consequat finibus, justo purus auctor
massa, nec semper lorem quam in massa. massa, nec semper lorem quam in massa.
[16]: https://github.com/squidfunk/mkdocs-material/tree/master/material/.icons [Custom icons]: https://github.com/squidfunk/mkdocs-material/tree/master/material/.icons
[17]: ../customization.md#additional-css [Custom animations]: icons-emojis.md#with-animations
[18]: icons-emojis.md#with-animations [additional stylesheet]: ../customization.md#additional-css

2
docs/setup/extensions/python-markdown-extensions.md
View File

@ -532,7 +532,7 @@ See reference for usage:
### SuperFences ### SuperFences
[:octicons-workflow-24: Extension][SuperFences] · [:octicons-workflow-24: Extension][SuperFences] ·
[:octicons-tag-24: 5.0.0 ... present][SuperFences support] · [:octicons-tag-24: 0.1.0 ... present][SuperFences support] ·
:octicons-zap-24: Supersedes [Fenced Code Blocks] :octicons-zap-24: Supersedes [Fenced Code Blocks]
The [SuperFences] extension allows for arbitrary nesting of code and content The [SuperFences] extension allows for arbitrary nesting of code and content