@henryiii I'm now testing henryiii:feat/autodark locally, using Jekyll 3.8.7.

With nil for both color scheme settings in _config.yml, switching to dark mode doesn't load the CSS:

_site/assets/js/just-the-docs.js shows:

    if (window.matchMedia) {
        window.matchMedia('(prefers-color-scheme: dark)')
              .addEventListener('change', event => {
          if (event.matches) {
              jtd.setTheme('nil');
          } else {
              jtd.setTheme('nil');
          }
        });
    
        if(window.matchMedia('(prefers-color-scheme: dark)').matches) {
            jtd.setTheme('nil');
        }
    }

It appears that {% if site.dark_color_scheme %} suppresses the code when the setting for dark_color_scheme is omitted, but not when it is explicitly set to nil?

Setting dark_color_scheme: dark makes the CSS load when switching to dark mode. Reloading the page and navigating to other pages in Safari works fine, but browsing the same site in Firefox (85.0) briefly shows the page without CSS before loading the CSS for the dark mode. And in both browsers, switching from dark to light shows the unformatted page until I reload the page or navigate to other pages – presumably due to jtd.setTheme('nil'). Setting also color_scheme: light fixes that problem, but it doesn't suppress the flashing that I see when browsing with Firefox in dark mode.

Can you reproduce the above locally? I guess Liquid tests can be added to fix the issue with the nil settings, but I've no idea how to eliminate the flashing in Firefox.

I'm looking into it. Ah, "nil" is not a dedicated true/false value in YAML, so it't the string nil. That's easy to fix. Will look into the loading next.

Fixed the handling of nil. Firefox is odd - it seems to be trying to show a partially loaded page for some reason (the flashed page is not complete). Chrome and Safari are fine. We could move this up in to the onReady function, perhaps, but I don't think that would fix the flashing? I couldn't get the syntax quite right for accessing jtd, so didn't properly get to test moving it.

Looks like Firefox is rather known for the white flash when loading. https://www.reddit.com/r/firefox/comments/8yqhu8/how_to_change_white_flash_when_loading_webpage/ https://support.mozilla.org/en-US/questions/1269392

Thanks for fixing the handling of nil options.

That Firefox flashing is very annoying! I tried moving the new code inside the onReady function, but it didn't seem to make any difference.

With PR #464, Firefox does not flash at all when navigating between pages in dark mode. I guess that is because the CSS already includes the code for the dark mode, so Firefox doesn't need to reload it? But I have no idea how to combine that technique with the use of setTheme in the present PR.

For me, navigating the pages of https://scikit-hep.org on Firefox, the only flashing I get is for the initial page. After that, it is stable. I think firefox is doing some sort of fast-load trickery to make the page appear to load quicker, but it's interfering with this. There might be a workaround, but not sure what it would be.

The SCSS method didn't seem bad, ether.

Indeed: browsing https://scikit-hep.org with Firefox, I saw flashes the first time I visited a few pages, but none appeared after that. When I browse a local copy of https://github.com/scikit-hep/scikit-hep.github.io, however, I see a flash in Firefox whenever I navigate to a different page, or reload the current page. The flash is a bit quicker when a page is revisited, but it is still quite annoying.

Similarly, when I visited https://pmarsceill.github.io/just-the-docs/docs/customization/#color-schemes with Firefox, clicking on Preview dark color scheme then Return to the light side flashed both times, but subsequent clicks on the same buttons showed no flash at all (also after reloading the page or visiting other pages). Browsing a clean local fork of https://github.com/pmarsceill/just-the-docs with Firefox, I see flashes persistently when I do the following:

• http://localhost:4000//just-the-docs/
• http://localhost:4000//just-the-docs/docs/customization/#color-schemes
• Preview dark color scheme: flash
• Return to the light side: flash
• Preview dark color scheme: no visible flash
• Return to the light side: no visible flash

Repeating the above sequence produces the same flashes.

I suspect jtd.setTheme always produces flashes in Firefox, but after caching pages on the theme docs site, the flashes are just too quick to see when served locally. Perhaps the only significant differences between browsing locally and on GitHub Pages are server speed and network latency, which combine to suppress the flashes in Firefox?

Hello, I was developing exactly the same thing when I came across this PR. What's new about a merge of this PR ?

and I think I'll probably merge this one (opposed to #966). I'll need to do a bit more thinking over the next few days and will either leave nit comments or approve it.

I now read this message and do not understand why it is preferable to load a theme via js than via media query (#858 and #966).... this causes flashes when starting the browser as documented at the beginning of the PR, it is absolutely preferable to use media queries:

JS code:

{% if site.dark_color_scheme and site.dark_color_scheme != 'nil' -%}
    if (window.matchMedia) {
        window.matchMedia('(prefers-color-scheme: dark)')
              .addEventListener('change', event => {
          if (event.matches) {
              jtd.setTheme('{{site.dark_color_scheme}}');
          } else {
              {% if site.color_scheme and site.color_scheme != 'nil' -%}
                  jtd.setTheme('{{site.color_scheme}}');
              {% else -%}
                  jtd.setTheme('light');
              {%- endif %}
          }
        });

        if(window.matchMedia('(prefers-color-scheme: dark)').matches) {
            jtd.setTheme('{{site.dark_color_scheme}}');
        }
    }
{%- endif %}

vs

pure HTML5 code:

  <link rel="stylesheet" href="iframe.php?url=https%3A%2F%2Fgithub.com%2F%7B%7B+"/assets/css/just-the-docs-light.css' | relative_url }}" media="(prefers-color-scheme: light)">
  <link rel="stylesheet" href="iframe.php?url=https%3A%2F%2Fgithub.com%2F%7B%7B+"/assets/css/just-the-docs-dark.css' | relative_url }}" media="(prefers-color-scheme: dark)">

I would like to add that a fix will most probably be added to this PR as well, so that the buttons can be used to change the theme (code in #966 but not #858). Yes it is always possible to cherry-pick, but does it make sense to add all this JS code?

jtd.getTheme = function() {
  var cssFile = document.querySelector('[rel="stylesheet"]');
  if(cssFile.hasAttribute('media')) return 'auto';

  var cssFileHref = cssFile.getAttribute('href');
  return cssFileHref.substring(cssFileHref.lastIndexOf('-') + 1, cssFileHref.length - 4);
}

jtd.setTheme = function(theme) {
  var cssFiles = [...document.querySelectorAll('[rel="stylesheet"]')];
  var cssFile = cssFiles[0];
  if(cssFiles.length >= 1) {
    cssFiles.shift();
    cssFiles.forEach(it => it.remove());
    cssFile.removeAttribute('media');
  }
  cssFile.setAttribute('href', '{{ "assets/css/just-the-docs-" | relative_url }}' + theme + '.css');
}

I have create a #1086 that even merge part of this PR and other PR: namely the fact that you can enable or disable this from _config.yml.

this causes flashes when starting the browser

Not only when starting it: I see really bad FOUCs also when navigating between the deploy preview pages with Firefox (108.0.1, macOS 12.6.2, MacBook Pro M1, system state auto/dark).