From 962f64d995761a83d262713d96b529782379d984 Mon Sep 17 00:00:00 2001 From: squidfunk Date: Sat, 20 May 2023 17:23:53 +0200 Subject: [PATCH] Updated Insiders changelog --- CHANGELOG | 8 ++++ docs/insiders/changelog.md | 8 ++++ docs/schema/plugins/social.json | 24 ++++++++++ docs/setup/setting-up-social-cards.md | 67 +++++++++++++++++++++++++-- 4 files changed, 103 insertions(+), 4 deletions(-) diff --git a/CHANGELOG b/CHANGELOG index e832d92fe..c29b12584 100644 --- a/CHANGELOG +++ b/CHANGELOG @@ -1,3 +1,11 @@ +mkdocs-material-9.1.14+insiders-4.35.0 (2023-05-20) + + * Improve editing experience and stability of social plugin + * Added support for custom layout syntax validation in social plugin + * Added support for layer origin for easier placement in social plugin + * Added support for in- and exclusion patterns in social plugin + * Catch and print syntax errors in custom layouts + mkdocs-material-9.1.14 (2023-05-20) * Updated Armenian and Greek translations diff --git a/docs/insiders/changelog.md b/docs/insiders/changelog.md index 6203411ec..802e46df9 100644 --- a/docs/insiders/changelog.md +++ b/docs/insiders/changelog.md @@ -2,6 +2,14 @@ ## Material for MkDocs Insiders +### 4.35.0 May 20, 2023 { id="4.35.0" } + +- Improve editing experience and stability of social plugin +- Added support for custom layout syntax validation in social plugin +- Added support for layer origin for easier placement in social plugin +- Added support for in- and exclusion patterns in social plugin +- Catch and print syntax errors in custom layouts + ### 4.34.1 May 16, 2023 { id="4.34.1" } - Disable social plugin debug mode by default on mkdocs build diff --git a/docs/schema/plugins/social.json b/docs/schema/plugins/social.json index 97c2b2efe..b2ba2e29a 100644 --- a/docs/schema/plugins/social.json +++ b/docs/schema/plugins/social.json @@ -61,6 +61,30 @@ "markdownDescription": "https://squidfunk.github.io/mkdocs-material/setup/setting-up-social-cards/#+social.cards_layout_options", "type": "object" }, + "cards_include": { + "title": "Pages or folders to include", + "markdownDescription": "https://squidfunk.github.io/mkdocs-material/setup/setting-up-social-cards/#+social.cards_include", + "type": "array", + "items": { + "title": "Pages or folders matching this pattern will be included", + "markdownDescription": "https://squidfunk.github.io/mkdocs-material/setup/setting-up-social-cards/#+social.cards_include", + "pattern": ".*" + }, + "uniqueItems": true, + "minItems": 1 + }, + "cards_exclude": { + "title": "Pages or folders to exclude", + "markdownDescription": "https://squidfunk.github.io/mkdocs-material/setup/setting-up-social-cards/#+social.cards_exclude", + "type": "array", + "items": { + "title": "Pages or folders matching this pattern will be excluded", + "markdownDescription": "https://squidfunk.github.io/mkdocs-material/setup/setting-up-social-cards/#+social.cards_exclude", + "pattern": ".*" + }, + "uniqueItems": true, + "minItems": 1 + }, "debug": { "title": "Debug mode", "markdownDescription": "https://squidfunk.github.io/mkdocs-material/setup/setting-up-social-cards/#+social.debug", diff --git a/docs/setup/setting-up-social-cards.md b/docs/setup/setting-up-social-cards.md index 108f6f296..8921853bd 100644 --- a/docs/setup/setting-up-social-cards.md +++ b/docs/setup/setting-up-social-cards.md @@ -228,10 +228,10 @@ The following configuration options are available for card generation: [`cards_layout_options`](#+social.cards_layout_options){ #+social.cards_layout_options } -: [:octicons-tag-24: insiders-4.33.0][Insiders] · :octicons-milestone-24: +: [:octicons-tag-24: 9.1.10][Layout options support] · :octicons-milestone-24: Default: _none_ – This option allows to set [parameters] as provided by the layout specification. For [custom layouts], this key can be used to - provide layout-specific options, making layouts entirels configurable. + provide layout-specific options, making layouts entirely configurable. --- @@ -293,6 +293,32 @@ The following configuration options are available for card generation: font_family: Ubuntu ``` +[`cards_include`](#+privacy.cards_include){ #+privacy.cards_include } + +: [:octicons-tag-24: insiders-4.35.0][Insiders] · :octicons-milestone-24: + Default: _none_ – This option allows to only generate social cards for + certain subsections of your documentation, e.g. to generate different + cards for different subfolders with multiple instances of the plugin: + + ``` yaml + plugins: + - social: + cards_include: + - blog/* + ``` + +[`cards_exclude`](#+privacy.cards_exclude){ #+privacy.cards_exclude } + +: :octicons-milestone-24: Default: _none_ – This option allows to exclude + certain subsections of your documentation from generating social cards: + + ``` yaml + plugins: + - social: + cards_exclude: + - changelog/*.md + ``` + [color palette]: ./changing-the-colors.md#color-palette [primary color]: ./changing-the-colors.md#primary-color [accent color]: ./changing-the-colors.md#accent-color @@ -308,6 +334,7 @@ The following configuration options are available for card generation: [parameters]: #parameters [default layouts]: #+social.cards_layout [CSS color keyword]: https://developer.mozilla.org/en-US/docs/Web/CSS/color_value#color_keywords + [Layout options support]: https://github.com/squidfunk/mkdocs-material/releases/tag/9.1.10 #### Debugging @@ -594,8 +621,8 @@ layers: ``` If the `size` is omitted, it defaults to the size of the layout. If the `offset` -is omitted, it defaults to the top left corner, which is the origin for all -layers. Saving the layout and reloading renders: +is omitted, it defaults to the top left corner, which is the defaut `origin`. +Saving the layout and reloading renders: ![Layer size] @@ -605,6 +632,38 @@ useful for alignment and composition. [Layer size]: ../assets/screenshots/social-cards-layer-size.png +#### Origin + +[:octicons-tag-24: insiders-4.35.0][Insiders] · +:octicons-beaker-24: Experimental + +The `origin` for the `x` and `y` values can be changed, so that the layer is +aligned to one of the edges or corners of the layout, e.g., to the bottom right +corner of the layout: + +``` yaml hl_lines="5" +size: { width: 1200, height: 630 } +layers: + - size: { width: 1200, height: 630 } + offset: { x: 0, y: 0 } + origin: end bottom +``` + +The following table shows the supported values: + +
+ +| Origin | | | +| -------------- | --------------- | ------------ | +| :material-arrow-top-left: `start top` | :material-arrow-up: `center top` | :material-arrow-top-right: `end top` | +| :material-arrow-left: `start center` | :material-circle-small: `center` | :material-arrow-right: `end center` | +| :material-arrow-bottom-left: `start bottom` | :material-arrow-down: `center bottom` | :material-arrow-bottom-right: `end bottom` | + +
+ Supported values for origin +
+
+ ### Backgrounds Each layer can be assigned a background color and image. If both are given, the