diff --git a/docs/blog/posts/the-past-present-and-future.md b/docs/blog/posts/the-past-present-and-future.md index 2cd783f36..a95a72214 100644 --- a/docs/blog/posts/the-past-present-and-future.md +++ b/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 diff --git a/docs/insiders/index.md b/docs/insiders/index.md index 7622404d4..6b4970e76 100644 --- a/docs/insiders/index.md +++ b/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:
+- [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 diff --git a/docs/reference/code-blocks.md b/docs/reference/code-blocks.md index a8db1b723..f75b0eefd 100644 --- a/docs/reference/code-blocks.md +++ b/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. 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. [`.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. - [Anchor links support]: https://github.com/squidfunk/mkdocs-material/releases/tag/8.5.0 + __Important__: Code annotations cannot be split between lexemes. + +Now, code annotations can be used from within strings in JSON: + +``` json +{ + "key": "value (1)" +} +``` + +1. :man_raising_hand: I'm a code annotation! I can contain `code`, __formatted + text__, images, ... basically anything that can be written in Markdown. + + [placed in comments]: #adding-annotations + [s2]: https://github.com/squidfunk/mkdocs-material/blob/87d5ca487b9d9ab95c41ee72813149d214048693/src/assets/stylesheets/main/extensions/pymdownx/_highlight.scss#L45 ## Usage diff --git a/docs/setup/ensuring-data-privacy.md b/docs/setup/ensuring-data-privacy.md index 6a1b35db5..5f2417963 100644 --- a/docs/setup/ensuring-data-privacy.md +++ b/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] · diff --git a/mkdocs.yml b/mkdocs.yml index 4904602cd..907a04493 100755 --- a/mkdocs.yml +++ b/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: