reviewed my other commits

docs/block_annotations.rst

@@ -2,7 +2,7 @@
 Block Annotations
 =================
 
-This sphinx has support for adding annotations to block level document elements.
+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::
@@ -16,14 +16,34 @@ To do this, we will use the :dudir:`class` which is re-exported by sphinx as ``r
 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
 
-    Lorem ipsum dolor sit amet, (1) consectetur adipiscing elit.
+    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
 ----------------
@@ -86,6 +106,9 @@ Instead, we can just add the ``annotate`` class to the admonition's :rst:`:class
 Annotating tabbed content
 -------------------------
 
+Here is a simple example of `annotating paragraphs`_ within tabbed content
+(using :doc:`content_tabs`).
+
 .. rst-example::
 
     .. md-tab-set::
@@ -106,32 +129,49 @@ Annotating tabbed content
 
             1. I'm an annotation as well!
 
-Annotating blockquotes is unsupported
--------------------------------------
+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.
-However, this suggestion is not compatible with adding annotations inside a blockquote.
 
-.. rst-example:: This doesn't work as expected!
+.. rst-example::
 
-    .. rst-class:: annotation
+    .. rst-class:: annotate
     ..
 
-        A blockquote with an unsupported annotation. (1)
+        A blockquote with an annotation. (1)
 
     1. I'm an annotation!
 
-.. hint::
+.. info:: Implementation Detail
     :collapsible:
-    :title: Implementation Detail
 
-    If you inspect the HTML of the above example, you will see the ``annotation`` class appended to
-    the :html:`<blockquote class="annotation">` element. But this class needs to be appended to a
-    :html:`<div>` container element that encapsulates the :html:`<blockquote>` element.
+    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)
 
-    Furthermore, annotations are mounted when the page is loaded via javascript.
-    The javascript implementation here is inherited from mkdocs-material source, and `blockquotes in mkdocs'
-    HTML output <https://squidfunk.github.io/mkdocs-material/reference/annotations/#in-everything-else>`_
-    do not have a :html:`<div>` container encapsulated within the :html:`<blockquote>` element
-    (like it is when blockquotes are generated by docutils/sphinx).
+        1. I'm an annotation!
+        2. I'm an annotation as well!

docs/customization.rst

@@ -221,7 +221,8 @@ Configuration Options
 
         .. themeconf:: close
 
-            This icon is used as the close icon when viewing search results (or to dismiss the announce banner).
+            This icon is used as the close icon when viewing search results (or to dismiss the
+            announcement banner).
             Defaults to ``material/close`` (:si-icon:`material/close`).
 
         .. themeconf:: top
@@ -313,8 +314,8 @@ Configuration Options
           - ``content.action.view`` will enable the :si-icon:`material/file-eye-outline` "View source of this page" link at the top of the page.
           - ``content.action.edit`` will enable the :si-icon:`material/file-edit-outline` "Edit this page" link at the top of the page.
 
-          .. note::
-              using the :themeconf:`hide-edit-link` metadata will suppress both of these features on a per-page basis.
+          .. seealso::
+              Using the :themeconf:`hide-edit-link` metadata field will suppress both of these features on a per-page basis.
 
         - `content.code.annotate <https://squidfunk.github.io/mkdocs-material/reference/code-blocks/#code-annotations>`_
 

sphinx_immaterial/custom_admonitions.py

@@ -344,8 +344,8 @@ def get_directive_class(name, title, classes=None) -> Type[CustomAdmonitionDirec
     if classes:
         class_list.extend(classes)
 
-    # make sphinx/docutils admonitions compatible with changes in
-    # supported admonition types in upstream v9
+    # make sphinx/docutils admonitions compatible with
+    # supported admonition types in upstream v9+
     if name in ("caution", "attention"):
         class_list.append("warning")
     elif name == "error":