diff --git a/CHANGELOG b/CHANGELOG index d9da2d3e4..291593e5a 100644 --- a/CHANGELOG +++ b/CHANGELOG @@ -1,3 +1,12 @@ +mkdocs-material-8.3.4+insiders-4.18.0 (2022-06-11) + + * Added support for automatic dark/light mode + * Fixed #4009: Privacy plugin uses invalid paths for file cache on Windows + +mkdocs-material-8.3.4 (2022-06-11) + + * Fixed #4004: Tags with multiple words not searchable + mkdocs-material-8.3.3 (2022-06-07) * Fixed #4000: Mermaid diagrams too dark in dark mode (8.3.0 regression) diff --git a/docs/changelog/index.md b/docs/changelog/index.md index a1598dce0..c0e9834e5 100644 --- a/docs/changelog/index.md +++ b/docs/changelog/index.md @@ -6,6 +6,10 @@ template: overrides/main.html ## Material for MkDocs +### 8.3.3 _ June 11, 2022 { id="8.3.3" } + +- Fixed #4004: Tags with multiple words not searchable + ### 8.3.3 _ June 7, 2022 { id="8.3.3" } - Fixed #4000: Mermaid diagrams too dark in dark mode (8.3.0 regression) diff --git a/docs/insiders/changelog.md b/docs/insiders/changelog.md index a03132747..ea21d20bc 100644 --- a/docs/insiders/changelog.md +++ b/docs/insiders/changelog.md @@ -6,6 +6,11 @@ template: overrides/main.html ## Material for MkDocs Insiders +### 4.18.0 _ June 11, 2022 { id="4.18.0" } + +- Added support for automatic dark/light mode +- Fixed #4009: Privacy plugin uses invalid paths for file cache on Windows + ### 4.17.2 _ June 5, 2022 { id="4.17.2" } - Added support for custom jieba dictionaries (Chinese search) diff --git a/docs/insiders/index.md b/docs/insiders/index.md index a6dd5ca5a..e55b256ac 100644 --- a/docs/insiders/index.md +++ b/docs/insiders/index.md @@ -178,9 +178,10 @@ which are currently exclusively available to sponsors:
+- [x] [Automatic light / dark mode] :material-alert-decagram:{ .mdx-pulse title="Added on June 11, 2022" } - [x] [Content tabs: anchor links] :material-alert-decagram:{ .mdx-pulse title="Added on June 4, 2022" } - [x] [Navigation pruning] :material-alert-decagram:{ .mdx-pulse title="Added on May 25, 2022" } -- [x] [Tooltips] :material-alert-decagram:{ .mdx-pulse title="Added on May 8, 2022" } +- [x] [Tooltips] - [x] [Chinese search support] - [x] [Tag icons] - [x] [Card grids] @@ -189,6 +190,7 @@ which are currently exclusively available to sponsors: - [x] [Table of contents anchor following] - [x] [Annotations] - [x] [Navigation icons] +- [x] Sidebars automatically scroll to active item - [x] [Code annotations: anchor links] - [x] [Code annotations: strip comments] - [x] [Dismissable announcement bar] @@ -274,13 +276,14 @@ are released for general availability. - [x] [Card grids] - [x] [Tooltips] - [x] [Content tabs: anchor links] -- [ ] Intelligent color palette (system preference) +- [x] [Automatic light / dark mode] - [ ] Document authors/contributors [Privacy plugin]: ../setup/ensuring-data-privacy.md [Card grids]: ../reference/grids.md [Tooltips]: ../reference/tooltips.md [Content tabs: anchor links]: ../reference/content-tabs.md#anchor-links + [Automatic light / dark mode]: ../setup/changing-the-colors.md#automatic-light-dark-mode #### $ 16,000 – Chipotle diff --git a/docs/reference/tooltips.md b/docs/reference/tooltips.md index 7dd84e367..f3832ac43 100644 --- a/docs/reference/tooltips.md +++ b/docs/reference/tooltips.md @@ -33,7 +33,7 @@ See additional configuration options: [Attribute Lists]: ../setup/extensions/python-markdown.md#attribute-lists [Snippets]: ../setup/extensions/python-markdown-extensions.md#snippets -### Improved tooltips :material-alert-decagram:{ .mdx-pulse title="Added on May 8, 2022" } +### Improved tooltips [:octicons-heart-fill-24:{ .mdx-heart } Sponsors only][Insiders]{ .mdx-insiders } · [:octicons-tag-24: insiders-4.15.0][Insiders] · diff --git a/docs/setup/changing-the-colors.md b/docs/setup/changing-the-colors.md index ecd17c017..1f8a9500f 100644 --- a/docs/setup/changing-the-colors.md +++ b/docs/setup/changing-the-colors.md @@ -21,8 +21,8 @@ fit your brand's identity by using [CSS variables][custom colors]. [:octicons-tag-24: 5.2.0][palette.scheme support] · :octicons-milestone-24: Default: `default` -Material for MkDocs supports two color schemes: a light mode, which is just -called `default`, and a dark mode, which is called `slate`. The color scheme +Material for MkDocs supports two color schemes: a __light mode__, which is just +called `default`, and a __dark mode__, which is called `slate`. The color scheme can be set via `mkdocs.yml`: ``` yaml @@ -169,21 +169,24 @@ Click on a tile to change the accent color: [:octicons-tag-24: 7.1.0][palette.toggle support] · :octicons-milestone-24: Default: _none_ -It's also possible to offer a list of color palettes to the user, each of which -can include a [`scheme`][palette.scheme], [`primary`][palette.primary] and -[`accent`][palette.accent] color each. The user can toggle between those color -palettes: +Offering a light _and_ dark color palette makes your documentation pleasant to +read at different times of the day, so the user can choose accordingly. Add the +following lines to `mkdocs.yml`: ``` yaml theme: palette: # (1)! + + # Palette toggle for light mode - scheme: default toggle: - icon: material/toggle-switch # (2)! + icon: material/brightness-7 # (2)! name: Switch to dark mode + + # Palette toggle for dark mode - scheme: slate # (3)! toggle: - icon: material/toggle-switch-off-outline + icon: material/brightness-4 name: Switch to light mode ``` @@ -193,7 +196,7 @@ theme: click on the shortcode to copy it to your clipboard:
- +
    @@ -206,6 +209,10 @@ theme: sure that the color combination of your choosing provides enough contrast and tweak CSS variables where necessary. +This configuration will render a color palette toggle next to the search bar. +Note that you can also define separate settings for [`scheme`][palette.scheme], +[`primary`][palette.primary] and [`accent`][palette.accent] per color palette. + The following properties must be set for each toggle: `icon`{ #toggle-icon } @@ -214,59 +221,101 @@ The following properties must be set for each toggle: This property must point to a valid icon path referencing any icon bundled with the theme, or the build will not succeed. Some popular combinations: + * :material-brightness-7: + :material-brightness-4: – `material/brightness-7` + `material/brightness-4` * :material-toggle-switch: + :material-toggle-switch-off-outline: – `material/toggle-switch` + `material/toggle-switch-off-outline` * :material-weather-night: + :material-weather-sunny: – `material/weather-night` + `material/weather-sunny` * :material-eye: + :material-eye-outline: – `material/eye` + `material/eye-outline` * :material-lightbulb: + :material-lightbulb-outline: – `material/lightbulb` + `material/lightbulb-outline` - * :material-brightness-7: + :material-brightness-4: – `material/brightness-7` + `material/brightness-4` `name`{ #toggle-name } : :octicons-milestone-24: Default: _none_ · :octicons-alert-24: Required – - This property is used as the toggle's `title` attribute and should be set to a - discernable name to improve accessibility. It will appear on mouse hover. + This property is used as the toggle's `title` attribute and should be set to + a discernable name to improve accessibility. It's rendered as a [tooltip]. [palette.toggle support]: https://github.com/squidfunk/mkdocs-material/releases/tag/7.1.0 [palette.scheme]: #color-scheme [palette.primary]: #primary-color [palette.accent]: #accent-color [icon search]: ../reference/icons-emojis.md#search + [tooltip]: ../reference/tooltips.md ### System preference [:octicons-tag-24: 7.1.0][palette.media support] · :octicons-milestone-24: Default: _none_ -In order to automatically set the color palette to the user's system preference, -a media query can be set as part of the `media` property next to the toggle -definition in `mkdocs.yml`: +Each color palette can be linked to the user's system preference for light and +dark appearance by using a media query. Simply add a `media` property next to +the `scheme` definition in `mkdocs.yml`: ``` yaml theme: palette: - - media: "(prefers-color-scheme: light)" # (1)! + + # Palette toggle for light mode + - media: "(prefers-color-scheme: light)" scheme: default toggle: - icon: material/toggle-switch-off-outline + icon: material/brightness-7 name: Switch to dark mode - - media: "(prefers-color-scheme: dark)" # (2)! + + # Palette toggle for dark mode + - media: "(prefers-color-scheme: dark)" scheme: slate toggle: - icon: material/toggle-switch + icon: material/brightness-4 name: Switch to light mode ``` -1. This media query is __checked first__. It's also the __fallback__ when no - media query matches. -2. This media query is __checked second__. If it doesn't match, the first one - is automatically used. - When the user first visits your site, the media queries are evaluated in the order of their definition. The first media query that matches selects the default color palette. [palette.media support]: https://github.com/squidfunk/mkdocs-material/releases/tag/7.1.0 +#### Automatic light / dark mode :material-alert-decagram:{ .mdx-pulse title="Added on June 11, 2022" } + +[:octicons-heart-fill-24:{ .mdx-heart } Sponsors only][Insiders]{ .mdx-insiders } · +[:octicons-tag-24: insiders-4.18.0][Insiders] · +:octicons-beaker-24: Experimental + +Newer operating system allow to automatically switch between light and dark +appearance during day and night times. [Insiders] adds support for automatic +light/dark mode, delegating color palette selection to the user's operating +system. Add the following lines to `mkdocs.yml`: + +``` yaml +theme: + palette: + + # Palette toggle for automatic mode + - media: "(prefers-color-scheme)" + toggle: + icon: material/brightness-auto + name: Switch to light mode + + # Palette toggle for light mode + - media: "(prefers-color-scheme: light)" + scheme: default + toggle: + icon: material/brightness-7 + name: Switch to dark mode + + # Palette toggle for dark mode + - media: "(prefers-color-scheme: dark)" + scheme: slate + toggle: + icon: material/brightness-4 + name: Switch to system preference +``` + +Material for MkDocs will now change the color palette each time the operating +system switches between light and dark appearance, even when the user doesn't +reload the site. + + [Insiders]: ../insiders/index.md + ## Customization ### Custom colors diff --git a/material/base.html b/material/base.html index bee4f48f4..3359e3ef3 100644 --- a/material/base.html +++ b/material/base.html @@ -22,7 +22,7 @@ {% endif %} - + {% endblock %} {% block htmltitle %} {% if page.meta and page.meta.title %} diff --git a/mkdocs.yml b/mkdocs.yml index 9858ed927..97368583e 100755 --- a/mkdocs.yml +++ b/mkdocs.yml @@ -72,13 +72,13 @@ theme: primary: indigo accent: indigo toggle: - icon: material/toggle-switch + icon: material/brightness-7 name: Switch to dark mode - scheme: slate primary: indigo accent: indigo toggle: - icon: material/toggle-switch-off-outline + icon: material/brightness-4 name: Switch to light mode font: text: Roboto diff --git a/package-lock.json b/package-lock.json index 7e849efcc..9630a96af 100644 --- a/package-lock.json +++ b/package-lock.json @@ -1,12 +1,12 @@ { "name": "mkdocs-material", - "version": "8.3.3", + "version": "8.3.4", "lockfileVersion": 2, "requires": true, "packages": { "": { "name": "mkdocs-material", - "version": "8.3.3", + "version": "8.3.4", "license": "MIT", "dependencies": { "array-flat-polyfill": "^1.0.1", diff --git a/package.json b/package.json index f3b97338b..24939271d 100644 --- a/package.json +++ b/package.json @@ -1,6 +1,6 @@ { "name": "mkdocs-material", - "version": "8.3.3", + "version": "8.3.4", "description": "Documentation that simply works", "keywords": [ "mkdocs",