cards_layout option not recognized, but should be according to documentation?

[Andre601]

This is similar to #7434 but in my case is the cards_layout option not recognized.

I receive this warning from MkDocs:

WARNING -  Config value 'plugins': Plugin 'material/social' option 'cards_layout': Unrecognised configuration name: cards_layout

Based on what I could read in the above linked discussion should the default layout variants be available within the free version.
If that is the case, then why is the cards_layout option not recognized?

And if these options are insiders-only, then why not mark them as such? It makes it look like as if they are part of the free package when they aren't (if the previous statement would be true).

Also, to make things clear:

• Yes, I installed and updated mkdocs-material[imaging] (pip install -U mkdocs-material[imaging])
• Yes, I installed the necessary Dependencies (In my case MSYS2). Also, the $env:Path -split ';' command at the bottom of the Troubleshooting Section for windows seems to be wrong, as the command isn't recognized in neither MSYS2 nor Powershell.
• Yes, I deleted the cache folder with the images to see if that could fix the issues. It didn't.
• My configuration is the same as suggested by the docs:

  plugins:
    - social:
        cards_layout: 'default/variant'

[kamilkrzyskow]

Hello @Andre601,
the cards_layout setting is marked with a ❤️, so it's insiders only. There is no "layout" capabilities in the free version.

The other discussion was about cards_layout_options, which is available in the free version to allow for seamless transition from the free version to the Insiders version, and it doesn't have the ❤️ icon. However, not every option mapping is used in the free version.

You can see the available plugin parameters here:

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

Lines 28 to 48 in 45f60a6

	# Social plugin configuration
	class SocialConfig(Config):
	enabled = Type(bool, default = True)
	cache_dir = Type(str, default = ".cache/plugin/social")
	# Settings for social cards
	cards = Type(bool, default = True)
	cards_dir = Type(str, default = "assets/images/social")
	cards_layout_options = Type(dict, default = {})
	# Deprecated settings
	cards_color = Deprecated(
	option_type = Type(dict, default = {}),
	message =
	"Deprecated, use 'cards_layout_options.background_color' "
	"and 'cards_layout_options.color' with 'default' layout"
	)
	cards_font = Deprecated(
	option_type = Type(str),
	message = "Deprecated, use 'cards_layout_options.font_family'"
	)

Yes, I installed the necessary Dependencies (In my case MSYS2). Also, the $env:Path -split ';' command at the bottom of the Troubleshooting Section for windows seems to be wrong, as the command isn't recognized in neither MSYS2 nor Powershell.

Yes, thanks for reporting, I'm aware of this based on another discussion. This part of the docs started of with global Windows and Powershell in mind, but later got changed to MSYS2 and this was missed during the change. Haven't gotten around to changing it, as I still haven't found the ultimate guide for Python installation and this sort of blocks my reevaluation of that part of the docs

• There are easy ways to improve the user experience when you have an existing website and you're installing Material on a new PC #7757 (comment)

[Andre601]

Well, it should be made clear then that the layouts are also insiders only (except default which is used by default obviously), because nothing in the layout section mentions this to really be insiders only, which is somewhat confusing.

[squidfunk]

And if these options are insiders-only, then why not mark them as such?

As @kamilkrzyskow pointed out, cards_layout is marked as Insiders-only. I've now also added it to the layout section in 0b44f9c, which was just forgotten. Also, using a friendlier tone in your writing wouldn't hurt ☺️