Use image defined in front matter for social cards

[Guts]

Context

As developer of the RSS plugin, I use the image: key (illustration: is also supported) in the frontmatter to use it as media enclosure.

Note: in a future release, the RSS plugin will be able to use the image generated by social plugin.

If I enable the social plugin:

Description

The idea is to add an option to tell the social plugin use the image set in the specified key in front matter instead of generating one.

Add option to generate card image only if when there is no page.meta.image nor page.meta.illustration. It would give something like this:

[...]
- social:
      cards: !ENV [MKDOCS_ENABLE_PLUGIN_CARDS, true]
      cards_color:
        fill: "#3e93a7"
      cards_font: Ubuntu
      use_from_meta: image
[...]

When YAML frontmatter does not contains image key, a social card is generated. When YAML frontmatter contains a image URI, it's directly used for the social card without generating one:

[...]
image: https://europe-west/cdn-cgi/image/width=600,quality=75/uploads/article-illustration.png
[...]

Related links

• Social plugin
• enclosure tag in RSS plugin

Use Cases

This option lets the author of a content set his illustration image and suggest one autogenerated by default if he is not inpired.

Visuals

No response

Before submitting

• I have read and followed the change request guidelines.
• I have verified that my idea is a change request and not a bug report.
• I have ensured that, to the best of my knowledge, my idea will benefit the entire community.
• I have included relevant links to the documentation, related issues, and discussions to underline the need for my idea.

[squidfunk]

Thanks for suggesting! Great idea! We can actually implement this with a custom template, which will allow to use the image as a basis and optionally render text on top of the image, which you can decide on a page-by-page basis. For this to work, we need to implement two things that are already on the roadmap:

1. Downloading of images: this will allow to directly point to external URLs, which the social plugin will download and then use as a background image. We should somehow cache the resolved URL, so URLs are stable and they are not downloaded every time. This will allow to use image APIs like Unsplash, e.g.: https://source.unsplash.com/random/1200x630/?coffee

2. Add an "image only" option: I'm not quite sure what's the best way to implement this, but there are two degrees of freedom for feeding custom data into the social plugin. There's cards_layout_options in mkdocs.yml, which allows to specify build-time options, there's the possibility to specify data via front matter, which you can use to set template variables for custom layouts for specific pages, and which you could even combine with the meta plugin to set those values for whole subsections of your documentation. I'll cook something up the next time I work on this plugin ☺️

[jonaharagon]

2. Add an "image only" option: I'm not quite sure what's the best way to implement this, but there are two degrees of freedom for feeding custom data into the social plugin...

I would really love the ability to just define a card layout template in a page's front matter, personally.

I was working on a custom layout in privacyguides/privacyguides.org#2177, and I made the card for the homepage look completely different than the cards for the rest of the site with a bunch of if statements in the layouts/custom.yml file, but it would be much cleaner if I could just have layouts/homepage.yml and layouts/page.yml and choose between them on a page by page basis.

I think this solution would also address this "image-only card" problem, and it would be very powerful in combination with the meta plugin.

[squidfunk]

Noted! We will definitely add the ability to change the card layout template + layout options via front matter in an upcoming release! And yes, combining this with the meta plugin will be super powerful. Feel free to open a new issue for this FR, as the FR reported here can likely be solved with what you#re asking, but it is more general.

[squidfunk]

fa5bd3f45 adds the ability to override the following parameters via front matter, either for a single page, or for a subtree of your documentation by using the built-in meta plugin. The new social property in front matter supports:

• cards
• cards_layout
• cards_layout_options

Additionally, a new layout called default/only/image was added, which allows to set just a background image. Currently, it has to be a local image, but we're working on automatically fetching remote images as well. This will make up for interesting integrations with APIs like the one from Unsplash where you can fetch a random image using a few keywords.

Examples

Disable social card generation for a page

---
social:
  cards: false
---

# Headline
...

Change social card layout for a page

---
social:
  cards_layout: default/only/image
---

# Headline
...

Change social card layout options for a page

---
social:
  cards_layout_options:
    background_color: red  # Change background color to red
    background_image: null # Reset background image
---

# Headline
...

Page layout options are merged with global options, the former of which are taking precedence. In order to reset options to their defaults, you can use null, which will be coerced to None in your layout, as expected when converting YAML to Python. Documentation has yet to be added, but if you check out the tip of master, you can start using it now.

In order to implement the request in the OP, you would just set your image as the background image. The nice thing is that the social plugin will automatically scale it correctly, if it's not fitting the dimensions defined in your layout.

