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