cards_layout_options labeled as part of community edition, but doesn't appear to be the case

[dfellis]

Description

The cards_layout_options configuration does not have the insiders ❤️ next to it, but doesn't appear to do anything on the community edition when attempting to configure with it.

The cards_layout configuration does have the ❤️ but it also marks it as having a default value of "default" which, when coupled with the options not being marked, implies that the community edition can configure the default card layout.

Related links

• cards_layout_options

Proposed change

While it would be nice if the card_layout_options would work for the default card in the community edition, it's probably best to put the ❤️ next to it to make it clearer to readers.

Before submitting

• I have read and followed the documentation issue guidelines.
• I have attached the links to the affected sections of the documentation

[kamilkrzyskow]

The cards_layout_options should be partially supported:

mkdocs-material/material/plugins/social/plugin.py

Line 451 in d5363ad

name = self.config.cards_layout_options.get("font_family")

mkdocs-material/material/plugins/social/plugin.py

Lines 151 to 156 in d5363ad

	# Retrieve color overrides
	options = self.config.cards_layout_options
	self.color = {
	"fill": options.get("background_color", self.color["fill"]),
	"text": options.get("color", self.color["text"])
	}

Some suboptions are missing, true, but they're marked with the ❤️ under their respective header.
https://squidfunk.github.io/mkdocs-material/plugins/social/#option.title

---

Also note that old social plugin options are ported over to the new format and do override them:

mkdocs-material/material/plugins/social/plugin.py

Lines 104 to 120 in d5363ad

	# Move color options
	if self.config.cards_color:
	# Move background color to new option
	value = self.config.cards_color.get("fill")
	if value:
	self.config.cards_layout_options["background_color"] = value
	# Move color to new option
	value = self.config.cards_color.get("text")
	if value:
	self.config.cards_layout_options["color"] = value
	# Move font family to new option
	if self.config.cards_font:
	value = self.config.cards_font
	self.config.cards_layout_options["font_family"] = value

---

Perhaps you're using an older version or there is some other issue. Please try to make a minimal reproduction.

[dfellis]

Definitely using the latest version, I just installed it yesterday.

I will work on a reproduction tomorrow or Monday as it's pretty late in the day, now.

[kamilkrzyskow]

Perhaps the issue you're experiencing is related to cache, and removing the .cache/plugin/social directory would help.

[dfellis]

This ended up being the correct answer after I started working on reproducing the issue. I assumed blowing away the site/ directory would be enough to get it to rebuild from scratch. I didn't know there was a .cache/ directory. Is there a reason the .cache is not placed inside of site?

[kamilkrzyskow]

Files in the site directory are removed and built anew after each execution of mkdocs build. This directory represents the data available for the user after deployment onto the webserver.

The usage of the .cache directory is just a convention in the MkDocs ecosystem (probably coined by mkdocs-material plugins), and it stores files that can be reused between mkdocs build executions to save on processing time.

Generally the plugin logic should invalidate the cache after config / other related changes happen.
I think I once planned to make a fix for the social plugin, as the community version doesn't fully incorporate every related change, like the config for example. However, I never came around to it, as I seldom change the social plugin's config.

This could be seen as a bug, because the user needs to fix the software via manual .cache removal, but for the most part it's just a small inconvenience.

mkdocs-material/material/plugins/social/plugin.py

Lines 210 to 215 in d5363ad

	# Generate social card if not in cache
	hash = md5("".join([
	site_name,
	str(title),
	description
	]).encode("utf-8"))

[squidfunk]

Correct, we can't rule out that the old social plugin might have some issues with cache invalidation. That's definitely all gone with the new implementation that will soon be released to the community edition.

[squidfunk]

Thanks for reporting. The cards_layout_options option is definitely supported in the community edition, but cards_layout is exclusive to Insiders. The reason is that in Insiders you can choose the layout, whereas in the community edition there's only the default layout. When shipping the ne social plugin to Insiders, we tried to make it compatible by matching the configuration settings.

Regardless, what you're describing is not a documentation issue, but should rather be a bug report including a minimal reproduction. I'm converting this to a discussion. Please provide a minimal reproduction and attach it here, so the community can help you ☺️

[squidfunk]

Additionally, see the Layouts section to learn which options are supported in what edition.