OpenSourceArk/mkdocs-material
1
0
Fork 0
mirror of https://github.com/squidfunk/mkdocs-material.git synced 2024-06-14 11:52:32 +03:00
Code Issues Packages Projects Releases Wiki Activity

Documentation

Browse Source
This commit is contained in:
squidfunk 2023-05-08 18:58:32 +02:00
parent 5b9f6c972d
commit b0d59f2241
No known key found for this signature in database
GPG Key ID: 5ED40BC4F9C436DF
3 changed files with 156 additions and 109 deletions
Show Stats Download Patch File Download Diff File Expand all files Collapse all files

104
docs/schema/plugins/privacy.json
View File

@ -24,62 +24,60 @@
"concurrency": {
"title": "Concurrency (number of CPUs)",
"markdownDescription": "https://squidfunk.github.io/mkdocs-material/setup/ensuring-data-privacy/#+privacy.concurrency",
"type": "number"
"type": "number",
"default": 1
},
"external_assets": {
"title": "External assets",
"markdownDescription": "https://squidfunk.github.io/mkdocs-material/setup/ensuring-data-privacy/#+privacy.external_assets",
"oneOf": [
{
"title": "Bundle external assets",
"enum": ["bundle"]
},
{
"title": "Report external assets as warnings",
"enum": ["report"]
}
],
"default": "bundle"
},
"external_assets_dir": {
"title": "External assets download directory",
"markdownDescription": "https://squidfunk.github.io/mkdocs-material/setup/ensuring-data-privacy/#+privacy.external_assets_dir",
"type": "string",
"default": "assets/external"
},
"external_assets_include": {
"title": "External assets to include",
"markdownDescription": "https://squidfunk.github.io/mkdocs-material/setup/ensuring-data-privacy/#+privacy.external_assets_include",
"type": "array",
"items": {
"title": "External assets matching this pattern will be downloaded",
"markdownDescription": "https://squidfunk.github.io/mkdocs-material/setup/ensuring-data-privacy/#+privacy.external_assets_include",
"pattern": ".*"
},
"uniqueItems": true,
"minItems": 1
},
"external_assets_exclude": {
"title": "External assets to 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 downloaded",
"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",
"assets": {
"title": "Process external assets",
"markdownDescription": "https://squidfunk.github.io/mkdocs-material/setup/ensuring-data-privacy/#+privacy.assets",
"type": "boolean",
"default": true
},
"external_links_attr_map": {
"assets_fetch": {
"title": "Download external assets",
"markdownDescription": "https://squidfunk.github.io/mkdocs-material/setup/ensuring-data-privacy/#+privacy.assets_fetch",
"type": "boolean",
"default": true
},
"assets_fetch_dir": {
"title": "Download external assets to this directory",
"markdownDescription": "https://squidfunk.github.io/mkdocs-material/setup/ensuring-data-privacy/#+privacy.assets_fetch_dir",
"type": "string",
"default": "assets/external"
},
"assets_include": {
"title": "External assets to include",
"markdownDescription": "https://squidfunk.github.io/mkdocs-material/setup/ensuring-data-privacy/#+privacy.assets_include",
"type": "array",
"items": {
"title": "External assets matching this pattern will be downloaded",
"markdownDescription": "https://squidfunk.github.io/mkdocs-material/setup/ensuring-data-privacy/#+privacy.assets_include",
"pattern": ".*"
},
"uniqueItems": true,
"minItems": 1
},
"assets_exclude": {
"title": "External assets to exclude",
"markdownDescription": "https://squidfunk.github.io/mkdocs-material/setup/ensuring-data-privacy/#+privacy.assets_exclude",
"type": "array",
"items": {
"title": "External assets matching this pattern will not be downloaded",
"markdownDescription": "https://squidfunk.github.io/mkdocs-material/setup/ensuring-data-privacy/#+privacy.assets_exclude",
"pattern": ".*"
},
"uniqueItems": true,
"minItems": 1
},
"links": {
"title": "Process external links",
"markdownDescription": "https://squidfunk.github.io/mkdocs-material/setup/ensuring-data-privacy/#+privacy.links",
"type": "boolean",
"default": true
},
"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",
"markdownDescription": "https://squidfunk.github.io/mkdocs-material/setup/ensuring-data-privacy/#+privacy.links_attr_map",
"type": "object",
"patternProperties": {
"^[\\w_]+$": {
@ -87,9 +85,9 @@
}
}
},
"external_links_noopener": {
"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",
"markdownDescription": "https://squidfunk.github.io/mkdocs-material/setup/ensuring-data-privacy/#+privacy.links_noopener",
"type": "boolean",
"default": true
}

107
docs/schema/plugins/social.json
View File

@ -15,51 +15,90 @@
"markdownDescription": "https://squidfunk.github.io/mkdocs-material/setup/setting-up-social-cards/#built-in-social-plugin",
"type": "object",
"properties": {
"enabled": {
"title": "Enable plugin",
"markdownDescription": "https://squidfunk.github.io/mkdocs-material/setup/setting-up-social-cards/#+social.enabled",
"type": "boolean",
"default": true
},
"concurrency": {
"title": "Concurrency (number of CPUs)",
"markdownDescription": "https://squidfunk.github.io/mkdocs-material/setup/setting-up-social-cards/#+social.concurrency",
"type": "number",
"default": 1
},
"cards": {
"title": "Social card generation",
"title": "Social cards",
"markdownDescription": "https://squidfunk.github.io/mkdocs-material/setup/setting-up-social-cards/#+social.cards",
"type": "boolean",
"default": true
},
"cards_color": {
"title": "Social card color palette",
"markdownDescription": "https://squidfunk.github.io/mkdocs-material/setup/setting-up-social-cards/#+social.cards_color",
"type": "object",
"properties": {
"fill": {
"title": "Background fill color",
"markdownDescription": "https://squidfunk.github.io/mkdocs-material/setup/setting-up-social-cards/#+social.cards_color",
"type": "string"
},
"text": {
"title": "Foreground text color",
"markdownDescription": "https://squidfunk.github.io/mkdocs-material/setup/setting-up-social-cards/#+social.cards_color",
"type": "string"
}
},
"additionalProperties": false,
"required": [
"fill",
"text"
]
},
"cards_font": {
"$ref": "../assets/fonts.json"
},
"cards_dir": {
"title": "Social card directory",
"title": "Social cards directory",
"markdownDescription": "https://squidfunk.github.io/mkdocs-material/setup/setting-up-social-cards/#+social.cards_dir",
"type": "string",
"default": "assets/images/social"
},
"cards_layout_dir": {
"title": "Social cards layout directory",
"markdownDescription": "https://squidfunk.github.io/mkdocs-material/setup/setting-up-social-cards/#+social.cards_layout_dir",
"type": "string",
"default": "layouts"
},
"cards_layout": {
"title": "Social cards layout",
"markdownDescription": "https://squidfunk.github.io/mkdocs-material/setup/setting-up-social-cards/#+social.cards_layout",
"default": "default",
"enum": [
"default",
"default/accent",
"default/invert",
"default/variant"
]
},
"cards_layout_options": {
"title": "Social cards layout options",
"markdownDescription": "https://squidfunk.github.io/mkdocs-material/setup/setting-up-social-cards/#+social.cards_layout_options",
"type": "object"
},
"debug": {
"title": "Debug mode",
"markdownDescription": "https://squidfunk.github.io/mkdocs-material/setup/setting-up-social-cards/#+social.debug",
"type": "boolean",
"default": true
},
"debug_grid": {
"title": "Debug grid",
"markdownDescription": "https://squidfunk.github.io/mkdocs-material/setup/setting-up-social-cards/#+social.debug_grid",
"type": "boolean",
"default": true
},
"debug_grid_step": {
"title": "Debug grid step size",
"markdownDescription": "https://squidfunk.github.io/mkdocs-material/setup/setting-up-social-cards/#+social.debug_grid_step",
"type": "number",
"default": 32
},
"debug_color": {
"title": "Debug color",
"markdownDescription": "https://squidfunk.github.io/mkdocs-material/setup/setting-up-social-cards/#+social.debug_color",
"type": "string",
"default": "yellow"
},
"cache": {
"title": "Enable caching",
"markdownDescription": "https://squidfunk.github.io/mkdocs-material/setup/setting-up-social-cards/#+social.cache",
"type": "boolean",
"default": true
},
"cache_dir": {
"title": "Cache directory",
"markdownDescription": "https://squidfunk.github.io/mkdocs-material/setup/setting-up-social-cards/#+social.cache_dir",
"type": "string",
"default": ".cache/plugins/social"
}
},
"additionalProperties": false,
"defaultSnippets": [
{
"label": "cards_font",
"body": "cards_font: ${1:Roboto}"
}
]
"additionalProperties": false
}
},
"additionalProperties": false

