Prepare 8.1.6 release

Author: squidfunk

CHANGELOG

@@ -1,3 +1,13 @@
+mkdocs-material-8.1.6-insiders-4.6.0 (2022-01-11)
+
+  * Added support for annotations (outside of code blocks)
+
+mkdocs-material-8.1.6 (2022-01-11)
+
+  * Fixed spacing of blockquotes (8.1.5 regression)
+  * Fixed edge cases for rounded corners on code blocks (8.1.5 regression)
+  * Fixed rendering issues with code annotation line heights
+
 mkdocs-material-8.1.5 (2022-01-09)
 
   * Improved browser support: Chrome 49+, Safari 10+, Firefox 53+, Edge 79+

docs/changelog/index.md

@@ -6,6 +6,12 @@ template: overrides/main.html
 
 ## Material for MkDocs
 
+### 8.1.6 <small>_ January 11, 2022</small> { id="8.1.6" }
+
+- Fixed spacing of blockquotes (8.1.5 regression)
+- Fixed edge cases for rounded corners on code blocks (8.1.5 regression)
+- Fixed issues with code annotation line heights
+
 ### 8.1.5 <small>_ January 9, 2022</small> { id="8.1.5" }
 
 - Improved browser support: Chrome 49+, Safari 10+, Firefox 53+, Edge 79+

docs/insiders/changelog.md

@@ -6,6 +6,10 @@ template: overrides/main.html
 
 ## Material for MkDocs Insiders
 
+### 4.6.0 <small>_ January 11, 2022</small> { id="4.6.0" }
+
+- Added support for annotations (outside of code blocks)
+
 ### 4.5.2 <small>_ January 8, 2022</small> { id="4.5.2" }
 
 - Fixed #3440: Content tab indicator not moving when using linking

docs/insiders/index.md

@@ -162,9 +162,10 @@ The following features are solely available via Material for MkDocs Insiders:
 
 <div class="mdx-columns" markdown>
 
+- [x] [Annotations] :material-new-box:
 - [x] [Navigation icons] :material-new-box:
-- [x] [Code annotations: anchor links] :material-new-box:
-- [x] [Code annotations: strip comments] :material-new-box:
+- [x] [Code annotations: anchor links]
+- [x] [Code annotations: strip comments]
 - [x] [Dismissable announcement bar]
 - [x] [Was this page helpful?]
 - [x] [Brand new search plugin]
@@ -251,12 +252,13 @@ are released for general availability.
 
 #### $ 12,000 – Piri Piri
 
+- [x] [Annotations]
 - [x] [Navigation icons]
 - [ ] Navigation status badges
 - [ ] Navigation pruning
-- [ ] Text annotations
 - [ ] Blog
 
+  [Annotations]: ../reference/annotations.md
   [Navigation icons]: ../reference/index.md#setting-the-page-icon
 
 ### Goals completed

docs/reference/annotations.md

