mirror of
https://github.com/squidfunk/mkdocs-material.git
synced 2024-11-23 23:21:00 +01:00
Updated Insiders changelog and documentation
This commit is contained in:
squidfunk
parent
b8161e0179
commit
93daab252d
@ -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
|
||||
|
||||
@ -6,6 +6,12 @@ template: overrides/main.html
|
||||
|
||||
## Material for MkDocs Insiders
|
||||
|
||||
### 4.26.0 <small>_ October 18, 2022</small> { 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 <small>_ October 16, 2022</small> { id="4.25.5" }
|
||||
|
||||
- Updated MkDocs to 1.4.1
|
||||
|
||||
@ -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
|
||||
|
||||
@ -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
|
||||
|
||||
@ -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
|
||||
|
||||
Loading…
Reference in New Issue
Block a user