diff --git a/docs/writing/admonitions.md b/docs/writing/admonitions.md new file mode 100644 index 000000000..cf96ce115 --- /dev/null +++ b/docs/writing/admonitions.md @@ -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. diff --git a/docs/writing/code-blocks.md b/docs/writing/code-blocks.md index 97eaac122..86e83e76c 100644 --- a/docs/writing/code-blocks.md +++ b/docs/writing/code-blocks.md @@ -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): diff --git a/docs/writing/footnotes.md b/docs/writing/footnotes.md new file mode 100644 index 000000000..4b93299dd --- /dev/null +++ b/docs/writing/footnotes.md @@ -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) diff --git a/mkdocs.yml b/mkdocs.yml index 361b3f59f..97eef01e8 100755 --- a/mkdocs.yml +++ b/mkdocs.yml @@ -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