Prepared 8.1.0 release

docs/reference/code-blocks.md

@@ -80,6 +80,26 @@ theme:
   [Code annotations support]: https://github.com/squidfunk/mkdocs-material/releases/tag/8.0.0
   [Attribute Lists]: ../setup/extensions/python-markdown.md#attribute-lists
 
+#### Anchor links
+
+[:octicons-heart-fill-24:{ .mdx-heart } Insiders][Insiders]{ .mdx-insiders } ·
+[:octicons-tag-24: insiders-4.1.0][Insiders] ·
+:octicons-beaker-24: Experimental
+
+In order to link to code annotations and share them more easily, [Insiders] adds
+an anchor link to each annotation automatically, which you can copy via right
+click or open in a new tab:
+
+``` yaml
+# (1)!
+```
+
+1.  If you ++cmd++ :material-plus::material-cursor-default-outline: me, I'm
+    rendered open in a new tab. You can also right-click me to __copy link
+    address__ to share me with others.
+
+  [Insiders]: ../insiders/index.md
+
 ## Usage
 
 Code blocks must be enclosed with two separate lines containing three backticks.
@@ -173,6 +193,38 @@ theme:
 1.  :man_raising_hand: I'm a code annotation! I can contain `code`, __formatted
     text__, images, ... basically anything that can be expressed in Markdown.
 
+#### Stripping comments
+
+[:octicons-heart-fill-24:{ .mdx-heart } Insiders][Insiders]{ .mdx-insiders } ·
+[:octicons-tag-24: insiders-4.1.0][Insiders] ·
+:octicons-beaker-24: Experimental
+
+If you wish to strip the comment characters surrounding a code annotation,
+[Insiders] adds a new syntax that allows for just that. Simply add an `!` after
+the closing parens of the code annotation:
+
+_Example_:
+
+```` markdown
+``` yaml
+# (1)!
+```
+
+1.  Look ma, less line noise!
+````
+
+_Result_:
+
+``` yaml
+# (1)!
+```
+
+1.  Look ma, less line noise!
+
+Note that this only allows for a single code annotation to be rendered per
+comment. If you want to add multiple code annotations, comments cannot be
+stripped for technical reasons.
+
 ### Adding line numbers
 
 Line numbers can be added to a code block by using the `linenums="<start>"`
@@ -367,3 +419,35 @@ override it as part of your [additional style sheet]:
   [types of string tokens]: https://pygments.org/docs/tokens/#literals
   [additional style sheet]: ../customization.md#additional-css
   [syntax theme definition]: https://github.com/squidfunk/mkdocs-material/blob/master/src/assets/stylesheets/main/extensions/pymdownx/_highlight.scss
+
+### Annotations with numbers
+
+Prior to [:octicons-tag-24: 8.1.0][code annotation markers], code annotations
+were rendered with markers showing the original number as used by the author.
+However, for technical reasons code annotation numbers restart each code block,
+which might lead to confusion. For this reason, code annotations now render as
+`+` signs which are rotated if they're open to denote that clicking them again
+will close them.
+
+If you wish to revert to the prior behavior and display code annotation numbers,
+you can add an [additional style sheet] and copy and paste the following CSS:
+
+=== ":octicons-file-code-16: docs/stylesheets/extra.css"
+
+    ``` css
+    .md-typeset .md-annotation__index > ::before {
+      content: attr(data-md-annotation-id);
+    }
+    .md-typeset :focus-within > .md-annotation__index > ::before {
+      transform: none;
+    }
+    ```
+
+=== ":octicons-file-code-16: mkdocs.yml"
+
+    ``` yaml
+    extra_css:
+      - stylesheets/extra.css
+    ```
+
+  [code annotation markers]: https://github.com/squidfunk/mkdocs-material/releases/tag/8.1.0