Skip to content

Commit

Permalink
Documentation
Browse files Browse the repository at this point in the history
  • Loading branch information
@squidfunk
squidfunk committed May 8, 2023
1 parent 5b9f6c9 commit b0d59f2
Show file tree
Hide file tree
Showing 3 changed files with 134 additions and 87 deletions.
60 changes: 29 additions & 31 deletions docs/schema/plugins/privacy.json
View file
Original file line number Diff line number Diff line change
Expand Up @@ -24,72 +24,70 @@
"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"
"assets": {
"title": "Process external assets",
"markdownDescription": "https://squidfunk.github.io/mkdocs-material/setup/ensuring-data-privacy/#+privacy.assets",
"type": "boolean",
"default": true
},
"assets_fetch": {
"title": "Download external assets",
"markdownDescription": "https://squidfunk.github.io/mkdocs-material/setup/ensuring-data-privacy/#+privacy.assets_fetch",
"type": "boolean",
"default": true
},
"external_assets_dir": {
"title": "External assets download directory",
"markdownDescription": "https://squidfunk.github.io/mkdocs-material/setup/ensuring-data-privacy/#+privacy.external_assets_dir",
"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"
},
"external_assets_include": {
"assets_include": {
"title": "External assets to include",
"markdownDescription": "https://squidfunk.github.io/mkdocs-material/setup/ensuring-data-privacy/#+privacy.external_assets_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.external_assets_include",
"markdownDescription": "https://squidfunk.github.io/mkdocs-material/setup/ensuring-data-privacy/#+privacy.assets_include",
"pattern": ".*"
},
"uniqueItems": true,
"minItems": 1
},
"external_assets_exclude": {
"assets_exclude": {
"title": "External assets to exclude",
"markdownDescription": "https://squidfunk.github.io/mkdocs-material/setup/ensuring-data-privacy/#+privacy.external_assets_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.external_assets_exclude",
"markdownDescription": "https://squidfunk.github.io/mkdocs-material/setup/ensuring-data-privacy/#+privacy.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",
"links": {
"title": "Process external links",
"markdownDescription": "https://squidfunk.github.io/mkdocs-material/setup/ensuring-data-privacy/#+privacy.links",
"type": "boolean",
"default": true
},
"external_links_attr_map": {
"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_]+$": {
"type": "string"
}
}
},
"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
}
Expand Down
107 changes: 73 additions & 34 deletions docs/schema/plugins/social.json
View file
Original file line number Diff line number Diff line change
Expand Up @@ -15,51 +15,90 @@
"markdownDescription": "https://squidfunk.github.io/mkdocs-material/setup/setting-up-social-cards/#built-in-social-plugin",
"type": "object",
"properties": {
"cards": {
"title": "Social card generation",
"markdownDescription": "https://squidfunk.github.io/mkdocs-material/setup/setting-up-social-cards/#+social.cards",
"enabled": {
"title": "Enable plugin",
"markdownDescription": "https://squidfunk.github.io/mkdocs-material/setup/setting-up-social-cards/#+social.enabled",
"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"
]
"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_font": {
"$ref": "../assets/fonts.json"
"cards": {
"title": "Social cards",
"markdownDescription": "https://squidfunk.github.io/mkdocs-material/setup/setting-up-social-cards/#+social.cards",
"type": "boolean",
"default": true
},
"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
Expand Down
54 changes: 32 additions & 22 deletions docs/setup/ensuring-data-privacy.md
View file
Original file line number Diff line number Diff line change
Expand Up @@ -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
Expand All @@ -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
Expand All @@ -243,7 +253,7 @@ The following configuration options are available for external assets:
``` yaml
plugins:
- privacy:
external_assets_include:
assets_include:
- unsplash.com/*
```

Expand All @@ -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
Expand All @@ -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/*
```
Expand Down Expand Up @@ -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
Expand All @@ -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
Expand All @@ -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
Expand All @@ -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/
Expand Down

0 comments on commit b0d59f2

Please sign in to comment.