Merge in upstream changes from mkdocs-material

.editorconfig

@@ -1,4 +1,4 @@
-# Copyright (c) 2016-2022 Martin Donath <martin.donath@squidfunk.com>
+# Copyright (c) 2016-2024 Martin Donath <martin.donath@squidfunk.com>
 
 # Permission is hereby granted, free of charge, to any person obtaining a copy
 # of this software and associated documentation files (the "Software"), to
@@ -30,10 +30,6 @@ end_of_line = lf
 insert_final_newline = true
 trim_trailing_whitespace = true
 
-# Markdown
-[*.md]
-trim_trailing_whitespace = false
-
 # Python
 [*.py]
 indent_style = space

.eslintignore

@@ -1,4 +1,4 @@
-# Copyright (c) 2016-2022 Martin Donath <martin.donath@squidfunk.com>
+# Copyright (c) 2016-2024 Martin Donath <martin.donath@squidfunk.com>
 
 # Permission is hereby granted, free of charge, to any person obtaining a copy
 # of this software and associated documentation files (the "Software"), to

.eslintrc

@@ -214,7 +214,7 @@
     ],
     "@typescript-eslint/no-empty-interface": "off",
     "@typescript-eslint/no-extraneous-class": "error",
-    "@typescript-eslint/no-misused-promises": "error",
+    "@typescript-eslint/no-misused-promises": "off",
     "@typescript-eslint/no-non-null-assertion": "off",
     "@typescript-eslint/no-parameter-properties": "off",
     "@typescript-eslint/no-floating-promises": "error",
@@ -320,7 +320,6 @@
       }
     ],
     "jsdoc/empty-tags": "warn",
-    "jsdoc/newline-after-description": "warn",
     "jsdoc/no-bad-blocks": "warn",
     "jsdoc/no-defaults": "warn",
     "jsdoc/no-types": "warn",

.github/workflows/build.yml

@@ -22,7 +22,7 @@ jobs:
         include:
           - nox-sessions: 'black check_yaml check_json check_toml check_eof check_trailing_space check_lf'
             python-version: '3.x'
-            node-version: '16.x'
+            node-version: '20.x'
           - nox-sessions: 'mypy pylint'
             python-version: '3.8'
           - nox-sessions: 'mypy pylint'
@@ -77,7 +77,7 @@ jobs:
         python-version:
           - '3.x'
         node-version:
-          - '16.x'
+          - '20.x'
     runs-on: ${{ matrix.os }}
     steps:
       - uses: actions/checkout@v4
@@ -158,7 +158,7 @@ jobs:
           - 'sphinx6'
           - 'sphinx7'
         node-version:
-          - '16.x'
+          - '20.x'
         exclude:
           - python-version: '3.8'
             sphinx-version: 'sphinx7'

.stylelintignore

@@ -1,4 +1,4 @@
-# Copyright (c) 2016-2022 Martin Donath <martin.donath@squidfunk.com>
+# Copyright (c) 2016-2024 Martin Donath <martin.donath@squidfunk.com>
 
 # Permission is hereby granted, free of charge, to any person obtaining a copy
 # of this software and associated documentation files (the "Software"), to

.stylelintrc

@@ -1,8 +1,9 @@
 {
   "extends": [
-    "stylelint-config-rational-order",
+    "stylelint-config-recess-order",
     "stylelint-config-recommended",
-    "stylelint-config-standard-scss"
+    "stylelint-config-standard-scss",
+    "stylelint-stylistic/config"
   ],
   "plugins": [
     "stylelint-scss"
@@ -32,16 +33,6 @@
       }
     ],
     "at-rule-no-unknown": null,
-    "block-closing-brace-newline-after": [
-      "always",
-      {
-        "ignoreAtRules": [
-          "if",
-          "else",
-          "elseif"
-        ]
-      }
-    ],
     "color-function-notation": null,
     "color-hex-length": "long",
     "color-named": "never",
@@ -58,23 +49,23 @@
     "declaration-colon-space-after": null,
     "declaration-no-important": true,
     "declaration-block-single-line-max-declarations": 0,
