Added docs on admonition and footnotes

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.

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"
+``` python hl_lines="2 3"
-""" Bubble sort """
 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"
+``` python linenums="1" hl_lines="2 3"
-""" Bubble sort """
 def bubble_sort(items):
     for i in range(len(items)):
         for j in range(len(items) - 1 - i):

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)

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