@@ -0,0 +1,204 @@
+---
+template: overrides/main.html
+icon: material/plus-circle
+---
+
+# Annotations
+
+One of the flagship features of Material for MkDocs is the ability to inject
+annotations – little markers that can be added almost anywhere in a document
+and expand a tooltip containing arbitrary Markdown on click or keyboard focus.
+
+## Configuration
+
+This configuration allows to add annotations to all inline- and block-level
+elements, as well as code blocks, and nest annotations inside each other. Add
+the following lines to `mkdocs.yml`:
+
+``` yaml
+markdown_extensions:
+  - attr_list
+  - md_in_html
+  - pymdownx.superfences
+```
+
+See additional configuration options:
+
+- [Attribute Lists]
+- [Markdown in HTML]
+- [SuperFences]
+
+  [Attribute Lists]: ../setup/extensions/python-markdown.md#attribute-lists
+  [Markdown in HTML]: ../setup/extensions/python-markdown.md#markdown-in-html
+  [SuperFences]: ../setup/extensions/python-markdown-extensions.md#superfences
+
+## Usage
+
+### Using annotations
+
+[:octicons-heart-fill-24:{ .mdx-heart } Insiders][Insiders]{ .mdx-insiders } ·
+[:octicons-tag-24: insiders-4.6.0][Insiders] ·
+:octicons-beaker-24: Experimental
+
+Annotations consist of two parts: a marker, which can be placed anywhere in
+a block marked with the `annotate` class, and content located in a list below
+the block containing the marker:
+
+``` markdown title="Text with annotations"
+Lorem ipsum dolor sit amet, (1) consectetur adipiscing elit.
+{ .annotate }
+
+1.  :man_raising_hand: I'm an annotation! I can contain `code`, __formatted
+    text__, images, ... basically anything that can be expressed in Markdown.
+```
+
+<div class="result" markdown>
+
+Lorem ipsum dolor sit amet, (1) consectetur adipiscing elit.
+{ .annotate }
+
+1.  :man_raising_hand: I'm an annotation! I can contain `code`, __formatted
+    text__, images, ... basically anything that can be written in Markdown.
+
+</div>
+
+Note that the `annotate` class must only be added to the outermost block. All
+nested elements can use the same list to define annotations, except when
+annotations are nested themselves.
+
+  [Insiders]: ../insiders/index.md
+
+#### in annotations
+
+When [SuperFences] is enabled, annotations can be nested inside annotations by
+adding the `annotate` class to the list item hosting the annotation content,
+repeating the process:
+
+``` markdown title="Text with nested annotations"
+Lorem ipsum dolor sit amet, (1) consectetur adipiscing elit.
+{ .annotate }
+
+1.  :man_raising_hand: I'm an annotation! (1)
+    { .annotate }
+
+    1.  :woman_raising_hand: I'm an annotation as well!
+```
+
+<div class="result" markdown>
+
+Lorem ipsum dolor sit amet, (1) consectetur adipiscing elit.
+{ .annotate }
+
+1.  :man_raising_hand: I'm an annotation! (1)
+    { .annotate style="margin-bottom: 0" }
+
+    1.  :woman_raising_hand: I'm an annotation as well!
+
+</div>
+
+#### in admonitions
+
+The titles and bodies of [admonitions] can also host annotations by adding the
+`annotate` modifier after the type qualifier, which is similar to how
+[inline blocks] work:
+
+``` markdown title="Admonition with annotations"
+!!! note annotate "Phasellus posuere in sem ut cursus (1)"
+
+    Lorem ipsum dolor sit amet, (2) consectetur adipiscing elit. Nulla et
+    euismod nulla. Curabitur feugiat, tortor non consequat finibus, justo
+    purus auctor massa, nec semper lorem quam in massa.
+
+1.  :man_raising_hand: I'm an annotation!
+2.  :woman_raising_hand: I'm an annotation as well!
+```
+
+<div class="result" markdown>
+
+!!! note annotate "Phasellus posuere in sem ut cursus (1)"
+
+    Lorem ipsum dolor sit amet, (2) consectetur adipiscing elit. Nulla et
+    euismod nulla. Curabitur feugiat, tortor non consequat finibus, justo
+    purus auctor massa, nec semper lorem quam in massa.
+
+1.  :man_raising_hand: I'm an annotation!
+2.  :woman_raising_hand: I'm an annotation as well!
+
+</div>
+
+  [admonitions]: admonitions.md
+  [inline blocks]: admonitions.md#inline-blocks
+
+#### in content tabs
+
+Content tabs can host annotations by adding the `annotate` class to the block
+of a dedicated content tab (and not to the container, which is not supported):
+
+``` markdown title="Content tabs with annotations"
+=== "Tab 1"
+
+    Lorem ipsum dolor sit amet, (1) consectetur adipiscing elit.
+    { .annotate }
+
+    1.  :man_raising_hand: I'm an annotation!
+
+=== "Tab 2"
+
+    Phasellus posuere in sem ut cursus (1)
+    { .annotate }
+
+    1.  :woman_raising_hand: I'm an annotation as well!
+```
+
+<div class="result" markdown>
+
+=== "Tab 1"
+
+    Lorem ipsum dolor sit amet, (1) consectetur adipiscing elit.
+    { .annotate }
+
+    1.  :man_raising_hand: I'm an annotation!
+
+=== "Tab 2"
+
+    Phasellus posuere in sem ut cursus (1)
+    { .annotate }
+
+    1.  :woman_raising_hand: I'm an annotation as well!
+
+</div>
+
+#### in everything else
+
+The [Attribute Lists] extension is the key ingredient for adding annotations to 
+most elements, but it has some [limitations]. However, it's always possible to
+leverage the [Markdown in HTML] extension to wrap arbitrary elements with a
+`div` with the `annotate` class:
+
+```` html title="HTML with annotations"
+<div class="annotate" markdown>
+
+> Lorem ipsum dolor sit amet, (1) consectetur adipiscing elit.
+
+</div>
+
+1.  :man_raising_hand: I'm an annotation!
+````
+
+<div class="result" markdown>
+  <div class="annotate" markdown>
+
+> Lorem ipsum dolor sit amet, (1) consectetur adipiscing elit.
+
+  </div>
+
+1.  :man_raising_hand: I'm an annotation!
+
+</div>
+
+With this trick, annotations can also be added to blockquotes, data tables,
+lists, and many other elements that are not supported by the [Attribute Lists]
+extension. Furthermore, note that [code blocks follow different semantics].
+
+  [limitations]: https://python-markdown.github.io/extensions/attr_list/#limitations
+  [code blocks follow different semantics]: code-blocks.md#adding-annotations

