Documentation

docs/insiders.md

@@ -112,6 +112,7 @@ The following features are currently exclusively available to sponsors:
 
 <div class="mdx-columns" markdown="1">
 
+- [x] [Code block annotations :material-new-box:][24]
 - [x] [Anchor tracking :material-new-box:][23]
 - [x] [Section index pages][21]
 - [x] [Latest release tag][15]
@@ -171,18 +172,19 @@ the public for general availability.
 #### $ 4,000 – Ghost Pepper
 
 - [x] [Anchor tracking][23]
-- [ ] Code block annotations
+- [x] [Code block annotations][24]
 - [ ] Back-to-top button
 
 [23]: setup/setting-up-navigation.md#anchor-tracking
+[24]: reference/code-blocks.md#adding-annotations
 
 #### $ 5,000 – Aji Panca
 
-- [x] [Mermaid.js integration][24]
+- [x] [Mermaid.js integration][25]
 - [ ] List of last searches
 - [ ] Advanced routing for versioning
 
-  [24]: reference/diagrams.md
+  [25]: reference/diagrams.md
 
 #### $ 6,000 – Trinidad Scorpion
 
@@ -198,10 +200,10 @@ the public for general availability.
 
 #### Future
 
-- [ ] [Material for MkDocs Live Edit][25]
+- [ ] [Material for MkDocs Live Edit][26]
 - [ ] New layouts and styles
 
-  [25]: https://twitter.com/squidfunk/status/1338252230265360391
+  [26]: https://twitter.com/squidfunk/status/1338252230265360391
 
 ### Goals completed
 
@@ -247,10 +249,10 @@ implemented behind feature flags; all configuration changes are
 backward-compatible. This means that your users will be able to build the
 documentation locally with Material for MkDocs and when they push their changes,
 it can be built with Insiders (e.g. as part of GitHub Actions). Thus, it's
-recommended to [install Insiders][26] only in CI, as you don't want to expose
+recommended to [install Insiders][27] only in CI, as you don't want to expose
 your `GH_TOKEN` to users.
 
-  [26]: publishing-your-site.md#github-pages
+  [27]: publishing-your-site.md#github-pages
 
 ### Terms
 
@@ -259,7 +261,7 @@ commercial project. Can we use Insiders under the same terms and conditions?_
 
 Yes. Whether you're an individual or a company, you may use _Material for MkDocs
 Insiders_ precisely under the same terms as Material for MkDocs, which are given
-by the [MIT license][27]. However, we kindly ask you to respect the following
+by the [MIT license][28]. However, we kindly ask you to respect the following
 guidelines:
 
 - Please __don't distribute the source code__ of Insiders. You may freely use
@@ -270,7 +272,7 @@ guidelines:
 - If you cancel your subscription, you're removed as a collaborator and will
   miss out on future updates of Insiders. However, you may __use the latest
   version__ that's available to you __as long as you like__. Just remember that
-  [GitHub deletes private forks][28].
+  [GitHub deletes private forks][29].
 
-  [27]: license.md
+  [28]: license.md
-  [28]: https://docs.github.com/en/github/setting-up-and-managing-your-github-user-account/removing-a-collaborator-from-a-personal-repository
+  [29]: https://docs.github.com/en/github/setting-up-and-managing-your-github-user-account/removing-a-collaborator-from-a-personal-repository

docs/reference/code-blocks.md

@@ -206,6 +206,61 @@ import tensorflow as tf
 
   [17]: https://pygments.org/docs/lexers/
 
+### Adding annotations
+
+[:octicons-file-code-24: Source][18] ·
+:octicons-beaker-24: Experimental ·
+[:octicons-heart-fill-24:{: .mdx-heart } Insiders only][18]{: .mdx-insiders }
+
+Annotations offer a comfortable and friendly way to attach explanations to
+arbitrary sections of code blocks by adding simple markers within block/inline
+comments that refer to items of a list following the code block, i.e. `(1)`,
+`(2)`, etc. Material for MkDocs removes the list from the flow of the document,
+injects the content of each list item into a tooltip, and links each list marker
+to the corresponding tooltip.
+
+In order to opt-in to annotation support, a slightly different syntax is
+required – just add the respective [language short code][17] and the `.annotate`
+class, after the three backticks.
+
+_Example_:
+
+```` markdown
+``` {: .js .annotate }
+document$.subscribe(function() { // (1)
+  var tables = document.querySelectorAll(/* (2) */ "article table")
+  tables.forEach(function(table) {
+    new Tablesort(table)
+  })
+})
+```
+
+1. ...
+2. ...
+````
+
+_Result_:
+
+<figure markdown="1">
+
+[![Annotations][19]][19]
+
+  <figcaption markdown="1">
+
+A demo is worth a thousand words — check it out at
+[squidfunk.github.io/mkdocs-material-insiders][20]
+
+  </figcaption>
+</figure>
+
+_Annotations require syntax highlighting with [Pygments][24] – they're currently
+not compatible with other JavaScript-based syntax highlighters. Support may be
+added later on._
+
+  [18]: ../insiders.md
+  [19]: ../assets/screenshots/annotations.png
+  [20]: https://squidfunk.github.io/mkdocs-material-insiders/reference/code-blocks/#adding-annotations
+
 ### Adding line numbers
 
 Line numbers can be added to a code block by using the `linenums="<start>"`
