From 93daab252d229e6ec2c9fd0a0a88eea4a191d4c3 Mon Sep 17 00:00:00 2001 From: squidfunk Date: Tue, 18 Oct 2022 14:23:32 +0700 Subject: [PATCH] Updated Insiders changelog and documentation --- CHANGELOG | 6 ++ docs/insiders/changelog.md | 6 ++ docs/insiders/index.md | 2 + docs/schema/plugins/privacy.json | 38 ++++++++--- docs/setup/ensuring-data-privacy.md | 100 ++++++++++++++++++++-------- 5 files changed, 118 insertions(+), 34 deletions(-) diff --git a/CHANGELOG b/CHANGELOG index 986cd571f..327e6153f 100644 --- a/CHANGELOG +++ b/CHANGELOG @@ -1,3 +1,9 @@ +mkdocs-material-8.5.6+insiders-4.26.0 (2022-10-18) + + * Refactored privacy plugin to prepare for new features + * Added support for rel=noopener links in privacy plugin + * Resolve encoding issues with blog and privacy plugin + mkdocs-material-8.5.6+insiders-4.25.5 (2022-10-16) * Updated MkDocs to 1.4.1 diff --git a/docs/insiders/changelog.md b/docs/insiders/changelog.md index c372ab91e..f85adf90e 100644 --- a/docs/insiders/changelog.md +++ b/docs/insiders/changelog.md @@ -6,6 +6,12 @@ template: overrides/main.html ## Material for MkDocs Insiders +### 4.26.0 _ October 18, 2022 { id="4.26.0" } + +- Refactored privacy plugin to prepare for new features +- Added support for `rel=noopener` links in privacy plugin +- Resolve encoding issues with blog and privacy plugin + ### 4.25.5 _ October 16, 2022 { id="4.25.5" } - Updated MkDocs to 1.4.1 diff --git a/docs/insiders/index.md b/docs/insiders/index.md index 5bf973246..1c307183f 100644 --- a/docs/insiders/index.md +++ b/docs/insiders/index.md @@ -307,9 +307,11 @@ are released for general availability. #### $ 20,000 – Jalapeño +- [x] [Privacy plugin: external links] - [ ] [Instant previews] - ... more to be announced + [Privacy plugin: external links]: ../setup/ensuring-data-privacy.md#+privacy.external_links [Instant previews]: https://twitter.com/squidfunk/status/1466794654213492743 ### Goals completed diff --git a/docs/schema/plugins/privacy.json b/docs/schema/plugins/privacy.json index f44b7ed7b..25fdc9c57 100644 --- a/docs/schema/plugins/privacy.json +++ b/docs/schema/plugins/privacy.json @@ -31,9 +31,9 @@ "type": "string", "default": ".cache/plugin/privacy" }, - "externals": { + "external_assets": { "title": "External assets", - "markdownDescription": "https://squidfunk.github.io/mkdocs-material/setup/ensuring-data-privacy/#+privacy.externals", + "markdownDescription": "https://squidfunk.github.io/mkdocs-material/setup/ensuring-data-privacy/#+privacy.external_assets", "oneOf": [ { "title": "Bundle external assets", @@ -50,23 +50,45 @@ ], "default": "bundle" }, - "externals_dir": { + "external_assets_dir": { "title": "External assets download directory", - "markdownDescription": "https://squidfunk.github.io/mkdocs-material/setup/ensuring-data-privacy/#+privacy.externals_dir", + "markdownDescription": "https://squidfunk.github.io/mkdocs-material/setup/ensuring-data-privacy/#+privacy.external_assets_dir", "type": "string", - "default": "assets/externals" + "default": "assets/external" }, - "externals_exclude": { + "external_assets_exclude": { "title": "External assets to be excluded", - "markdownDescription": "https://squidfunk.github.io/mkdocs-material/setup/ensuring-data-privacy/#+privacy.externals_exclude", + "markdownDescription": "https://squidfunk.github.io/mkdocs-material/setup/ensuring-data-privacy/#+privacy.external_assets_exclude", "type": "array", "items": { "title": "External assets matching this pattern will not be bundled", - "markdownDescription": "https://squidfunk.github.io/mkdocs-material/setup/ensuring-data-privacy/#+privacy.externals_exclude", + "markdownDescription": "https://squidfunk.github.io/mkdocs-material/setup/ensuring-data-privacy/#+privacy.external_assets_exclude", "pattern": ".*" }, "uniqueItems": true, "minItems": 1 + }, + "external_links": { + "title": "External links", + "markdownDescription": "https://squidfunk.github.io/mkdocs-material/setup/ensuring-data-privacy/#+privacy.external_links", + "type": "boolean", + "default": true + }, + "external_links_attr_map": { + "title": "Custom attributes to add to external links", + "markdownDescription": "https://squidfunk.github.io/mkdocs-material/setup/ensuring-data-privacy/#+privacy.external_links_attr_map", + "type": "object", + "patternProperties": { + "^[\\w_]+$": { + "type": "string" + } + } + }, + "external_links_noopener": { + "title": "Behavior for external links that open in new windows", + "markdownDescription": "https://squidfunk.github.io/mkdocs-material/setup/ensuring-data-privacy/#+privacy.external_links_noopener", + "type": "boolean", + "default": true } }, "additionalProperties": false diff --git a/docs/setup/ensuring-data-privacy.md b/docs/setup/ensuring-data-privacy.md index af87f1f55..cdac43cdb 100644 --- a/docs/setup/ensuring-data-privacy.md +++ b/docs/setup/ensuring-data-privacy.md @@ -159,14 +159,9 @@ the following lines to `mkdocs.yml`: ``` yaml plugins: - - privacy # (1)! + - privacy ``` -1. Note that the privacy plugin should be located at the end of the list of - `plugins`, as it will scan the resulting HTML for resources to download and - replace. If a plugin after the privacy plugin adds further - [external assets], these assets will not be downloaded. - > If you need to be able to build your documentation with and without > [Insiders], please refer to the [built-in plugins] section to learn how > shared configurations help to achieve this. @@ -185,7 +180,14 @@ The following configuration options are available: enabled: !ENV [CI, false] ``` -[`externals`](#+privacy.externals){ #+privacy.externals } + [Insiders]: ../insiders/index.md + [built-in plugins]: ../insiders/getting-started.md#built-in-plugins + +#### External assets + +The following configuration options are available for external assets: + +[`external_assets`](#+privacy.external_assets){ #+privacy.external_assets } : :octicons-milestone-24: Default: `bundle` – This option specifies what the plugin should do when encountering external assets. There are two options: @@ -195,7 +197,7 @@ The following configuration options are available: ``` yaml plugins: - privacy: - externals: bundle + external_assets: bundle ``` If you've removed all external assets from your project via [customization], @@ -206,10 +208,7 @@ The following configuration options are available: Using `report` in [strict mode] will make the build fail when external assets are detected. - [customization]: ../customization.md - [strict mode]: https://www.mkdocs.org/user-guide/configuration/#strict - -[`externals_dir`](#+privacy.externals_dir){ #+privacy.externals_dir } +[`external_assets_dir`](#+privacy.external_assets_dir){ #+privacy.external_assets_dir } : :octicons-milestone-24: Default: `assets/externals` – This option specifies where the downloaded [external assets] will be stored. It's @@ -218,10 +217,12 @@ The following configuration options are available: ``` yaml plugins: - privacy: - externals_dir: assets/externals + external_assets_dir: assets/externals ``` -[`externals_exclude`](#+privacy.externals_exclude){ #+privacy.externals_exclude } + The path must be defined relative to [`docs_dir`][docs_dir]. + +[`external_assets_exclude`](#+privacy.external_assets_exclude){ #+privacy.external_assets_exclude } : :octicons-milestone-24: Default: _none_ – This option allows to exclude certain external assets from processing by the privacy plugin, so they will @@ -230,7 +231,7 @@ The following configuration options are available: ``` yaml plugins: - privacy: - externals_exclude: # (1)! + external_assets_exclude: # (1)! - cdn.jsdelivr.net/npm/mathjax@3/* - giscus.app/* ``` @@ -247,16 +248,7 @@ The following configuration options are available: dynamically created or relative URLs, which can't be resolved by the privacy plugin due to [technical limitations]. - [Insiders]: ../insiders/index.md - [built-in plugins]: ../insiders/getting-started.md#built-in-plugins - [MathJax]: ../reference/mathjax.md - [MathJax can be self-hosted]: https://docs.mathjax.org/en/latest/web/hosting.html - [Giscus can be self-hosted]: https://github.com/giscus/giscus/blob/main/SELF-HOSTING.md - [comment system]: adding-a-comment-system.md - [external assets]: #how-it-works - [environment variable]: https://www.mkdocs.org/user-guide/configuration/#environment-variables - -??? question "Why can't Material for MkDocs bundle all assets by design?" +!!! question "Why can't Material for MkDocs bundle all assets by design?" The primary reason why Material for MkDocs can't just bundle all of its own assets is the integration with [Google Fonts], which offers over a thousand @@ -273,13 +265,69 @@ The following configuration options are available: This is the very reason the [built-in privacy plugin] exists — it automates the process of downloading all external assets manually to ensure compliance - with GDPR. Note that there are some [technical limitations]. + with GDPR with some some [technical limitations]. + [customization]: ../customization.md + [strict mode]: https://www.mkdocs.org/user-guide/configuration/#strict + [docs_dir]: https://www.mkdocs.org/user-guide/configuration/#docs_dir + [MathJax]: ../reference/mathjax.md + [MathJax can be self-hosted]: https://docs.mathjax.org/en/latest/web/hosting.html + [Giscus can be self-hosted]: https://github.com/giscus/giscus/blob/main/SELF-HOSTING.md + [comment system]: adding-a-comment-system.md + [external assets]: #how-it-works + [environment variable]: https://www.mkdocs.org/user-guide/configuration/#environment-variables [Google Fonts]: changing-the-fonts.md [regular font]: changing-the-fonts.md#regular-font [example]: #example [technical limitations]: #limitations +#### External links + +[:octicons-heart-fill-24:{ .mdx-heart } Sponsors only][Insiders]{ .mdx-insiders } · +[:octicons-tag-24: insiders-4.26.0][Insiders] · +:octicons-beaker-24: Experimental + +The following configuration options are available for external links: + +[`external_links`](#+privacy.external_links){ #+privacy.external_links } + +: :octicons-milestone-24: Default: `true` – This option specifies whether the + plugin should automatically annotate external links. By default, + [`rel="noopener"`][noopener] is added to all links with `target="_blank"`: + + ``` yaml + plugins: + - privacy: + external_links: true + ``` + +[`external_links_attr_map`](#+privacy.external_links_attr_map){ #+privacy.external_links_attr_map } + +: :octicons-milestone-24: Default: _None_ – This option specifies custom + attributes that should be added to external links, like for example + `target="_blank"` so all external links open in a new window: + + ``` yaml + plugins: + - privacy: + external_links_attr_map: + target: _blank + ``` + +[`external_links_noopener`](#+privacy.external_links_noopener){ #+privacy.external_links_noopener } + +: :octicons-milestone-24: Default: `true` – This option specifies whether the + plugin should automatically add [`rel="noopener"`][noopener] to all links + with `target="_blank"` for security reasons: + + ``` yaml + plugins: + - privacy: + external_links_noopener: true + ``` + + [noopener]: https://mathiasbynens.github.io/rel-noopener/ + #### How it works The [built-in privacy plugin] scans the resulting HTML for links to external