Documentation

Author: squidfunk

docs/blog/posts/the-past-present-and-future.md

@@ -119,7 +119,7 @@ are still exclusively available to sponsors as part of [Insiders]:
 - [Boosting pages in search]
 - [Brand new search plugin]
 - [Code annotations]
-- [Code annotations: anchor links]
+- Code annotations: anchor links
 - [Code annotations: strip comments]
 - [Code block titles]
 - [Code block line anchors]
@@ -167,7 +167,6 @@ __55__ times, `mkdocs-material-insiders` was shipped __72__ times.
   [Boosting pages in search]: ../../setup/setting-up-site-search.md#search-boosting
   [Brand new search plugin]: search-better-faster-smaller.md
   [Code annotations]: ../../reference/code-blocks.md#adding-annotations
-  [Code annotations: anchor links]: ../../reference/code-blocks.md#anchor-links
   [Code annotations: strip comments]: ../../reference/code-blocks.md#stripping-comments
   [Code block titles]: ../../reference/code-blocks.md#adding-a-title
   [Code block line anchors]: ../../setup/extensions/python-markdown-extensions.md#anchor-linenums

docs/insiders/index.md

@@ -88,14 +88,16 @@ a handful of them, [thanks to our awesome sponsors]!
 ## What's in it for me?
 
 The moment you [become a sponsor][how to become a sponsor], you'll get __immediate
-access to 23 additional features__ that you can start using right away, and
+access to 25 additional features__ that you can start using right away, and
 which are currently exclusively available to sponsors:
 
 <div class="mdx-columns" markdown>
 
+- [x] [Code range selection] :material-alert-decagram:{ .mdx-pulse title="Added on February 19, 2023" }
+- [x] [Code annotations: custom selectors] :material-alert-decagram:{ .mdx-pulse title="Added on February 19, 2023" }
 - [x] [Privacy plugin: optimization support] :material-alert-decagram:{ .mdx-pulse title="Added on February 6, 2023" }
-- [x] [Optimize plugin] :material-alert-decagram:{ .mdx-pulse title="Added on January 21, 2023" }
-- [x] [Navigation path] (Breadcrumbs) :material-alert-decagram:{ .mdx-pulse title="Added on January 14, 2023" }
+- [x] [Optimize plugin]
+- [x] [Navigation path] (Breadcrumbs)
 - [x] [Typeset plugin]
 - [x] [Privacy plugin: external links]
 - [x] [Navigation subtitles]
@@ -287,7 +289,7 @@ are released for general availability.
 - [x] [Blog plugin: related links]
 - [x] [Blog plugin: custom index pages]
 - [x] [Tags plugin: additional indexes]
-- [x] [Tags plugin: allow list] and [custom sorting]
+- [x] [Tags plugin: allow list] + [custom sorting]
 - [x] [Navigation subtitles]
 
   [Meta plugin]: ../reference/index.md#built-in-meta-plugin
@@ -302,10 +304,10 @@ are released for general availability.
 
 - [x] [Optimize plugin]
 - [x] [Typeset plugin]
-- [x] [Privacy plugin: external links]
 - [x] [Navigation path] (Breadcrumbs)
 - [x] [Privacy plugin: optimization support]
-- [ ] Code block line wrapping
+- [x] [Privacy plugin: external links]
+- [ ] Privacy plugin: external link validation
 
   [Optimize plugin]: ../setup/building-an-optimized-site.md#built-in-optimize-plugin
   [Typeset plugin]: ../reference/index.md#built-in-typeset-plugin
@@ -316,7 +318,12 @@ are released for general availability.
 
 #### $ 24,000 – Blockpaprika
 
-- [ ] [Instant previews]
+- [x] [Code range selection]
+- [x] [Code annotations: custom selectors]
+- [ ] Code line wrap button
+
+  [Code range selection]: ../reference/code-blocks.md#code-selection-button
+  [Code annotations: custom selectors]: ../reference/code-blocks.md#custom-selectors
 
 ### Goals completed
 
@@ -343,14 +350,13 @@ can be used by all users.
 #### $ 8,000 – Scotch Bonnet
 
 - [x] [Social cards]
-- [x] [Code annotations: anchor links]
+- [x] Code annotations: anchor links
 - [x] [Code annotations: strip comments]
 - [x] [Tag icons]
 - [x] [Table of contents anchor following]
 - [x] Sidebars automatically scroll to active item
 
   [Social cards]: ../setup/setting-up-social-cards.md
-  [Code annotations: anchor links]: ../reference/code-blocks.md#anchor-links
   [Code annotations: strip comments]: ../reference/code-blocks.md#stripping-comments
   [Tag icons]: ../setup/setting-up-tags.md#tag-icons-and-identifiers
   [Table of contents anchor following]: ../setup/setting-up-navigation.md#anchor-following

docs/reference/code-blocks.md

@@ -21,6 +21,8 @@ following lines to `mkdocs.yml`:
 markdown_extensions:
   - pymdownx.highlight:
       anchor_linenums: true
