diff --git a/docs/block_annotations.rst b/docs/block_annotations.rst index 1e3da990..c3e3b80e 100644 --- a/docs/block_annotations.rst +++ b/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:`
` element. But this class needs to be appended to a - :html:`
` container element that encapsulates the :html:`
` 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 `_ - do not have a :html:`
` container encapsulated within the :html:`
` element - (like it is when blockquotes are generated by docutils/sphinx). + 1. I'm an annotation! + 2. I'm an annotation as well! diff --git a/docs/customization.rst b/docs/customization.rst index 7d9b4cb9..0dc72b84 100644 --- a/docs/customization.rst +++ b/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 `_ diff --git a/sphinx_immaterial/custom_admonitions.py b/sphinx_immaterial/custom_admonitions.py index 58928f05..0aceb5ee 100644 --- a/sphinx_immaterial/custom_admonitions.py +++ b/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":