+    "font-family-name-quotes": "always-where-recommended",
+    "font-weight-notation": "numeric",
     "function-calc-no-unspaced-operator": null,
     "function-no-unknown": null,
     "function-url-no-scheme-relative": true,
     "function-url-quotes": "always",
-    "font-family-name-quotes": "always-where-recommended",
-    "font-weight-notation": "numeric",
     "hue-degree-notation": "number",
     "length-zero-no-unit": [
       true,
       {
         "ignore": ["custom-properties"]
       }
     ],
-    "linebreaks": "unix",
     "media-feature-name-no-unknown": null,
+    "media-feature-range-notation": null,
+    "media-query-no-invalid": null,
     "no-descending-specificity": null,
-    "no-empty-first-line": true,
     "no-unknown-animations": true,
     "property-no-unknown": null,
     "property-no-vendor-prefix": [
@@ -90,19 +81,17 @@
     "selector-combinator-space-before": null,
     "selector-descendant-combinator-no-non-space": null,
     "selector-id-pattern": null,
-    "selector-max-empty-lines": 0,
     "selector-max-id": 0,
     "selector-no-qualifying-type": null,
     "selector-pseudo-class-no-unknown": null,
     "selector-pseudo-element-no-unknown": null,
-    "string-quotes": "double",
-    "unicode-bom": "never",
     "unit-allowed-list": [
       "%",
       "ch",
       "dppx",
       "deg",
       "em",
+      "fr",
       "mm",
       "ms",
       "px",
@@ -158,6 +147,23 @@
     "scss/operator-no-unspaced": true,
     "scss/partial-no-import": true,
     "scss/percent-placeholder-pattern": "^[a-z][a-z0-9]*(-[a-z0-9]+)*$",
-    "scss/selector-no-redundant-nesting-selector": true
+    "scss/selector-no-redundant-nesting-selector": true,
+    "stylistic/block-closing-brace-newline-after": [
+      "always",
+      {
+        "ignoreAtRules": [
+          "if",
+          "else",
+          "elseif"
+        ]
+      }
+    ],
+    "stylistic/declaration-colon-space-after": null,
+    "stylistic/no-empty-first-line": true,
+    "stylistic/linebreaks": "unix",
+    "stylistic/selector-max-empty-lines": 0,
+    "stylistic/string-quotes": "double",
+    "stylistic/unicode-bom": "never",
+    "stylistic/value-list-comma-newline-after": null
   }
 }

MKDOCS_MATERIAL_MERGE_BASE

@@ -1 +1 @@
-f139b54c61b2df4512f15149cba2c222475e2bc9
+f27b93ece3c423537873e0bc5de55b3c3381792f

docs/_static/extra_css.css

@@ -3,14 +3,6 @@
   --md-tooltip-width: 600px;
 }
 