@@ -265,7 +320,7 @@ def bubble_sort(items):
 
 ### Highlighting inline code blocks
 
-When [InlineHilite][18] is enabled, inline code blocks can be highlighted by
+When [InlineHilite][21] is enabled, inline code blocks can be highlighted by
 prefixing them with a shebang-like sequence, i.e. `#!`, directly followed by
 the [language short name][17].
 
@@ -279,11 +334,11 @@ _Result_:
 
 The `#!python range()` function is used to generate a sequence of numbers.
 
-  [18]: #inlinehilite
+  [21]: #inlinehilite
 
 ### Adding keyboard keys
 
-When [Keys][19] is enabled, keyboard keys can be rendered with a simple syntax.
+When [Keys][22] is enabled, keyboard keys can be rendered with a simple syntax.
 Consult the [Python Markdown Extensions][16] documentation to learn about all
 available key codes.
 
@@ -297,13 +352,13 @@ _Result_:
 
 ++ctrl+alt+del++
 
-  [19]: #keys
+  [22]: #keys
 
 ### Embedding external files
 
-_Also known as transcludes or file transclusion in [MultiMarkdown][20]_.
+_Also known as transcludes or file transclusion in [MultiMarkdown][23]_.
 
-When [Snippets][21] is enabled, content from other files can be embedded, which
+When [Snippets][24] is enabled, content from other files can be embedded, which
 is especially useful to reference and embed the contents of source files
 directly into your project documentation.
 
@@ -321,23 +376,23 @@ _Result_:
 last 4 years
 ```
 
-Note that [Snippets][21] is not limited to code blocks, but can be used anywhere
+Note that [Snippets][24] is not limited to code blocks, but can be used anywhere
 from a document to move repeating content to separate files, which is also
 explained in the [official documentation][16].
 
-  [20]: https://fletcher.github.io/MultiMarkdown-5/transclusion.html
+  [23]: https://fletcher.github.io/MultiMarkdown-5/transclusion.html
-  [21]: #snippets
+  [24]: #snippets
 
 ## Customization
 
 ### Custom syntax theme
 
-[:octicons-file-code-24: Source][22] ·
+[:octicons-file-code-24: Source][25] ·
 :octicons-mortar-board-24: Difficulty: _easy_
 
-If [Pygments][23] is used, Material for MkDocs provides the [styles for code
+If [Pygments][26] is used, Material for MkDocs provides the [styles for code
-blocks][22], which are built with a custom and well-balanced palette that works
+blocks][25], which are built with a custom and well-balanced palette that works
-equally well for both [color schemes][24]:
+equally well for both [color schemes][27]:
 
 - :material-checkbox-blank-circle:{: style="color: var(--md-code-hl-number-color) " } `--md-code-hl-number-color`
 - :material-checkbox-blank-circle:{: style="color: var(--md-code-hl-special-color) " } `--md-code-hl-special-color`
@@ -359,7 +414,7 @@ Code block foreground, background and line highlight colors are defined via:
 - :material-checkbox-blank-circle:{: style="color: var(--md-code-hl-color) " } `--md-code-hl-color`
 
 Let's say you want to change the color of `#!js "strings"`. While there are
-several [types of string tokens][25], Material for MkDocs assigns a single color
+several [types of string tokens][28], Material for MkDocs assigns a single color
 to most of them.
 
 Create an [additional stylesheet][6], and add:
@@ -371,7 +426,7 @@ Create an [additional stylesheet][6], and add:
 ```
 
 If you want to tweak a specific type of string, i.e. ``#!js `backticks` ``, you
-can lookup the specific class name in the [syntax theme definition][26], and
+can lookup the specific class name in the [syntax theme definition][29], and
 override it as part of your additional stylesheet:
 
 ``` css
@@ -380,8 +435,8 @@ override it as part of your additional stylesheet:
 }
 ```
 
-  [22]: https://github.com/squidfunk/mkdocs-material/blob/master/src/assets/stylesheets/main/_colors.scss#
+  [25]: https://github.com/squidfunk/mkdocs-material/blob/master/src/assets/stylesheets/main/_colors.scss#
-  [23]: #use-pygments
+  [26]: #use-pygments
-  [24]: ../setup/changing-the-colors.md#color-scheme
+  [27]: ../setup/changing-the-colors.md#color-scheme
-  [25]: https://pygments.org/docs/tokens/#literals
+  [28]: https://pygments.org/docs/tokens/#literals
-  [26]: https://github.com/squidfunk/mkdocs-material/blob/master/src/assets/stylesheets/main/extensions/markdown/_codehilite.scss
+  [29]: https://github.com/squidfunk/mkdocs-material/blob/master/src/assets/stylesheets/main/extensions/markdown/_codehilite.scss