+      line_spans: __span
+      pygments_lang_class: true
   - pymdownx.inlinehilite
   - pymdownx.snippets
   - pymdownx.superfences
@@ -81,6 +83,47 @@ theme:
     ```
     ````
 
+### Code selection button :material-alert-decagram:{ .mdx-pulse title="Added on February 19, 2023" }
+
+[:octicons-heart-fill-24:{ .mdx-heart } Sponsors only][Insiders]{ .mdx-insiders } ·
+[:octicons-tag-24: insiders-4.32.0][Insiders] ·
+:octicons-beaker-24: Experimental
+
+Code blocks can include a button to allow for the selection of line ranges by
+the user, which is perfect for linking to a specific subsection of a code block. This allows the user to apply [line highlighting] dynamically. Add the following
+to `mkdocs.yml` to enable it globally:
+
+``` yaml
+theme:
+  features:
+    - content.code.select
+```
+
+??? info "Enabling or disabling code selection buttons for a specific code block"
+
+    If you don't want to enable code selection buttons globally, you can enable 
+    them for a specific code block by using a slightly different syntax based on 
+    the [Attribute Lists] extension:
+
+    ```` yaml
+    ``` { .yaml .select }
+    # Code block content
+    ```
+    ````
+
+    Note that the language shortcode which has to come first must now also be 
+    prefixed by a `.`. Similarly, the selection button can also be disabled for
+    a specific code block:
+
+    ```` { .yaml .no-select }
+    ``` { .yaml .no-select }
+    # Code block content
+    ```
+    ````
+
+  [Insiders]: ../insiders/index.md
+  [line highlighting]: #highlighting-specific-lines
+
 ### Code annotations
 
 [:octicons-tag-24: 8.0.0][Code annotations support] ·
@@ -119,24 +162,45 @@ 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
+#### Custom selectors :material-alert-decagram:{ .mdx-pulse title="Added on February 19, 2023" }
 
-[:octicons-tag-24: 8.5.0][Anchor links support] ·
+[:octicons-heart-fill-24:{ .mdx-heart } Sponsors only][Insiders]{ .mdx-insiders } ·
+[:octicons-tag-24: insiders-4.32.0][Insiders] ·
 :octicons-beaker-24: Experimental
 
-In order to be able to link to code annotations and share them more easily, an
-anchor link is automatically added to each annotation, which you can copy via
-right click or open in a new tab:
+Normally, code annotations can only be [placed in comments], as comments can be
+considered safe for placement. However, sometimes it might be necessary to place
+annotations in parts of the code block where comments are not allowed, e.g. in 
+strings.
+
+Additional selectors can be set per-language:
 
 ``` yaml
-# (1)!
+extra:
+  annotate:
+    json: [.s2] # (1)!
+```
+
+1.  [`.s2`][s2] is the name of the lexeme that [Pygments] generates for double-quoted
+    strings. If you want to use a code annotation in another lexeme than a
+    comment, inspect the code block and determine which lexeme needs to be added
+    to the list of additional selectors.
+
+    __Important__: Code annotations cannot be split between lexemes.
+
+Now, code annotations can be used from within strings in JSON:
+
+``` json
+{
+  "key": "value (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.
+1.  :man_raising_hand: I'm a code annotation! I can contain `code`, __formatted
+    text__, images, ... basically anything that can be written in Markdown.
 
-  [Anchor links support]: https://github.com/squidfunk/mkdocs-material/releases/tag/8.5.0
+  [placed in comments]: #adding-annotations
+  [s2]: https://github.com/squidfunk/mkdocs-material/blob/87d5ca487b9d9ab95c41ee72813149d214048693/src/assets/stylesheets/main/extensions/pymdownx/_highlight.scss#L45
 
 ## Usage
 

docs/setup/ensuring-data-privacy.md

@@ -325,7 +325,7 @@ The following configuration options are available for external assets:
   [technical limitations]: #limitations
   [built-in optimize plugin]: building-an-optimized-site.md#built-in-optimize-plugin
 
-#### External links :material-alert-decagram:{ .mdx-pulse title="Added on October 18, 2022" }
+#### External links
 
 [:octicons-heart-fill-24:{ .mdx-heart } Sponsors only][Insiders]{ .mdx-insiders } ·
 [:octicons-tag-24: insiders-4.26.0][Insiders] ·

mkdocs.yml

@@ -94,6 +94,8 @@ hooks:
 
 # Customization
 extra:
+  annotate:
+    json: [.s2]
   analytics:
     provider: google
     property: !ENV GOOGLE_ANALYTICS_KEY
@@ -132,6 +134,8 @@ markdown_extensions:
       emoji_index: !!python/name:materialx.emoji.twemoji
   - pymdownx.highlight:
       anchor_linenums: true
+      line_spans: __span
+      pygments_lang_class: true
   - pymdownx.inlinehilite
   - pymdownx.keys
   - pymdownx.magiclink: