diff --git a/CHANGELOG b/CHANGELOG index dd81cb558..0a99aeb19 100644 --- a/CHANGELOG +++ b/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+ diff --git a/docs/changelog/index.md b/docs/changelog/index.md index 48f74980c..587f79beb 100644 --- a/docs/changelog/index.md +++ b/docs/changelog/index.md @@ -6,6 +6,12 @@ template: overrides/main.html ## Material for MkDocs +### 8.1.6 _ January 11, 2022 { 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 _ January 9, 2022 { id="8.1.5" } - Improved browser support: Chrome 49+, Safari 10+, Firefox 53+, Edge 79+ diff --git a/docs/insiders/changelog.md b/docs/insiders/changelog.md index 4ad976596..d5d31fa74 100644 --- a/docs/insiders/changelog.md +++ b/docs/insiders/changelog.md @@ -6,6 +6,10 @@ template: overrides/main.html ## Material for MkDocs Insiders +### 4.6.0 _ January 11, 2022 { id="4.6.0" } + +- Added support for annotations (outside of code blocks) + ### 4.5.2 _ January 8, 2022 { id="4.5.2" } - Fixed #3440: Content tab indicator not moving when using linking diff --git a/docs/insiders/index.md b/docs/insiders/index.md index 42a93ea10..c0c562079 100644 --- a/docs/insiders/index.md +++ b/docs/insiders/index.md @@ -162,9 +162,10 @@ The following features are solely available via Material for MkDocs Insiders:
+- [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 diff --git a/docs/reference/annotations.md b/docs/reference/annotations.md new file mode 100644 index 000000000..59b9f968a --- /dev/null +++ b/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. +``` + +
+ +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. + +
+ +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! +``` + +
+ +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! + +
+ +#### 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! +``` + +
+ +!!! 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! + +
+ + [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! +``` + +
+ +=== "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! + +
+ +#### 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" +
+ +> Lorem ipsum dolor sit amet, (1) consectetur adipiscing elit. + +
+ +1. :man_raising_hand: I'm an annotation! +```` + +
+
+ +> Lorem ipsum dolor sit amet, (1) consectetur adipiscing elit. + +
+ +1. :man_raising_hand: I'm an annotation! + +
+ +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 diff --git a/docs/reference/data-tables.md b/docs/reference/data-tables.md index 6f0731f38..6d40fb545 100644 --- a/docs/reference/data-tables.md +++ b/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 | diff --git a/docs/reference/diagrams.md b/docs/reference/diagrams.md index d3fd67944..0f57c6417 100644 --- a/docs/reference/diagrams.md +++ b/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 <> @@ -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 diff --git a/docs/setup/extensions/python-markdown-extensions.md b/docs/setup/extensions/python-markdown-extensions.md index 7af1a29f0..442a3aff9 100644 --- a/docs/setup/extensions/python-markdown-extensions.md +++ b/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 diff --git a/docs/setup/extensions/python-markdown.md b/docs/setup/extensions/python-markdown.md index 05f3a4a06..720237588 100644 --- a/docs/setup/extensions/python-markdown.md +++ b/docs/setup/extensions/python-markdown.md @@ -81,6 +81,7 @@ markdown_extensions: No configuration options are available. See reference for usage: +- [Annotations] - [Adding buttons] - [Adding icons with colors] - [Image alignment] @@ -158,6 +159,8 @@ No configuration options are available. See reference for usage: - [Setting the page title] - [Setting the page description] +- [Setting the page icon] +- [Setting the page template] - [Adding tags] - [Hiding the tags] - [Hiding the sidebars] @@ -167,6 +170,8 @@ No configuration options are available. See reference for usage: [Metadata support]: https://github.com/squidfunk/mkdocs-material/releases/tag/1.0.0 [Setting the page title]: ../../reference/index.md#setting-the-page-title [Setting the page description]: ../../reference/index.md#setting-the-page-description + [Setting the page icon]: ../../reference/index.md#setting-the-page-icon + [Setting the page template]: ../../reference/index.md#setting-the-page-template [Adding tags]: ../../setup/setting-up-tags.md#adding-tags [Hiding the tags]: ../../setup/setting-up-tags.md#hiding-the-tags [Hiding the sidebars]: ../../setup/setting-up-navigation.md#hiding-the-sidebars @@ -194,10 +199,12 @@ markdown_extensions: No configuration options are available. See reference for usage: +- [Annotations] - [Image captions] [Markdown in HTML]: https://python-markdown.github.io/extensions/md_in_html/ [Markdown in HTML support]: https://github.com/squidfunk/mkdocs-material/releases/tag/0.1.0 + [Annotations]: ../../reference/annotations.md [Image captions]: ../../reference/images.md#image-captions ### Table of Contents diff --git a/material/base.html b/material/base.html index b6deb72ab..be0a8c88e 100644 --- a/material/base.html +++ b/material/base.html @@ -22,7 +22,7 @@ {% endif %} - + {% endblock %} {% block htmltitle %} {% if page and page.meta and page.meta.title %} diff --git a/mkdocs.yml b/mkdocs.yml index 4eb398980..59b33f795 100755 --- a/mkdocs.yml +++ b/mkdocs.yml @@ -194,6 +194,7 @@ nav: - reference/index.md - Abbreviations: reference/abbreviations.md - Admonitions: reference/admonitions.md + - Annotations: reference/annotations.md - Buttons: reference/buttons.md - Code blocks: reference/code-blocks.md - Content tabs: reference/content-tabs.md diff --git a/package-lock.json b/package-lock.json index ca6b67255..c6f0475fb 100644 --- a/package-lock.json +++ b/package-lock.json @@ -1,6 +1,6 @@ { "name": "mkdocs-material", - "version": "8.1.5", + "version": "8.1.6", "lockfileVersion": 1, "requires": true, "dependencies": { diff --git a/package.json b/package.json index e09c0df45..4e446b898 100644 --- a/package.json +++ b/package.json @@ -1,6 +1,6 @@ { "name": "mkdocs-material", - "version": "8.1.5", + "version": "8.1.6", "description": "A Material Design theme for MkDocs", "keywords": [ "mkdocs",