54
docs/setup/ensuring-data-privacy.md
View File

@ -199,28 +199,38 @@ The following configuration options are available:
The following configuration options are available for external assets:
[`external_assets`](#+privacy.external_assets){ #+privacy.external_assets }
[`assets`](#+privacy.assets){ #+privacy.assets }
: :octicons-milestone-24: Default: `bundle` – This option specifies what the
plugin should do when encountering external assets. There are two options:
while `report` will issue warning messages during the build, `bundle` will
automatically download all external files and adjust all references:
: :octicons-milestone-24: Default: `true` – This option specifies whether the
plugin should scan the HTML output to detect and process external assets:
``` yaml
plugins:
- privacy:
external_assets: bundle
assets: true
```
If you've removed all external assets from your project via [customization],
it's still a good idea to enable the plugin and set the mode to `report`,
as the plugin will make sure that there are no hidden external links in any
Markdown files that were unintentionally added.
it's still a good idea to enable the plugin, as the plugin will make sure
that there are no hidden external links in any Markdown files that were
unintentionally added.
Using `report` in [strict mode] will make the build fail when external
Using `assets` in [strict mode] will make the build fail when external
assets are detected.
[`external_assets_dir`](#+privacy.external_assets_dir){ #+privacy.external_assets_dir }
[`assets_fetch`](#+privacy.assets_fetch){ #+privacy.assets_fetch }
: :octicons-milestone-24: Default: `true` – This option specifies whether the
plugin should download external assets it encountered and bundle them with
your documentation:
``` yaml
plugins:
- privacy:
assets_fetch: true
```
[`assets_fetch_dir`](#+privacy.assets_fetch_dir){ #+privacy.assets_fetch_dir }
: :octicons-milestone-24: Default: `assets/external` – This option
specifies where the downloaded [external assets] will be stored. It's
@ -229,12 +239,12 @@ The following configuration options are available for external assets:
``` yaml
plugins:
- privacy:
external_assets_dir: assets/external
assets_fetch_dir: assets/external
```
The path must be defined relative to [`docs_dir`][docs_dir].
[`external_assets_include`](#+privacy.external_assets_include){ #+privacy.external_assets_include } :material-alert-decagram:{ .mdx-pulse title="Added on February 6, 2023" }
[`assets_include`](#+privacy.assets_include){ #+privacy.external_assets_include }
: :octicons-milestone-24: Default: _none_ – This option allows to only include
certain external assets for processing by the privacy plugin, so they will
@ -243,7 +253,7 @@ The following configuration options are available for external assets:
``` yaml
plugins:
- privacy:
external_assets_include:
assets_include:
- unsplash.com/*
```
@ -265,7 +275,7 @@ The following configuration options are available for external assets:
differently from others or exclude some images from downloading, you can
use multiple instances of the [built-in privacy plugin].
[`external_assets_exclude`](#+privacy.external_assets_exclude){ #+privacy.external_assets_exclude }
[`assets_exclude`](#+privacy.assets_exclude){ #+privacy.assets_exclude }
: :octicons-milestone-24: Default: _none_ – This option allows to exclude
certain external assets from processing by the privacy plugin, so they will
@ -274,7 +284,7 @@ The following configuration options are available for external assets:
``` yaml
plugins:
- privacy:
external_assets_exclude: # (1)!
assets_exclude: # (1)!
- cdn.jsdelivr.net/npm/mathjax@3/*
- giscus.app/*
```
@ -333,7 +343,7 @@ The following configuration options are available for external assets:
The following configuration options are available for external links:
[`external_links`](#+privacy.external_links){ #+privacy.external_links }
[`links`](#+privacy.links){ #+privacy.links }
: :octicons-milestone-24: Default: `true` – This option specifies whether the
plugin should parse and process external links. If you want to speed up
@ -342,10 +352,10 @@ The following configuration options are available for external links:
``` yaml
plugins:
- privacy:
external_links: !ENV [CI, false]
links: !ENV [CI, false]
```
[`external_links_attr_map`](#+privacy.external_links_attr_map){ #+privacy.external_links_attr_map }
[`links_attr_map`](#+privacy.links_attr_map){ #+privacy.links_attr_map }
: :octicons-milestone-24: Default: _None_ – This option specifies custom
attributes that should be added to external links, like for example
@ -354,11 +364,11 @@ The following configuration options are available for external links:
``` yaml
plugins:
- privacy:
external_links_attr_map:
links_attr_map:
target: _blank
```
[`external_links_noopener`](#+privacy.external_links_noopener){ #+privacy.external_links_noopener }
[`links_noopener`](#+privacy.links_noopener){ #+privacy.links_noopener }
: :octicons-milestone-24: Default: `true` – This option specifies whether the
plugin should automatically add [`rel="noopener"`][noopener] to all links
@ -367,7 +377,7 @@ The following configuration options are available for external links:
``` yaml
plugins:
- privacy:
external_links_noopener: true
links_noopener: true
```
[noopener]: https://mathiasbynens.github.io/rel-noopener/