diff --git a/CHANGELOG b/CHANGELOG index 6375f1a72..de428a471 100644 --- a/CHANGELOG +++ b/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 diff --git a/docs/changelog/index.md b/docs/changelog/index.md index b153eb334..7886a4db8 100644 --- a/docs/changelog/index.md +++ b/docs/changelog/index.md @@ -6,6 +6,16 @@ template: overrides/main.html ## Material for MkDocs +### 8.1.0 _ December 10, 2021 { 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 _ December 6, 2021 { id="8.0.5" } - Fixed #3302: Footer refactoring induced ellipsis in some browsers diff --git a/docs/customization.md b/docs/customization.md index e00f5fbda..1b4d11585 100644 --- a/docs/customization.md +++ b/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 . diff --git a/docs/reference/code-blocks.md b/docs/reference/code-blocks.md index 0e11886a0..5ff5ea3d1 100644 --- a/docs/reference/code-blocks.md +++ b/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=""` @@ -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 diff --git a/docs/setup/extensions/python-markdown-extensions.md b/docs/setup/extensions/python-markdown-extensions.md index 67bda2e46..f09e791d2 100644 --- a/docs/setup/extensions/python-markdown-extensions.md +++ b/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 diff --git a/material/base.html b/material/base.html index 5ddaeaf78..338ad2782 100644 --- a/material/base.html +++ b/material/base.html @@ -22,7 +22,7 @@ {% endif %} - + {% endblock %} {% block htmltitle %} {% if page and page.meta and page.meta.title %} diff --git a/mkdocs.yml b/mkdocs.yml index 2a8f104ec..cd2276de0 100755 --- a/mkdocs.yml +++ b/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: diff --git a/package-lock.json b/package-lock.json index 871c0a968..5ac823158 100644 --- a/package-lock.json +++ b/package-lock.json @@ -1,6 +1,6 @@ { "name": "mkdocs-material", - "version": "8.0.5", + "version": "8.1.0", "lockfileVersion": 1, "requires": true, "dependencies": { diff --git a/package.json b/package.json index 318053ae3..47160209d 100644 --- a/package.json +++ b/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",