Feedback appreciated.

[squidfunk]

Documentation added in ab39491. I'll issue a release shortly.

[squidfunk]

Released as part of 9.1.18+insiders-4.37.0!

[Guts]

Good evening,

Sorry for the delay in replying, I haven't had much time for my side projects in recent weeks.

Thank you very much for the ideas derived from my request and the subsequent implementation! Still impressed with your responsiveness @squidfunk.

These changes clearly make the use of the social plugin even more flexible.

However, they don't quite meet my request, which was based on feedback from non-technical editors (or those not sufficiently skilled to master the arcana of the YAML frontmatter in mkdocs).

If I have the following configuration:

- social:
      cards: !ENV [MKDOCS_ENABLE_PLUGIN_CARDS, true]
      cards_layout_options:
        cards_layout: default/only/image
        cards_color:
          fill: "#3e93a7"
        font_family: Ubuntu

And a page with :

---
title: The final tutorial
description: "Page WITH image set in frontmatter"
image: https//example.com/image.png
---

## Here we go for the technical writing with Mkdocs

How do I get the image defined in the frontmatter to be used?

If I have another page with :

---
title: The final tutorial
description: "Page WITHOUT image set in frontmatter"
---

## Here we go for the technical writing with Mkdocs

How do I generate an image?

You mentioned a template, otherwise I was thinking of an mkdocs hook that would write social: cards: false if the image is empty or absent from the frontmatter.

Am I missing something? Any thoughts?

[squidfunk]

Your request was targeted towards a specific feature: setting a background image on a social card for a single page. What we did is we generalized your request and now allow to set everything in a social card template to a value provided via metadata. I understand that it's not 100% of what you requested, but it allows for much more powerful integrations now.

If you want you use a custom metadata property like image outside of options, you have two options.

• Use a hook to carry over page.meta.image to cards_layout_options.background_image
• Use a custom template to directly access page.meta.image

I recommend to study the default/only/image template, because essentially, you only need to change line 30 to:

{{ page.meta.image or layout.background_image }}

Please understand that "this is how we work". If we would implement each feature request as desired, Material for MkDocs would be a monster with 237 legs. Only by generalizing and modularizing we can keep the code base clean and the project in a great shape. We always try to put as little "burden of customization" as necessary on the author 😊

[squidfunk]

Oh, and if a little more verbosity is okay, then please just follow my previous comment:

---
social:
  cards_layout: default/only/image
  cards_layout_options:
    background_image: <url>
---

# Page title

[Guts]

Your request was targeted towards a specific feature: setting a background image on a social card for a single page.

Not exactly. It was about using an image, not specifically as background, just an image which is specified in frontmatter.

Please understand that "this is how we work". If we would implement each feature request as desired, Material for MkDocs would be a monster with 237 legs. Only by generalizing and modularizing we can keep the code base clean and the project in a great shape. We always try to put as little "burden of customization" as necessary on the author blush

I understand and no need to remind me that, don't worry. Note that I'm not complaining about the necessary choices to keep the project generic enough to allow customization and global usage.

I was just asking and confirming it was not completely filling my needs, to be sure that I was not missing something.

Thanks for template tip :).

[squidfunk]

Is there any downside of setting your image as a background image on the social card? The outcome is exactly the same if your image has the same dimension as the card (which it should). Because if you do it like that, you can use all additional functionality of the plugin, like automatically setting the necessary og:* and twitter:* tags, rendering fonts on top, etc. Please understand that we won't implement "replace social card with this image" at this moment, as we consider it an edge case. Setting it as a background image and using the default/only/image template is the canonical way to go 😊

If this turns out to be an important use case, we might reconsider, but the essence of what you requested is now definitely possible, even though you might need a 3-4 line hook or adjust the template to fit it to your taste.

[Guts]

Just to follow the thread and if someone else is intersted, I've achieved the MkDocs's hook that allow to customize the social plugin behavior: https://github.com/geotribu/website/blob/master/hooks/mkdocs/G003_social_cards_adapter.py

[squidfunk]

@Guts thanks for sharing! Note that this will only work with the Insiders version of the social plugin.

[Guts]

Note that this will only work with the Insiders version of the social plugin.

Hi @squidfunk, just to follow up here: now, it works too on community version. I've added a `` attribute to theme section that allows me to adjust the hook's behavior depending on which theme's flavoris installed.

Next step: using the group plugin.