Prepared 8.1.0 release

CHANGELOG

@@ -1,7 +1,19 @@
-mkdocs-material-8.0.5+insiders-4.x.x (2021-xx-xx)
+mkdocs-material-8.1.0+insiders-4.1.0 (2021-12-12)
 
+  * Added support for code annotation anchor links (deep linking)
+  * Added new code annotation syntax modifier to strip comment
   * Updated German translations for cookie consent
 
+mkdocs-material-8.1.0 (2012-12-12)
+
+  * Added basic support for code block line anchors
+  * Switched code annotation markers to + signs to improve usability
+  * Switched main site title to bold font
+  * Improved admonition icon positioning to align when font-size is increased
+  * Improved and simplified footnotes CSS
+  * Improved and simplified code annotation positioning
+  * Fixed syntax error in Russian translations
+
 mkdocs-material-8.0.5 (2012-12-04)
 
   * Fixed #3302: Footer refactoring induced ellipsis in some browsers

docs/changelog/index.md

@@ -6,6 +6,16 @@ template: overrides/main.html
 
 ## Material for MkDocs
 
+### 8.1.0 <small>_ December 10, 2021</small> { id="8.1.0" }
+
+- Added basic support for code block line anchors
+- Switched code annotation markers to `+` signs to improve usability
+- Switched main site title to bold font
+- Improved admonition icon positioning to align when `font-size` is increased
+- Improved and simplified footnotes CSS
+- Improved and simplified code annotation positioning
+- Fixed syntax error in Russian translations
+
 ### 8.0.5 <small>_ December 6, 2021</small> { id="8.0.5" }
 
 - Fixed #3302: Footer refactoring induced ellipsis in some browsers

docs/customization.md

@@ -20,8 +20,8 @@ the `docs` directory.
 ### Additional CSS
 
 If you want to tweak some colors or change the spacing of certain elements,
-you can do this in a separate stylesheet. The easiest way is by creating a
-new stylesheet file in the `docs` directory:
+you can do this in a separate style sheet. The easiest way is by creating a
+new style sheet file in the `docs` directory:
 
 ``` sh
 .

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

docs/setup/extensions/python-markdown-extensions.md

@@ -308,7 +308,8 @@ The [Highlight] extension adds support for syntax highlighting of code blocks
 
 ``` yaml
 markdown_extensions:
-  - pymdownx.highlight
+  - pymdownx.highlight:
+      anchor_linenums: true
   - pymdownx.superfences # (1)
 ```
 
@@ -414,6 +415,19 @@ The following configuration options are supported:
     copying a code block to the clipboard. Thus, the usage of either `table`
     or `pymdownx-inline` is recommended.
 
+`anchor_linenums`{ #anchor-linenums }
+
+:   [:octicons-tag-24: 8.1.0][anchor_linenums support] · :octicons-milestone-24:
+    Default: `false` – If a code blocks contains line numbers, enabling this
+    setting will wrap them with anchor links, so they can be hyperlinked and
+    shared more easily:
+
+    ``` yaml
+    markdown_extensions:
+      - pymdownx.highlight:
+          anchor_linenums: true
+    ```
+
 The other configuration options of this extension are not officially supported
 by Material for MkDocs, which is why they may yield unexpected results. Use
 them at your own risk.
@@ -435,6 +449,7 @@ See reference for usage:
   [additional CSS]: ../../customization.md#additional-css
   [Highlight.js]: https://highlightjs.org/
   [title]: ../../reference/code-blocks.md#adding-a-title
+  [anchor_linenums support]: https://github.com/squidfunk/mkdocs-material/releases/tag/8.1.0
   [Adding line numbers]: ../../reference/code-blocks.md#adding-line-numbers
   [Using code blocks]: ../../reference/code-blocks.md#usage
   [Adding a title]: ../../reference/code-blocks.md#adding-a-title

material/base.html

@@ -22,7 +22,7 @@
         <link rel="canonical" href="{{ page.canonical_url }}">
       {% endif %}
       <link rel="icon" href="{{ config.theme.favicon | url }}">
-      <meta name="generator" content="mkdocs-{{ mkdocs_version }}, mkdocs-material-8.0.5">
+      <meta name="generator" content="mkdocs-{{ mkdocs_version }}, mkdocs-material-8.1.0">
     {% endblock %}
     {% block htmltitle %}
       {% if page and page.meta and page.meta.title %}

mkdocs.yml

@@ -137,8 +137,7 @@ markdown_extensions:
       emoji_index: !!python/name:materialx.emoji.twemoji
       emoji_generator: !!python/name:materialx.emoji.to_svg
   - pymdownx.highlight:
-      line_spans: __codeline
-      anchor_linenums: True
+      anchor_linenums: true
   - pymdownx.inlinehilite
   - pymdownx.keys
   - pymdownx.magiclink:

package.json

@@ -1,6 +1,6 @@
 {
   "name": "mkdocs-material",
-  "version": "8.0.5",
+  "version": "8.1.0",
   "description": "A Material Design theme for MkDocs",
   "keywords": [
     "mkdocs",