diff --git a/CHANGELOG b/CHANGELOG index 3409835df..9936d3d6d 100644 --- a/CHANGELOG +++ b/CHANGELOG @@ -1,3 +1,7 @@ +mkdocs-material-9.5.4+insiders-4.50.0 (2024-01-19) + + * Added configurable logging capabilities to privacy plugin + mkdocs-material-9.5.4 (2024-01-15) * Fixed #6645: Local storage with invalid value can break site diff --git a/docs/insiders/changelog/index.md b/docs/insiders/changelog/index.md index bbffe7ff6..8c615cf2f 100644 --- a/docs/insiders/changelog/index.md +++ b/docs/insiders/changelog/index.md @@ -2,6 +2,10 @@ ## Material for MkDocs Insiders +### 4.50.0 January 19, 2024 { id="4.50.0" } + +- Added configurable logging capabilities to privacy plugin + ### 4.49.2 January 9, 2024 { id="4.49.2" } - Fixed missing attribute lists extension for tags plugin diff --git a/docs/insiders/index.md b/docs/insiders/index.md index ba65c0db5..8e6b7890d 100644 --- a/docs/insiders/index.md +++ b/docs/insiders/index.md @@ -105,7 +105,7 @@ which are currently exclusively available to sponsors: - [x] [Social plugin: background images] - [x] [Code range selection] - [x] [Code annotations: custom selectors] -- [x] [Privacy plugin: optimization support] +- [x] [Privacy plugin: advanced settings] - [x] [Optimize plugin] - [x] [Navigation path] (Breadcrumbs) - [x] [Typeset plugin] @@ -277,8 +277,8 @@ are released for general availability. [Blog plugin: related links]: ../setup/setting-up-a-blog.md#adding-related-links [Blog plugin: custom index pages]: ../setup/setting-up-a-blog.md#custom-index-pages [Tags plugin: configurable listings]: ../setup/setting-up-tags.md#configurable-listings - [Tags plugin: allow list]: ../setup/setting-up-tags.md#+tags.tags_allowed - [custom sorting]: ../setup/setting-up-tags.md#+tags.tags_compare + [Tags plugin: allow list]: ../plugins/tags.md#config.tags_allowed + [custom sorting]: ../plugins/tags.md#config.tags_sort_by [Navigation subtitles]: ../reference/index.md#setting-the-page-subtitle #### $ 20,000 – Jalapeño @@ -286,7 +286,7 @@ are released for general availability. - [x] [Optimize plugin] - [x] [Typeset plugin] - [x] [Navigation path] (Breadcrumbs) -- [x] [Privacy plugin: optimization support] +- [x] [Privacy plugin: advanced settings] - [x] [Privacy plugin: external links] - [x] [Instant prefetching] - [x] [Blog plugin: advanced settings] @@ -294,8 +294,8 @@ are released for general availability. [Optimize plugin]: ../plugins/optimize.md [Typeset plugin]: ../plugins/typeset.md - [Privacy plugin: external links]: ../setup/ensuring-data-privacy.md#+privacy.links - [Privacy plugin: optimization support]: ../setup/ensuring-data-privacy.md#+privacy.assets_include + [Privacy plugin: external links]: ../plugins/privacy.md#external-links + [Privacy plugin: advanced settings]: ../setup/ensuring-data-privacy.md#advanced-settings [Navigation path]: ../setup/setting-up-navigation.md#navigation-path [Instant prefetching]: ../setup/setting-up-navigation.md#instant-prefetching [Blog plugin: advanced settings]: ../setup/setting-up-a-blog.md#advanced-settings @@ -314,7 +314,7 @@ are released for general availability. [Projects plugin]: ../plugins/projects.md [Social plugin: custom layouts]: ../setup/setting-up-social-cards.md#customization - [Social plugin: background images]: ../setup/setting-up-social-cards.md#+social.cards_layout_params.background_image + [Social plugin: background images]: ../plugins/social.md#option.background_image [Code range selection]: ../reference/code-blocks.md#code-selection-button [Code annotations: custom selectors]: ../reference/code-blocks.md#custom-selectors [Stay on page when switching languages]: ../setup/changing-the-language.md#stay-on-page diff --git a/docs/plugins/privacy.md b/docs/plugins/privacy.md index ce3000984..4bd91d3a3 100644 --- a/docs/plugins/privacy.md +++ b/docs/plugins/privacy.md @@ -213,6 +213,84 @@ with each other. [multiple instances]: index.md#multiple-instances +### Logging + +The following settings are available for logging: + +--- + +#### + + + + + +Use this setting to control whether the plugin should display log messages when +building your site. While not being recommended, you can disable logging with: + +``` yaml +plugins: + - privacy: + log: false +``` + +--- + +#### + + + + + +Use this setting to control the log level that the plugin should employ when +encountering errors, which requires that the [`log`][config.log] setting is +enabled. The following log levels are available: + +=== "`error`" + + ``` yaml + plugins: + - privacy: + log_level: error + ``` + + Only errors are reported. + +=== "`warn`" + + ``` yaml + plugins: + - privacy: + log_level: warn + ``` + + Errors and warnings are reported, terminating the build in + [`strict`][mkdocs.strict] mode. This includes warnings when symlinks cannot + be created due to a lack of permissions on Windows systems (#6550). + +=== "`info`" + + ``` yaml + plugins: + - privacy: + log_level: info + ``` + + Errors, warnings and informational messages are reported, including which + assets were successfully downloaded by the plugin. + +=== "`debug`" + + ``` yaml + plugins: + - privacy: + log_level: debug + ``` + + All messages are reported, including debug messages, if and only if MkDocs + was started with the `--verbose` flag. Note that this will print a lot of + messages and is only useful for debugging. + ### External assets The following settings are available for external assets: diff --git a/docs/schema/plugins/privacy.json b/docs/schema/plugins/privacy.json index d884e616c..1233ac549 100644 --- a/docs/schema/plugins/privacy.json +++ b/docs/schema/plugins/privacy.json @@ -36,6 +36,23 @@ "type": "string", "default": ".cache/plugins/privacy" }, + "log": { + "title": "Enable logging", + "markdownDescription": "https://squidfunk.github.io/mkdocs-material/plugins/privacy/#config.log", + "type": "boolean", + "default": true + }, + "log_level": { + "title": "Log level", + "markdownDescription": "https://squidfunk.github.io/mkdocs-material/plugins/privacy/#config.log_level", + "enum": [ + "error", + "warn", + "info", + "debug" + ], + "default": "info" + }, "assets": { "title": "Process external assets", "markdownDescription": "https://squidfunk.github.io/mkdocs-material/plugins/privacy/#config.assets", diff --git a/docs/schema/plugins/projects.json b/docs/schema/plugins/projects.json index 29dac4aa5..74b4be89a 100644 --- a/docs/schema/plugins/projects.json +++ b/docs/schema/plugins/projects.json @@ -51,7 +51,7 @@ "info", "debug" ], - "default": "warn" + "default": "info" }, "projects": { "title": "Enable projects", diff --git a/docs/setup/ensuring-data-privacy.md b/docs/setup/ensuring-data-privacy.md index c2a379b6b..1194f2696 100644 --- a/docs/setup/ensuring-data-privacy.md +++ b/docs/setup/ensuring-data-privacy.md @@ -206,7 +206,6 @@ For a list of all settings, please consult the [plugin documentation]. [example]: #example [built-in optimize plugin]: ../plugins/optimize.md - ??? example "Expand to inspect example" For the official documentation, the [built-in privacy plugin] downloads the @@ -280,6 +279,24 @@ For a list of all settings, please consult the [plugin documentation]. [built-in privacy plugin]: ../plugins/privacy.md [preconnect]: https://developer.mozilla.org/en-US/docs/Web/Performance/dns-prefetch +#### Advanced settings + + + + +The following advanced settings are currently reserved to our [sponsors] +[Insiders]. They are entirely optional, and don't affect the functionality of +the blog, but can be helpful for customizations: + +- [`log`][config.log] +- [`log_level`][config.log_level] + +We'll add more settings here, as we discover new use cases. + + [Insiders]: ../insiders/index.md + [config.log]: ../plugins/privacy.md#config.log + [config.log_level]: ../plugins/privacy.md#config.log_level + ## Customization ### Custom cookies