Skip to content

Commit b0d59f2

Browse files
squidfunksquidfunk
committed
Documentation
1 parent 5b9f6c9 commit b0d59f2

File tree

3 files changed

+134
-87
lines changed

3 files changed

+134
-87
lines changed

‎docs/schema/plugins/privacy.json

+29-31
Original file line numberDiff line numberDiff line change
@@ -24,72 +24,70 @@
2424
"concurrency": {
2525
"title": "Concurrency (number of CPUs)",
2626
"markdownDescription": "https://squidfunk.github.io/mkdocs-material/setup/ensuring-data-privacy/#+privacy.concurrency",
27-
"type": "number"
27+
"type": "number",
28+
"default": 1
2829
},
29-
"external_assets": {
30-
"title": "External assets",
31-
"markdownDescription": "https://squidfunk.github.io/mkdocs-material/setup/ensuring-data-privacy/#+privacy.external_assets",
32-
"oneOf": [
33-
{
34-
"title": "Bundle external assets",
35-
"enum": ["bundle"]
36-
},
37-
{
38-
"title": "Report external assets as warnings",
39-
"enum": ["report"]
40-
}
41-
],
42-
"default": "bundle"
30+
"assets": {
31+
"title": "Process external assets",
32+
"markdownDescription": "https://squidfunk.github.io/mkdocs-material/setup/ensuring-data-privacy/#+privacy.assets",
33+
"type": "boolean",
34+
"default": true
35+
},
36+
"assets_fetch": {
37+
"title": "Download external assets",
38+
"markdownDescription": "https://squidfunk.github.io/mkdocs-material/setup/ensuring-data-privacy/#+privacy.assets_fetch",
39+
"type": "boolean",
40+
"default": true
4341
},
44-
"external_assets_dir": {
45-
"title": "External assets download directory",
46-
"markdownDescription": "https://squidfunk.github.io/mkdocs-material/setup/ensuring-data-privacy/#+privacy.external_assets_dir",
42+
"assets_fetch_dir": {
43+
"title": "Download external assets to this directory",
44+
"markdownDescription": "https://squidfunk.github.io/mkdocs-material/setup/ensuring-data-privacy/#+privacy.assets_fetch_dir",
4745
"type": "string",
4846
"default": "assets/external"
4947
},
50-
"external_assets_include": {
48+
"assets_include": {
5149
"title": "External assets to include",
52-
"markdownDescription": "https://squidfunk.github.io/mkdocs-material/setup/ensuring-data-privacy/#+privacy.external_assets_include",
50+
"markdownDescription": "https://squidfunk.github.io/mkdocs-material/setup/ensuring-data-privacy/#+privacy.assets_include",
5351
"type": "array",
5452
"items": {
5553
"title": "External assets matching this pattern will be downloaded",
56-
"markdownDescription": "https://squidfunk.github.io/mkdocs-material/setup/ensuring-data-privacy/#+privacy.external_assets_include",
54+
"markdownDescription": "https://squidfunk.github.io/mkdocs-material/setup/ensuring-data-privacy/#+privacy.assets_include",
5755
"pattern": ".*"
5856
},
5957
"uniqueItems": true,
6058
"minItems": 1
6159
},
62-
"external_assets_exclude": {
60+
"assets_exclude": {
6361
"title": "External assets to exclude",
64-
"markdownDescription": "https://squidfunk.github.io/mkdocs-material/setup/ensuring-data-privacy/#+privacy.external_assets_exclude",
62+
"markdownDescription": "https://squidfunk.github.io/mkdocs-material/setup/ensuring-data-privacy/#+privacy.assets_exclude",
6563
"type": "array",
6664
"items": {
6765
"title": "External assets matching this pattern will not be downloaded",
68-
"markdownDescription": "https://squidfunk.github.io/mkdocs-material/setup/ensuring-data-privacy/#+privacy.external_assets_exclude",
66+
"markdownDescription": "https://squidfunk.github.io/mkdocs-material/setup/ensuring-data-privacy/#+privacy.assets_exclude",
6967
"pattern": ".*"
7068
},
7169
"uniqueItems": true,
7270
"minItems": 1
7371
},
74-
"external_links": {
75-
"title": "External links",
76-
"markdownDescription": "https://squidfunk.github.io/mkdocs-material/setup/ensuring-data-privacy/#+privacy.external_links",
72+
"links": {
73+
"title": "Process external links",
74+
"markdownDescription": "https://squidfunk.github.io/mkdocs-material/setup/ensuring-data-privacy/#+privacy.links",
7775
"type": "boolean",
7876
"default": true
7977
},
80-
"external_links_attr_map": {
78+
"links_attr_map": {
8179
"title": "Custom attributes to add to external links",
82-
"markdownDescription": "https://squidfunk.github.io/mkdocs-material/setup/ensuring-data-privacy/#+privacy.external_links_attr_map",
80+
"markdownDescription": "https://squidfunk.github.io/mkdocs-material/setup/ensuring-data-privacy/#+privacy.links_attr_map",
8381
"type": "object",
8482
"patternProperties": {
8583
"^[\\w_]+$": {
8684
"type": "string"
8785
}
8886
}
8987
},
90-
"external_links_noopener": {
88+
"links_noopener": {
9189
"title": "Behavior for external links that open in new windows",
92-
"markdownDescription": "https://squidfunk.github.io/mkdocs-material/setup/ensuring-data-privacy/#+privacy.external_links_noopener",
90+
"markdownDescription": "https://squidfunk.github.io/mkdocs-material/setup/ensuring-data-privacy/#+privacy.links_noopener",
9391
"type": "boolean",
9492
"default": true
9593
}

‎docs/schema/plugins/social.json

+73-34
Original file line numberDiff line numberDiff line change
@@ -15,51 +15,90 @@
1515
"markdownDescription": "https://squidfunk.github.io/mkdocs-material/setup/setting-up-social-cards/#built-in-social-plugin",
1616
"type": "object",
1717
"properties": {
18-
"cards": {
19-
"title": "Social card generation",
20-
"markdownDescription": "https://squidfunk.github.io/mkdocs-material/setup/setting-up-social-cards/#+social.cards",
18+
"enabled": {
19+
"title": "Enable plugin",
20+
"markdownDescription": "https://squidfunk.github.io/mkdocs-material/setup/setting-up-social-cards/#+social.enabled",
2121
"type": "boolean",
2222
"default": true
2323
},
24-
"cards_color": {
25-
"title": "Social card color palette",
26-
"markdownDescription": "https://squidfunk.github.io/mkdocs-material/setup/setting-up-social-cards/#+social.cards_color",
27-
"type": "object",
28-
"properties": {
29-
"fill": {
30-
"title": "Background fill color",
31-
"markdownDescription": "https://squidfunk.github.io/mkdocs-material/setup/setting-up-social-cards/#+social.cards_color",
32-
"type": "string"
33-
},
34-
"text": {
35-
"title": "Foreground text color",
36-
"markdownDescription": "https://squidfunk.github.io/mkdocs-material/setup/setting-up-social-cards/#+social.cards_color",
37-
"type": "string"
38-
}
39-
},
40-
"additionalProperties": false,
41-
"required": [
42-
"fill",
43-
"text"
44-
]
24+
"concurrency": {
25+
"title": "Concurrency (number of CPUs)",
26+
"markdownDescription": "https://squidfunk.github.io/mkdocs-material/setup/setting-up-social-cards/#+social.concurrency",
27+
"type": "number",
28+
"default": 1
4529
},
46-
"cards_font": {
47-
"$ref": "../assets/fonts.json"
30+
"cards": {
31+
"title": "Social cards",
32+
"markdownDescription": "https://squidfunk.github.io/mkdocs-material/setup/setting-up-social-cards/#+social.cards",
33+
"type": "boolean",
34+
"default": true
4835
},
4936
"cards_dir": {
50-
"title": "Social card directory",
37+
"title": "Social cards directory",
5138
"markdownDescription": "https://squidfunk.github.io/mkdocs-material/setup/setting-up-social-cards/#+social.cards_dir",
5239
"type": "string",
5340
"default": "assets/images/social"
41+
},
42+
"cards_layout_dir": {
43+
"title": "Social cards layout directory",
44+
"markdownDescription": "https://squidfunk.github.io/mkdocs-material/setup/setting-up-social-cards/#+social.cards_layout_dir",
45+
"type": "string",
46+
"default": "layouts"
47+
},
48+
"cards_layout": {
49+
"title": "Social cards layout",
50+
"markdownDescription": "https://squidfunk.github.io/mkdocs-material/setup/setting-up-social-cards/#+social.cards_layout",
51+
"default": "default",
52+
"enum": [
53+
"default",
54+
"default/accent",
55+
"default/invert",
56+
"default/variant"
57+
]
58+
},
59+
"cards_layout_options": {
60+
"title": "Social cards layout options",
61+
"markdownDescription": "https://squidfunk.github.io/mkdocs-material/setup/setting-up-social-cards/#+social.cards_layout_options",
62+
"type": "object"
63+
},
64+
"debug": {
65+
"title": "Debug mode",
66+
"markdownDescription": "https://squidfunk.github.io/mkdocs-material/setup/setting-up-social-cards/#+social.debug",
67+
"type": "boolean",
68+
"default": true
69+
},
70+
"debug_grid": {
71+
"title": "Debug grid",
72+
"markdownDescription": "https://squidfunk.github.io/mkdocs-material/setup/setting-up-social-cards/#+social.debug_grid",
73+
"type": "boolean",
74+
"default": true
75+
},
76+
"debug_grid_step": {
77+
"title": "Debug grid step size",
78+
"markdownDescription": "https://squidfunk.github.io/mkdocs-material/setup/setting-up-social-cards/#+social.debug_grid_step",
79+
"type": "number",
80+
"default": 32
81+
},
82+
"debug_color": {
83+
"title": "Debug color",
84+
"markdownDescription": "https://squidfunk.github.io/mkdocs-material/setup/setting-up-social-cards/#+social.debug_color",
85+
"type": "string",
86+
"default": "yellow"
87+
},
88+
"cache": {
89+
"title": "Enable caching",
90+
"markdownDescription": "https://squidfunk.github.io/mkdocs-material/setup/setting-up-social-cards/#+social.cache",
91+
"type": "boolean",
92+
"default": true
93+
},
94+
"cache_dir": {
95+
"title": "Cache directory",
96+
"markdownDescription": "https://squidfunk.github.io/mkdocs-material/setup/setting-up-social-cards/#+social.cache_dir",
97+
"type": "string",
98+
"default": ".cache/plugins/social"
5499
}
55100
},
56-
"additionalProperties": false,
57-
"defaultSnippets": [
58-
{
59-
"label": "cards_font",
60-
"body": "cards_font: ${1:Roboto}"
61-
}
62-
]
101+
"additionalProperties": false
63102
}
64103
},
65104
"additionalProperties": false

‎docs/setup/ensuring-data-privacy.md

+32-22
Original file line numberDiff line numberDiff line change
@@ -199,28 +199,38 @@ The following configuration options are available:
199199

200200
The following configuration options are available for external assets:
201201

202-
[`external_assets`](#+privacy.external_assets){ #+privacy.external_assets }
202+
[`assets`](#+privacy.assets){ #+privacy.assets }
203203

204-
: :octicons-milestone-24: Default: `bundle` – This option specifies what the
205-
plugin should do when encountering external assets. There are two options:
206-
while `report` will issue warning messages during the build, `bundle` will
207-
automatically download all external files and adjust all references:
204+
: :octicons-milestone-24: Default: `true` – This option specifies whether the
205+
plugin should scan the HTML output to detect and process external assets:
208206

209207
``` yaml
210208
plugins:
211209
- privacy:
212-
external_assets: bundle
210+
assets: true
213211
```
214212

215213
If you've removed all external assets from your project via [customization],
216-
it's still a good idea to enable the plugin and set the mode to `report`,
217-
as the plugin will make sure that there are no hidden external links in any
218-
Markdown files that were unintentionally added.
214+
it's still a good idea to enable the plugin, as the plugin will make sure
215+
that there are no hidden external links in any Markdown files that were
216+
unintentionally added.
219217

220-
Using `report` in [strict mode] will make the build fail when external
218+
Using `assets` in [strict mode] will make the build fail when external
221219
assets are detected.
222220

223-
[`external_assets_dir`](#+privacy.external_assets_dir){ #+privacy.external_assets_dir }
221+
[`assets_fetch`](#+privacy.assets_fetch){ #+privacy.assets_fetch }
222+
223+
: :octicons-milestone-24: Default: `true` – This option specifies whether the
224+
plugin should download external assets it encountered and bundle them with
225+
your documentation:
226+
227+
``` yaml
228+
plugins:
229+
- privacy:
230+
assets_fetch: true
231+
```
232+
233+
[`assets_fetch_dir`](#+privacy.assets_fetch_dir){ #+privacy.assets_fetch_dir }
224234

225235
: :octicons-milestone-24: Default: `assets/external` – This option
226236
specifies where the downloaded [external assets] will be stored. It's
@@ -229,12 +239,12 @@ The following configuration options are available for external assets:
229239
``` yaml
230240
plugins:
231241
- privacy:
232-
external_assets_dir: assets/external
242+
assets_fetch_dir: assets/external
233243
```
234244

235245
The path must be defined relative to [`docs_dir`][docs_dir].
236246

237-
[`external_assets_include`](#+privacy.external_assets_include){ #+privacy.external_assets_include } :material-alert-decagram:{ .mdx-pulse title="Added on February 6, 2023" }
247+
[`assets_include`](#+privacy.assets_include){ #+privacy.external_assets_include }
238248

239249
: :octicons-milestone-24: Default: _none_ – This option allows to only include
240250
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:
243253
``` yaml
244254
plugins:
245255
- privacy:
246-
external_assets_include:
256+
assets_include:
247257
- unsplash.com/*
248258
```
249259

@@ -265,7 +275,7 @@ The following configuration options are available for external assets:
265275
differently from others or exclude some images from downloading, you can
266276
use multiple instances of the [built-in privacy plugin].
267277

268-
[`external_assets_exclude`](#+privacy.external_assets_exclude){ #+privacy.external_assets_exclude }
278+
[`assets_exclude`](#+privacy.assets_exclude){ #+privacy.assets_exclude }
269279

270280
: :octicons-milestone-24: Default: _none_ – This option allows to exclude
271281
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:
274284
``` yaml
275285
plugins:
276286
- privacy:
277-
external_assets_exclude: # (1)!
287+
assets_exclude: # (1)!
278288
- cdn.jsdelivr.net/npm/mathjax@3/*
279289
- giscus.app/*
280290
```
@@ -333,7 +343,7 @@ The following configuration options are available for external assets:
333343

334344
The following configuration options are available for external links:
335345

336-
[`external_links`](#+privacy.external_links){ #+privacy.external_links }
346+
[`links`](#+privacy.links){ #+privacy.links }
337347

338348
: :octicons-milestone-24: Default: `true` – This option specifies whether the
339349
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:
342352
``` yaml
343353
plugins:
344354
- privacy:
345-
external_links: !ENV [CI, false]
355+
links: !ENV [CI, false]
346356
```
347357

348-
[`external_links_attr_map`](#+privacy.external_links_attr_map){ #+privacy.external_links_attr_map }
358+
[`links_attr_map`](#+privacy.links_attr_map){ #+privacy.links_attr_map }
349359

350360
: :octicons-milestone-24: Default: _None_ – This option specifies custom
351361
attributes that should be added to external links, like for example
@@ -354,11 +364,11 @@ The following configuration options are available for external links:
354364
``` yaml
355365
plugins:
356366
- privacy:
357-
external_links_attr_map:
367+
links_attr_map:
358368
target: _blank
359369
```
360370

361-
[`external_links_noopener`](#+privacy.external_links_noopener){ #+privacy.external_links_noopener }
371+
[`links_noopener`](#+privacy.links_noopener){ #+privacy.links_noopener }
362372

363373
: :octicons-milestone-24: Default: `true` – This option specifies whether the
364374
plugin should automatically add [`rel="noopener"`][noopener] to all links
@@ -367,7 +377,7 @@ The following configuration options are available for external links:
367377
``` yaml
368378
plugins:
369379
- privacy:
370-
external_links_noopener: true
380+
links_noopener: true
371381
```
372382

373383
[noopener]: https://mathiasbynens.github.io/rel-noopener/

0 commit comments

Comments
 (0)