Documentation

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": {
+            "assets": {
-              "title": "External assets",
+              "title": "Process external assets",
-              "markdownDescription": "https://squidfunk.github.io/mkdocs-material/setup/ensuring-data-privacy/#+privacy.external_assets",
+              "markdownDescription": "https://squidfunk.github.io/mkdocs-material/setup/ensuring-data-privacy/#+privacy.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",
               "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
             }

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,
+          "additionalProperties": false
-          "defaultSnippets": [
-            {
-              "label": "cards_font",
-              "body": "cards_font: ${1:Roboto}"
-            }
-          ]
         }
       },
       "additionalProperties": false

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
+:   :octicons-milestone-24: Default: `true` – This option specifies whether the
-    plugin should do when encountering external assets. There are two options:
+    plugin should scan the HTML output to detect and process external assets:
-    while `report` will issue warning messages during the build, `bundle` will
-    automatically download all external files and adjust all references:
 
     ``` 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`,
+    it's still a good idea to enable the plugin, as the plugin will make sure
-    as the plugin will make sure that there are no hidden external links in any
+    that there are no hidden external links in any Markdown files that were 
-    Markdown files that were unintentionally added.
+    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/