-.annotated-with-numbers .md-annotation__index > ::before {
-  content: attr(data-md-annotation-id);
-}
-
-.annotated-with-numbers :focus-within > .md-annotation__index > ::before {
-  transform: none;
-}
-
 /* style for custom font example */
 .custom-font-example {
   --md-text-font: "Comic Neue";

docs/_templates/base.html

@@ -3,6 +3,6 @@
   <p>
     Now includes
     <a href="https://squidfunk.github.io/mkdocs-material/changelog/">changes from mkdocs-material theme</a>
-    v8.5.6
+    v9.5.16
   </p>
 {% endblock %}

docs/block_annotations.rst

@@ -0,0 +1,177 @@
+
+Block Annotations
+=================
+
+The sphinx-immaterial theme has support for adding annotations to block level document elements.
+To do this, we will use the :dudir:`class` which is re-exported by sphinx as ``rst-class``.
+
+.. important::
+
+    Please read the :dudir:`class` documentation to better understand how Sphinx'
+    ``rst-class`` directive works.
+
+.. seealso::
+    A special directive is needed to produce :rst:dir:`code-annotations`.
+
+Annotating paragraphs
+---------------------
+
+The first block-level element that follows a ``rst-class`` directive (without directive content)
+is appended with the ``annotate`` class.
+
+.. rst-example::
+
+    .. rst-class:: annotate
+
+    An annotated paragraph. (1)
+
+    An unannotated paragraph. (2)
+
+    1. I'm an annotation! I can contain ``code``, *formatted text*, images, ...
+       basically anything that can be used. :si-icon:`material/emoticon-happy`
+    2. This won't show.
+
+When the ``rst-class`` is given content, then all blocks within the content are
+appended with the ``annotate`` class.
+
+.. rst-example::
+
+    .. rst-class:: annotate
+
+        First paragraph (1)
+
+        Second paragraph (2)
+
+    1. I'm an annotation!
+    2. I'm an annotation as well!
+
+Annotating lists
+----------------
+
+Lists can be annotated as well. Beware that lists are typically started and ended with a blank line.
+So, consecutive lists (as in the case of annotating lists) might look odd.
+
+.. rst-example::
+
+    .. rst-class:: annotate
+
+    1. An ordered list item (1)
+
+       1. A nested list does not need to end in a blank line.
+    2. A second list item (2)
+
+    1. I'm an annotation!
+    2. I'm an annotation as well!
+
+Nested annotations
+******************
+
+Nested annotations can be done as well, although the indentation gets tricky.
+Beware that the paragraph within the annotated list must also be flagged with
+``.. rst-class:: annotate``, otherwise the nested annotation will just appear
+as a nested list.
+
+.. rst-example::
+
+    .. rst-class:: annotate
+
+    Lorem ipsum dolor sit amet, (1) consectetur adipiscing elit.
+
+    1. .. rst-class:: annotate
+
+       I'm an annotation! (1)
+
+       1. I'm an annotation as well!
+
+Annotating admonitions
+----------------------
+
+The :rst:dir:`admonition` directives already contain an option to specify CSS classes.
+Therefor, we don't need to use the ``rst-class`` directive for admonitions.
+Instead, we can just add the ``annotate`` class to the admonition's :rst:`:class:` option.
+
+.. rst-example::
+
+    .. note::
+        :title: Phasellus posuere in sem ut cursus (1)
+        :class: annotate
+
+        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. I'm an annotation!
+    2. I'm an annotation as well!
+
+Annotating tabbed content
+-------------------------
+
+Here is a simple example of `annotating paragraphs`_ within tabbed content
+(using :doc:`content_tabs`).
+
+.. rst-example::
+
+    .. md-tab-set::
+
+        .. md-tab-item:: Tab 1
+
+            .. rst-class:: annotate
+
+            Lorem ipsum dolor sit amet, (1) consectetur adipiscing elit.
+
+            1. I'm an annotation!
+
+        .. md-tab-item:: Tab 2
+
+            .. rst-class:: annotate
+
+            Phasellus posuere in sem ut cursus (1)
+
+            1. I'm an annotation as well!
+
+Annotating blockquotes
+----------------------
+
+There is a noteworthy clash between the syntax for :duref:`block-quotes` versus the :dudir:`class`.
+The suggested workaround is a single rST comment immediately after the ``rst-class`` invocation.
+
+.. rst-example::
+
+    .. rst-class:: annotate
+    ..
+
+        A blockquote with an annotation. (1)
+
+    1. I'm an annotation!
+
+.. info:: Implementation Detail
+    :collapsible:
+
+    The ``rst-class`` directive is not given any content in the example above.
+    The empty comment :rst:`..` (followed by a blank line) implicitly signifies this to the rST parser.
+
+    If we instead provide a blockquote as the sole content to the ``rst-class`` directive,
+    then indentation is normalized by the rST parser and the blockquote is
+    interpreted as a simple paragraph.
+
+    .. rst-example:: A blockquote as sole directive content *does not work*
+
+        .. rst-class:: annotate
+
+                A blockquote (normalized to a paragraph) with an annotation. (1)
+
+        1. I'm an annotation!
+
+    Using a blockquote as subsequent content preserves the indentation needed to satisfy
+    the :duref:`block-quotes` specification.
+
+    .. rst-example:: A blockquote as subsequent directive content *can work*
+
+        .. rst-class:: annotate
+
+            An annotated paragraph (1) which does not get annotated by the JS implementation.
+
+                A blockquote with an annotation. (2)
+
+        1. I'm an annotation!
+        2. I'm an annotation as well!