Config to enable/disable theming

[lorenzolewis]

What version of starlight are you using?

0.5.6

What is your idea?

A way to set the Starlight site to only be dark or light (or auto) via the config

Why is this feature necessary?

Sometimes branding only has light or dark mode colors (or a developer only wants a specific theme). This would expose an option in the Starlight config for a user to only create a dark or light website. This could disable the theme dropdown in the navbar as well as reduce the resulting CSS.

A use case from Discord: https://discord.com/channels/830184174198718474/1070481941863878697/1125991126885744723

Do you have examples of this feature in other projects?

Docusaurus theme config for color: https://docusaurus.io/docs/api/themes/configuration#color-mode---dark-mode

I like how they also let the developer set a "preferred" mode (defaultMode) so that the dev could specify a specific theme but then the user could also override it if they'd like. I remember some conversations over there around all the different permutations and states this could result in so it would probably be good to have a solid think through what the API and UX would be around this.

Participation

• I am willing to submit a pull request for this issue.

[delucis]

I’m pretty strongly in favour of letting site users pick dark/light mode — forcing someone to use colours different from their preference is an accessibility concern.

If people want it enough, I think we could make the default theme configurable though — i.e. disrespectUserThemePreference: 'light' 😛 — so that pages load in light/dark instead of auto while still letting users switch to their preference. There are situations where this could make sense, like https://terrateam.io/ where the transition from their dark marketing homepage to the docs in light mode (when that’s the device preference) can be quite jarring.

[lorenzolewis]

Love that suggested key name ;)

Get what you're saying around accessibility (and even my personal experience with being blinded by the light[-theme]).

Maybe a config option could be: preferredTheme: 'userPreference' | 'dark' | 'light';

[delucis]

Yeah! I might suggest defaultTheme or initialTheme perhaps? And the values would probably be clearest if they match how we label them in the UI 'auto' | 'dark' | 'light'. We could make it clear in docs that setting this config option overrides user preference.

[schalkneethling]

Being able to set the initial theme would be enough for me. Thanks, @delucis

[dhruvkb]

Personally, I would prefer sites have 'auto' theme be the default, as it allows me to set my light/dark preference once (at the device level) and have my web browsing experience consistently match my preference.

[delucis]

Personally, I would prefer sites have 'auto' theme be the default

Yeah, absolutely, we won’t change that default.

[magicDGS]

I also would like to be able to disable the light/dark mode switch to control better the branding of my documentation. In my case, I would like to have a dark-only mode for the website hosting the documentation and even if I style in the same way the light/dark mode, the switch will appear making the site look like if the light mode is not working.

I agree that the default should still be keeping the switch and default to auto, but having a one-style is an use-case that I can see as valuable in case that somebody needs it.

[iqbalamo93]

Hey Ya!
I was wondering if this feature will be released. I've built my site and I need 'dark mode' to be the only option.

[bramsmulders]

Our Astro site doesn't have a dark mode, and we'd like to document it in starlight. But the theme toggle prevents us from deploying the documentation to a public site. Not all design systems/brandings have taken dark/light mode into account(yet) and forcing this in starlight is not productive it think. I agree it should be enabled by default, but a configuration option would be very nice.

[delucis]

This can be worked around using component overrides currently. There are two theme-related components:

• ThemeProvider — adds a <script> and <template> to set-up theme support, could be overridden to just contain

  <script is:inline>
  document.documentElement.dataset.theme = 'light'
  </script>

  (is:inline prevents Astro bundling the script, which would make it run too late)

• ThemeSelect — adds the actual theme picker UI. This could be overridden with an empty component to hide it.

Hope that helps!

[bramsmulders]

@delucis Awesome! This worked very well, thanks for your swift reply!