From b0d59f2241baaa380468614ae0b8880f4c6ca9e8 Mon Sep 17 00:00:00 2001 From: squidfunk Date: Mon, 8 May 2023 18:58:32 +0200 Subject: [PATCH] Documentation --- docs/schema/plugins/privacy.json | 104 +++++++++++++-------------- docs/schema/plugins/social.json | 107 +++++++++++++++++++--------- docs/setup/ensuring-data-privacy.md | 54 ++++++++------ 3 files changed, 156 insertions(+), 109 deletions(-) diff --git a/docs/schema/plugins/privacy.json b/docs/schema/plugins/privacy.json index 4afa6559f..aaa36b830 100644 --- a/docs/schema/plugins/privacy.json +++ b/docs/schema/plugins/privacy.json @@ -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 } diff --git a/docs/schema/plugins/social.json b/docs/schema/plugins/social.json index 161d7cf8c..668caa87a 100644 --- a/docs/schema/plugins/social.json +++ b/docs/schema/plugins/social.json @@ -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 diff --git a/docs/setup/ensuring-data-privacy.md b/docs/setup/ensuring-data-privacy.md index 0d4e8896c..693a99cc8 100644 --- a/docs/setup/ensuring-data-privacy.md +++ b/docs/setup/ensuring-data-privacy.md @@ -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/