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
### Admonition
[:octicons-file-code-24: Source][1] · [:octicons-workflow-24: Extension][2]
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`:
The following configuration enables admonitions, allows to make them collapsible
and to nest arbitrary content inside admonition bodies. Add the following lines
to `mkdocs.yml`:
``` yaml
markdown_extensions:
- 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
```
[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
```
[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
Admonitions follow a simple syntax: a block must start with `!!!`, followed
by a single keyword which is used as the [type qualifier][7] of the block. The
content of the block then follows on the next line, indented by four spaces.
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.
_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.
@ -79,7 +56,7 @@ _Result_:
nulla. Curabitur feugiat, tortor non consequat finibus, justo purus auctor
massa, nec semper lorem quam in massa.
[7]: #supported-types
[type qualifier]: #supported-types
### Changing the title
@ -91,6 +68,7 @@ _Example_:
``` markdown
!!! note "Phasellus posuere in sem ut cursus"
Lorem ipsum dolor sit amet, consectetur adipiscing elit. Nulla et euismod
nulla. Curabitur feugiat, tortor non consequat finibus, justo purus auctor
massa, nec semper lorem quam in massa.
@ -106,14 +84,15 @@ _Result_:
### Removing the title
Similar to [changing the title][8], 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][9].
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].
_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.
@ -127,70 +106,20 @@ _Result_:
nulla. Curabitur feugiat, tortor non consequat finibus, justo purus auctor
massa, nec semper lorem quam in massa.
[8]: #changing-the-title
[9]: #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
[changing the title]: #changing-the-title
[collapsible blocks]: #collapsible-blocks
### Collapsible blocks
The [Details][11] extension adds support for rendering collapsible admonition
blocks. This is useful for FAQs or content that is of secondary nature. A
details block follows the syntax and semantics of admonition blocks, but must
start with `???`.
If the [Details] extension is enabled and an admonition is started with `???`
instead of `!!!`, the admonition is rendered as a collapsible block with a
small marker on the right side.
_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.
@ -204,12 +133,13 @@ _Result_:
nulla. Curabitur feugiat, tortor non consequat finibus, justo purus auctor
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_:
``` 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.
@ -223,23 +153,13 @@ _Result_:
nulla. Curabitur feugiat, tortor non consequat finibus, justo purus auctor
massa, nec semper lorem quam in massa.
[11]: #details
### Inline blocks
[:octicons-file-code-24: Source][12] ·
:octicons-beaker-24: Experimental
Admonitions can also be rendered as inline blocks (i.e. for sidebars), placing
them to the right using the `inline` + `end` modifiers, or to the left using
only the `inline` modifier.
Admonitions and [Details][11] can also be rendered as inline blocks (i.e.
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"
=== ":octicons-arrow-right-16: inline end"
_Example_ / _Result_:
@ -251,6 +171,7 @@ will stretch to the full width of the viewport, e.g. on mobile viewports.
``` markdown
!!! info inline end
Lorem ipsum dolor sit amet, consectetur
adipiscing elit. Nulla et euismod nulla.
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).
=== "inline"
=== ":octicons-arrow-left-16: inline"
_Example_ / _Result_:
@ -272,6 +193,7 @@ will stretch to the full width of the viewport, e.g. on mobile viewports.
``` markdown
!!! info inline
Lorem ipsum dolor sit amet, consectetur
adipiscing elit. Nulla et euismod nulla.
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).
[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
@ -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.
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 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
[:octicons-file-code-24: Source][13] ·
[:octicons-heart-fill-24:{ .mdx-heart } Insiders only][13]{ .mdx-insiders }
> This feature is currently only available in [:octicons-heart-fill-24:{ .mdx-heart } Insiders][Insiders]{ .mdx-insiders }
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
a valid icon in `mkdocs.yml`:
=== "Octicons"
=== ":octicons-mark-github-16: Octicons"
_Example_:
@ -424,10 +348,10 @@ a valid icon in `mkdocs.yml`:
_Result_:
[![Admonition with Octicons icons][14]][14]
[![Admonition with Octicons icons][Octicons]][Octicons]
=== "FontAwesome"
=== ":fontawesome-brands-font-awesome: FontAwesome"
_Example_:
@ -451,19 +375,19 @@ a valid icon in `mkdocs.yml`:
_Result_:
[![Admonition with FontAwesome icons][15]][15]
[![Admonition with FontAwesome icons][FontAwesome]][FontAwesome]
[13]: ../insiders/index.md
[14]: ../assets/screenshots/admonition-octicons.png
[15]: ../assets/screenshots/admonition-fontawesome.png
[Insiders]: ../insiders/index.md
[Octicons]: ../assets/screenshots/admonition-octicons.png
[FontAwesome]: ../assets/screenshots/admonition-fontawesome.png
## Customization
### Custom admonitions
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
following CSS to an [additional stylesheet][17]:
`*.svg` icon. Copy the icon's code from the [`.icons`][Custom icons] folder
and add the following CSS to an [additional stylesheet]:
``` css
: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
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>
:root {
@ -528,6 +452,6 @@ _Result_:
nulla. Curabitur feugiat, tortor non consequat finibus, justo purus auctor
massa, nec semper lorem quam in massa.
[16]: https://github.com/squidfunk/mkdocs-material/tree/master/material/.icons
[17]: ../customization.md#additional-css
[18]: icons-emojis.md#with-animations
[Custom icons]: https://github.com/squidfunk/mkdocs-material/tree/master/material/.icons
[Custom animations]: 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
[: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]
The [SuperFences] extension allows for arbitrary nesting of code and content