docs/reference/data-tables.md

@@ -63,7 +63,7 @@ and/or end of the divider.
 
 === "Left"
 
-    ``` markdown hl_lines="2" title="Data table, aligned to left"
+    ``` markdown hl_lines="2" title="Data table, columns aligned to left"
     | Method      | Description                          |
     | :---------- | :----------------------------------- |
     | `GET`       | :material-check:     Fetch resource  |
@@ -83,7 +83,7 @@ and/or end of the divider.
 
 === "Center"
 
-    ``` markdown hl_lines="2" title="Data table, centered"
+    ``` markdown hl_lines="2" title="Data table, columns centered"
     | Method      | Description                          |
     | :---------: | :----------------------------------: |
     | `GET`       | :material-check:     Fetch resource  |
@@ -103,7 +103,7 @@ and/or end of the divider.
 
 === "Right"
 
-    ``` markdown hl_lines="2" title="Data table, aligned to right"
+    ``` markdown hl_lines="2" title="Data table, columns aligned to right"
     | Method      | Description                          |
     | ----------: | -----------------------------------: |
     | `GET`       | :material-check:     Fetch resource  |
@@ -153,7 +153,7 @@ loading] via [additional JavaScript]:
 After applying the customization, data tables can be sorted by clicking on a
 column:
 
-``` markdown title="Data table"
+``` markdown title="Data table, columns sortable"
 | Method      | Description                          |
 | ----------- | ------------------------------------ |
 | `GET`       | :material-check:     Fetch resource  |

docs/reference/diagrams.md

@@ -56,7 +56,7 @@ No further configuration is necessary. Advantages over a custom integration:
 are rendered as nodes of various kinds and are connected by edges, describing
 the necessary order of steps:
 
-```` markdown title="Mermaid.js flow chart"
+```` markdown title="Flow chart"
 ``` mermaid
 graph LR
   A[Start] --> B{Error?};
@@ -88,7 +88,7 @@ graph LR
 between multiple objects or actors, including the messages that are exchanged
 between those actors:
 
-```` markdown title="Mermaid.js sequence diagram"
+```` markdown title="Sequence diagram"
 ``` mermaid
 sequenceDiagram
   Alice->>John: Hello John, how are you?
@@ -126,7 +126,7 @@ sequenceDiagram
 decomposing it into a finite number of states, and transitions between those
 states:
 
-```` markdown title="Mermaid.js state diagram"
+```` markdown title="State diagram"
 ``` mermaid
 stateDiagram-v2
   state fork_state <<fork>>
@@ -168,7 +168,7 @@ stateDiagram-v2
 structure of a system by modelling entities as classes and relationships between
 them:
 
-```` markdown title="Mermaid.js class diagram"
+```` markdown title="Class diagram"
 ``` mermaid
 classDiagram
   Person <|-- Student
@@ -240,7 +240,7 @@ An [entity-relationship diagram] is composed of entity types and specifies
 relationships that exist between entities. It describes inter-related things in
 a specific domain of knowledge:
 
-```` markdown title="Mermaid.js entity-relationship diagram"
+```` markdown title="Entity-relationship diagram"
 ``` mermaid
 erDiagram
   CUSTOMER ||--o{ ORDER : places

docs/setup/extensions/python-markdown-extensions.md

@@ -604,6 +604,7 @@ them at your own risk.
 
 See reference for usage:
 
+- [Annotations]
 - [Using flowcharts]
 - [Using sequence diagrams]
 - [Using state diagrams]
@@ -615,6 +616,7 @@ See reference for usage:
   [Fenced Code Blocks]: python-markdown.md#fenced-code-blocks
   [Mermaid.js]: https://mermaid-js.github.io/mermaid/
   [diagrams]: ../../reference/diagrams.md
+  [Annotations]: ../../reference/annotations.md
   [Using flowcharts]: ../../reference/diagrams.md#using-flowcharts
   [Using sequence diagrams]: ../../reference/diagrams.md#using-sequence-diagrams
   [Using state diagrams]: ../../reference/diagrams.md#using-state-diagrams