mirror of
https://github.com/squidfunk/mkdocs-material.git
synced 2024-11-12 01:50:52 +01:00
Added docs on admonition and footnotes
This commit is contained in:
squidfunk
parent
0f1b640c0d
commit
a70b04d1a2
329
docs/writing/admonitions.md
Normal file
329
docs/writing/admonitions.md
Normal file
@ -0,0 +1,329 @@
|
||||
---
|
||||
template: overrides/main.html
|
||||
---
|
||||
|
||||
# Admonitions
|
||||
|
||||
Admonitions, also know as _call-outs_, are an excellent choice for including
|
||||
side content into your project documentation minimally interrupting the document
|
||||
flow. Material for MkDocs provides several types of admonitions and allows for
|
||||
the 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 from
|
||||
`mkdocs.yml`:
|
||||
|
||||
``` yaml
|
||||
markdown_extensions:
|
||||
- admonition
|
||||
```
|
||||
|
||||
[1]: https://github.com/squidfunk/mkdocs-material/blob/master/src/assets/stylesheets/extensions/_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 abilty to make admonitions collapsible. It can be enabled from
|
||||
`mkdocs.yml`:
|
||||
|
||||
``` yaml
|
||||
markdown_extensions:
|
||||
- pymdownx.details
|
||||
```
|
||||
|
||||
[3]: https://github.com/squidfunk/mkdocs-material/blob/master/src/assets/stylesheets/extensions/pymdown/_details.scss
|
||||
[4]: https://facelessuser.github.io/pymdown-extensions/extensions/details/
|
||||
[5]: https://facelessuser.github.io/pymdown-extensions/
|
||||
|
||||
### SuperFences
|
||||
|
||||
[:octicons-file-code-24: Source][6] · [:octicons-workflow-24: Extension][7]
|
||||
|
||||
The [SuperFences][7] extension, which is also part of [Python Markdown
|
||||
Extensions][5], allows for the arbitrary nesting of content inside blocks, and
|
||||
is therefore strongly recommended:
|
||||
|
||||
``` yaml
|
||||
markdown_extensions:
|
||||
- pymdownx.superfences
|
||||
```
|
||||
|
||||
[6]: https://github.com/squidfunk/mkdocs-material/blob/master/src/assets/stylesheets/base/_typeset.scss
|
||||
[7]: https://facelessuser.github.io/pymdown-extensions/extensions/superfences/
|
||||
|
||||
## Usage
|
||||
|
||||
Admonitions follow a simple syntax: a block must start with `!!!`, followed
|
||||
by a single keyword which is used as the [type qualifier][8] of the block. The
|
||||
content of the block then 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.
|
||||
```
|
||||
|
||||
_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.
|
||||
|
||||
[8]: #supported-types
|
||||
|
||||
### Changing the title
|
||||
|
||||
By default, the admonition title will equal the type qualifier in titlecase.
|
||||
However, it can be changed to a custom string by adding a quoted string after
|
||||
the type qualifier.
|
||||
|
||||
_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.
|
||||
```
|
||||
|
||||
_Result_:
|
||||
|
||||
!!! 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.
|
||||
|
||||
### Removing the title
|
||||
|
||||
Similar to [changing the title][9], the icon and title can be omitted by adding
|
||||
an empty string directly after the type qualifier.
|
||||
|
||||
_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.
|
||||
```
|
||||
|
||||
_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.
|
||||
|
||||
[9]: #changing-the-title
|
||||
|
||||
### 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 code 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
|
||||
|
||||
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 `???`.
|
||||
|
||||
_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.
|
||||
```
|
||||
|
||||
_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.
|
||||
|
||||
Adding a `+` after `???` will render the block open on page load:
|
||||
|
||||
_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.
|
||||
```
|
||||
|
||||
_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.
|
||||
|
||||
[11]: #details
|
||||
|
||||
### Supported types
|
||||
|
||||
Following is a list of type qualifiers provided by Material for MkDocs, whereas
|
||||
the default type, and thus fallback for unknown type qualifiers, is `note`:
|
||||
|
||||
`note`, `seealso`
|
||||
|
||||
: !!! 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.
|
||||
|
||||
`abstract`, `summary`, `tldr`
|
||||
|
||||
: !!! abstract
|
||||
|
||||
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.
|
||||
|
||||
`info`, `todo`
|
||||
|
||||
: !!! info
|
||||
|
||||
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.
|
||||
|
||||
`tip`, `hint`, `important`
|
||||
|
||||
: !!! tip
|
||||
|
||||
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.
|
||||
|
||||
`success`, `check`, `done`
|
||||
|
||||
: !!! success
|
||||
|
||||
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.
|
||||
|
||||
`question`, `help`, `faq`
|
||||
|
||||
: !!! question
|
||||
|
||||
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.
|
||||
|
||||
`warning`, `caution`, `attention`
|
||||
|
||||
: !!! warning
|
||||
|
||||
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.
|
||||
|
||||
`failure`, `fail`, `missing`
|
||||
|
||||
: !!! failure
|
||||
|
||||
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.
|
||||
|
||||
`danger`, `error`
|
||||
|
||||
: !!! danger
|
||||
|
||||
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.
|
||||
|
||||
`bug`
|
||||
|
||||
: !!! bug
|
||||
|
||||
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.
|
||||
|
||||
`example`
|
||||
|
||||
: !!! example
|
||||
|
||||
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.
|
||||
|
||||
`quote`, `cite`
|
||||
|
||||
: !!! quote
|
||||
|
||||
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.
|
||||
@ -137,7 +137,7 @@ See the section on [inline code blocks][11] for usage information.
|
||||
|
||||
This section discusses how to use different syntax highlighting features with
|
||||
[Pygments][1] – the default highlighter – so they don't apply when using
|
||||
a JavaScript syntaxhighlighter.
|
||||
a JavaScript syntax highlighter.
|
||||
|
||||
### Specifying the language
|
||||
|
||||
@ -173,7 +173,6 @@ _Example_:
|
||||
|
||||
```` markdown
|
||||
``` python linenums="1"
|
||||
""" Bubble sort """
|
||||
def bubble_sort(items):
|
||||
for i in range(len(items)):
|
||||
for j in range(len(items) - 1 - i):
|
||||
@ -185,7 +184,6 @@ def bubble_sort(items):
|
||||
_Result_:
|
||||
|
||||
``` python linenums="1"
|
||||
""" Bubble sort """
|
||||
def bubble_sort(items):
|
||||
for i in range(len(items)):
|
||||
for j in range(len(items) - 1 - i):
|
||||
@ -202,8 +200,7 @@ at `1`, regardless of the starting line number specified as part of `linenums`.
|
||||
_Example_:
|
||||
|
||||
```` markdown
|
||||
``` python hl_lines="3 4"
|
||||
""" Bubble sort """
|
||||
``` python hl_lines="2 3"
|
||||
def bubble_sort(items):
|
||||
for i in range(len(items)):
|
||||
for j in range(len(items) - 1 - i):
|
||||
@ -214,8 +211,7 @@ def bubble_sort(items):
|
||||
|
||||
_Result_:
|
||||
|
||||
``` python linenums="1" hl_lines="3 4"
|
||||
""" Bubble sort """
|
||||
``` python linenums="1" hl_lines="2 3"
|
||||
def bubble_sort(items):
|
||||
for i in range(len(items)):
|
||||
for j in range(len(items) - 1 - i):
|
||||
|
||||
91
docs/writing/footnotes.md
Normal file
91
docs/writing/footnotes.md
Normal file
@ -0,0 +1,91 @@
|
||||
---
|
||||
template: overrides/main.html
|
||||
---
|
||||
|
||||
# Footnotes
|
||||
|
||||
Footnotes are a great way to add references to supplemental or additional
|
||||
information for a specific section of a document without interrupting the
|
||||
document flow. Material for MkDocs provides the ability to insert inline
|
||||
footnotes and render them at the bottom of the page.
|
||||
|
||||
## Configuration
|
||||
|
||||
### Footnotes
|
||||
|
||||
[:octicons-file-code-24: Source][1] · [:octicons-workflow-24: Extension][2]
|
||||
|
||||
The [Footnotes][1] extension, which is part of the standard Markdown library,
|
||||
adds the ability to add inline footnotes to a document and can be enabled from
|
||||
`mkdocs.yml`:
|
||||
|
||||
``` yaml
|
||||
markdown_extensions:
|
||||
- footnotes
|
||||
```
|
||||
|
||||
[1]: https://github.com/squidfunk/mkdocs-material/blob/master/src/assets/stylesheets/extensions/_footnotes.scss
|
||||
[2]: https://python-markdown.github.io/extensions/footnotes/
|
||||
|
||||
## Usage
|
||||
|
||||
### Adding footnote references
|
||||
|
||||
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
|
||||
Lorem ipsum[^1] dolor sit amet, consectetur adipiscing elit.[^2]
|
||||
```
|
||||
|
||||
_Result_:
|
||||
|
||||
Lorem ipsum[^1] dolor sit amet, consectetur adipiscing elit.[^2]
|
||||
|
||||
### Adding footnote content
|
||||
|
||||
The footnote content must be declared with the same identifier as the reference.
|
||||
It can be inserted at an arbitrary position in the document and is always
|
||||
rendered at the bottom of the page. Furthermore, a backlink to the footnote
|
||||
reference is automatically added.
|
||||
|
||||
#### on a single line
|
||||
|
||||
Short statements can be written on the same line.
|
||||
|
||||
_Example_:
|
||||
|
||||
``` markdown
|
||||
[^1]: Lorem ipsum dolor sit amet, consectetur adipiscing elit.
|
||||
```
|
||||
|
||||
_Result_:
|
||||
|
||||
[Jump to footnote at the bottom of the page](#fn:1)
|
||||
|
||||
[^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.
|
||||
|
||||
_Example_:
|
||||
|
||||
``` markdown
|
||||
[^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_:
|
||||
|
||||
[^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.
|
||||
|
||||
[Jump to footnote at the bottom of the page](#fn:2)
|
||||
@ -132,7 +132,9 @@ nav:
|
||||
- Troubleshooting: troubleshooting.md
|
||||
- Data privacy: data-privacy.md
|
||||
- Writing:
|
||||
- Admonitions: writing/admonitions.md
|
||||
- Code blocks: writing/code-blocks.md
|
||||
- Footnotes: writing/footnotes.md
|
||||
- Guides:
|
||||
- Changing colors: guides/changing-colors.md
|
||||
- Changing the fonts: guides/changing-the-fonts.md
|
||||
|
||||
Loading…
Reference in New Issue
Block a user