Add support for custom light/dark schemes

[sisp]

I've added support for custom light/dark schemes when using Material for MkDocs.

Material for MkDocs' default schemes are default (light) and slate (dark). But it is possible to define custom schemes with different names/identifiers. For this case, I've added options to configure these identifiers:

scheme: custom-light
scheme_dark: custom-dark

Their defaults are default and slate respectively. As before, the fallback for when Material for MkDocs is not used (or especially data-md-color-scheme is not set) is the (configured) light Vega theme.

WDYT, @timvink?

[timvink]

Hi @sisp , thanks for the contribution! I was on holiday, hence the late reply.

I don't understand this PR, and I think the current options document is confusing for users.

We are now mixing the concept of vegalite themes and mkdocs material themes. I would expect the theme to be a vegalite theme (https://github.com/vega/vega-themes).

The way this plugin currently works, is that it automatically detects if you're using mkdocs-material with the dark mode, and then select the vegalite theme vega_theme_dark. The problem you've identified is that you can define custom schemes in mkdocs-material.

An alternative solution would be for this plugin to have the theme option be set to either vega_theme, vega_theme_dark or autodetect (default). The autodetect option could then infer, when using mkdocs-material, which theme to use.

Then we still need an option to specify which mkdocs-material schemes are dark, and which are light. Perhaps something like:

charts:
    scheme: autodetect
    mkdocs_material_light_themes:
        - default
    mkdocs_material_dark_themes:
        - slate

That way, it's clearer to users what's happening & we're not mixing vegalite themes with mkdocs-material themes. Thoughts?

[sisp]

I was implicitly mapping scheme -> vega_theme and scheme_dark -> vega_theme_dark where scheme/scheme_dark are Material for MkDocs theme names, whereas you're suggesting an explicit Vega theme selection (or auto-detection) via theme (or scheme?) and a decoupled Material for MkDocs themes config via mkdocs_material_{light,dark}_themes. I recognize the advantage of your design.

Two questions though:

1. theme: autodetect|vega_theme|vega_theme_dark feels not so intuitive to me. How about theme: autodetect|light|dark where light means the theme set by vega_theme and dark means the theme set by vega_theme_dark?

2. The mkdocs_material_{light,dark}_themes settings feel verbose to me. Also, your design would be extensible to more MkDocs themes other than Material for MkDocs. I realize that the current config is flat, but how about structuring it more? E.g.:

   charts:
     theme: autodetect
     integrations:
       mkdocs_material:
         themes_light:
           - default
           - light
         themes_dark:
           - slate
           - dark

   Or do you think that's too much structure for only a single scenario at the moment?

[timvink]

I like the decoupling of the vega theme and the mkdocs material, and the nested config structure makes it clear, great idea! You are right about 'autodetect' option not feeling intuitive.

This plugin is using vega-embed, which has a theme parameter that we use, that supports themes from vega-themes. Currently we're passing either default or dark:

mkdocs-charts-plugin/mkdocs_charts_plugin/plugin.py

Lines 29 to 30 in 87789f5

	("vega_theme", config_options.Type(str, default="default")),
	("vega_theme_dark", config_options.Type(str, default="dark")),

mkdocs-charts-plugin/mkdocs_charts_plugin/plugin.py

Lines 102 to 107 in 87789f5

	# Config as javascript dictionary
	add_variables = f"""
	<script>
	var mkdocs_chart_plugin = {plugin_config}
	</script>
	"""

And then only overwriting it if mkdocs-material theme is present and has a different color scheme:

mkdocs-charts-plugin/mkdocs_charts_plugin/js/mkdocs-charts-plugin.js

Lines 170 to 180 in 87789f5

	// mkdocs-material has a dark mode
	// detect which one is being used
	var theme = (document.querySelector('body').getAttribute('data-md-color-scheme') == 'slate') ? mkdocs_chart_plugin['vega_theme_dark'] : mkdocs_chart_plugin['vega_theme'];
	// Render the chart
	vegaEmbed(block, schema, {
	actions: false,
	"theme": theme,
	"renderer": mkdocs_chart_plugin['vega_renderer']
	});
	}

So we can combine the ideas and remain backwards compatible:

charts:
  vega_theme: default # <-- existing default
  vega_theme_dark: dark # <-- existing default. We can explain we will attempt to use this theme if dark mode is preferred/detected.
  integrations:
    mkdocs_material:
      themes_light:
        - default
        - light
      themes_dark:
        - slate
        - dark

Then, we can also add a javascript detection if the users prefers dark mode on the browser or OS (https://stackoverflow.com/questions/56393880/how-do-i-detect-dark-mode-using-javascript)

[timvink]

Any chance we can finish this one? :)

[sisp]

Absolutely! Sorry, I had forgotten about it. I'll finish it tomorrow evening.

[sisp]

I've updated the PR to add explicit mkdocs-material integration and also user's preferred color scheme detection as discussed above. I split the two changes into separate commits to separate concerns.

The current implementation tries to derive the theme in the following order:

1. Try to detect mkdocs-material's active color scheme.
2. Try to detect the user's preferred color scheme on the browser or OS.
3. Fall back to the light theme.

When trying to detect mkdocs-material's active color scheme, the light names are actually ignored. Should we rethink the design? 🤔

[timvink]

This is epic! Really well done!

When trying to detect mkdocs-material's active color scheme, the light names are actually ignored. Should we rethink the design?

I noticed. Actually vega_theme was implicitly used as vega_theme_light. I renamed it, and deprecated vega_theme. Works perfectly for me now.

[timvink]

I did that here btw: #25

Will release soon

[sisp]

Fantastic! Thanks for the amazing feedback and guidance! 🙏

[timvink]

Sorry it took a while. Also updated the README ! Now released to pypi

[sisp]

No problem. Thanks!