Draft: porting over https://github.com/just-the-docs/just-the-docs/pull/1086/

_config.yml

@@ -140,7 +140,11 @@ gh_edit_branch: "main" # the branch that your docs is served from
 gh_edit_view_mode: "tree" # "tree" or "edit" if you want the user to jump into the editor immediately
 
 # Color scheme currently only supports "dark", "light"/nil (default), or a custom scheme that you define
-color_scheme: nil
+color_scheme: auto
+color_scheme_options:
+  enable_localstorage: true
+  enable_switch: true
+  switch_options: ["auto", "light", "dark"]
 
 callouts_level: quiet # or loud
 callouts:

_includes/components/aux_nav.html

@@ -11,5 +11,12 @@
         </a>
       </li>
     {% endfor %}
+    {% if site.color_scheme_options and site.color_scheme_options.switch_options %}
+    <li class="aux-nav-list-item">
+      <button class="site-button color-scheme-switch-theme-button" aria-label="Switch color scheme">
+        <svg aria-hidden="true" class="site-button-icon"><use href="#svg-{{ site.color_scheme | default: 'light' }}"></use></svg>
+      </button>
+    </li>
+    {% endif %}
   </ul>
 </nav>

_includes/components/header.html

@@ -5,7 +5,7 @@
     <div></div>
   {% endif %}
   {% include header_custom.html %}
-  {% if site.aux_links %}
+  {% if site.aux_links or site.color_scheme_options and site.color_scheme_options.switch_options %}
     {% include components/aux_nav.html %}
   {% endif %}
 </div>

_includes/head.html

@@ -5,7 +5,7 @@
   Results in: HTML for the head element.
   Includes:
     head_nav.html, head_custom.html.
-  Overwrites: 
+  Overwrites:
     ga_tracking_ids, ga_property, file, favicon.
   Should not be cached, because included files depend on page.
 {%- endcomment -%}
@@ -14,8 +14,49 @@
   <meta charset="UTF-8">
   <meta http-equiv="X-UA-Compatible" content="IE=Edge">
 
-  <link rel="stylesheet" href="{{ '/assets/css/just-the-docs-default.css' | relative_url }}">
-  
+  {% if site.color_scheme_options and site.color_scheme_options.enable_localstorage %}
+  <script>
+    (function(){
+      function createThemeStylesheet(theme, media) {
+        var link  = document.createElement('link');
+        link.rel  = 'stylesheet';
+        link.type = 'text/css';
+        link.href = "{{ '/assets/css/just-the-docs-*.css' | relative_url }}".replace("*",theme);
+        if(media) link.media = media;
+        return link;
+      }
+
+      var theme = window.localStorage.getItem('theme');
+      var head = document.getElementsByTagName('head')[0];
+
+      if (theme === null) {
+        theme = "{{ site.color_scheme }}";
+      }
+
+      if (theme === "nil") {
+        theme = "default";
+      }
+
+      if (theme === "auto") {
+        head.appendChild(createThemeStylesheet('light', '(prefers-color-scheme: light)'));
+        head.appendChild(createThemeStylesheet('dark', '(prefers-color-scheme: dark)'));
+      } else {
+        head.appendChild(createThemeStylesheet(theme || "default"));
+      }
+    })();
+  </script>
+  {% else %}
+    {% case site.color_scheme %}
+    {% when "auto" %}
+      <link rel="stylesheet" href="{{ '/assets/css/just-the-docs-light.css' | relative_url }}" type="text/css" media="(prefers-color-scheme: light)">
+      <link rel="stylesheet" href="{{ '/assets/css/just-the-docs-dark.css' | relative_url }}" type="text/css" media="(prefers-color-scheme: dark)">
+    {% when nil %}
+      <link rel="stylesheet" href="{{ '/assets/css/just-the-docs-default.css' | relative_url }}" type="text/css">
+    {% else %}
+      <link rel="stylesheet" href="{{ site.color_scheme | prepend: '/assets/css/just-the-docs-' | append: '.css' | relative_url }}" type="text/css">
+    {% endcase %}
+  {% endif %}
+
   {% include head_nav.html %}
 
   {% if site.ga_tracking != nil %}

_includes/head_nav.html

@@ -4,7 +4,7 @@
   Results in: HTML for a page-specific style element.
   Includes:
     css/activation.scss.liquid.
-  Overwrites: 
+  Overwrites:
     activation, test_scss, scss, css, index, count.
   Should not be cached, because css/activation.scss.liquid depends on page.
 {%- endcomment -%}
@@ -28,7 +28,7 @@
     {%- assign color_scheme = "light" -%}
   {%- endif %}
   @import "./color_schemes/light";
-  {% unless color_scheme == "light" %}
+  {% unless color_scheme == "light" or color_scheme == "auto" %}
   @import "./color_schemes/{{ color_scheme }}";
   {% endunless %}
   {{ activation }}

_includes/icons/icons.html

@@ -10,4 +10,7 @@
   {% if site.enable_copy_code_button != false %}
     {% include icons/code_copy.html %}
   {% endif %}
+  {% if site.color_scheme_options and site.color_scheme_options.enable_switch %}
+    {% include icons/switch_color_scheme.html %}
+  {% endif %}
 </svg>

_includes/icons/switch_color_scheme.html

@@ -0,0 +1,29 @@
+<!-- Feather. Public domain or under the CC0-1.0-Universal license: https://github.com/python/peps/blob/ebff37d5e7728377035b1e1ce9c9796ed63940b1/pep_sphinx_extensions/LICENCE.rst -->
+<symbol id="svg-auto" viewBox="0 0 24 24" pointer-events="all">
+  <title>Following system colour scheme</title>
+  <svg xmlns="http://www.w3.org/2000/svg" viewBox="0 0 24 24" fill="none" stroke="currentColor" stroke-width="2" stroke-linecap="round" stroke-linejoin="round">
+    <circle cx="12" cy="12" r="9"></circle>
+    <path d="M12 3v18m0-12l4.65-4.65M12 14.3l7.37-7.37M12 19.6l8.85-8.85"></path>
+  </svg>
+</symbol>
+<symbol id="svg-dark" viewBox="0 0 24 24" pointer-events="all">
+  <title>Selected dark colour scheme</title>
+  <svg xmlns="http://www.w3.org/2000/svg" viewBox="0 0 24 24" fill="none" stroke="currentColor" stroke-width="2" stroke-linecap="round" stroke-linejoin="round">
+    <path stroke="none" d="M0 0h24v24H0z" fill="none"></path>
+    <path d="M12 3c.132 0 .263 0 .393 0a7.5 7.5 0 0 0 7.92 12.446a9 9 0 1 1 -8.313 -12.454z"></path>
+  </svg>
+</symbol>
+<symbol id="svg-light" viewBox="0 0 24 24" pointer-events="all">
+  <title>Selected light colour scheme</title>
+  <svg xmlns="http://www.w3.org/2000/svg" viewBox="0 0 24 24" fill="none" stroke="currentColor" stroke-width="2" stroke-linecap="round" stroke-linejoin="round">
+    <circle cx="12" cy="12" r="5"></circle>
+    <line x1="12" y1="1" x2="12" y2="3"></line>
+    <line x1="12" y1="21" x2="12" y2="23"></line>
+    <line x1="4.22" y1="4.22" x2="5.64" y2="5.64"></line>
+    <line x1="18.36" y1="18.36" x2="19.78" y2="19.78"></line>
+    <line x1="1" y1="12" x2="3" y2="12"></line>
+    <line x1="21" y1="12" x2="23" y2="12"></line>
+    <line x1="4.22" y1="19.78" x2="5.64" y2="18.36"></line>
+    <line x1="18.36" y1="5.64" x2="19.78" y2="4.22"></line>
+  </svg>
+</symbol>

_sass/layout.scss

@@ -140,11 +140,32 @@
   }
 }
 
+button.site-button {
+  background: none;
+  border: none;
+}
+
 .site-button {
   display: flex;
   height: 100%;
   padding: $gutter-spacing-sm;
   align-items: center;
+
+  .site-button-icon {
+    width: #{$sp-4 * 1.2};
+    height: #{$sp-4 * 1.2};
+    align-self: center;
+    color: $grey-dk-000;
+    cursor: pointer;
+  }
+
+  &:hover,
+  &:focus,
+  &:active {
+    .site-button-icon {
+      color: $link-color;
+    }
+  }
 }
 
 @include mq(md) {

assets/css/just-the-docs-default.scss

@@ -1,6 +1,6 @@
 ---
 ---
-{% if site.color_scheme and site.color_scheme != "nil" %}
+{% if site.color_scheme and site.color_scheme != "nil" and site.color_scheme != "auto" %}
   {% assign color_scheme = site.color_scheme %}
 {% else %}
   {% assign color_scheme = "light" %}

assets/js/just-the-docs.js

@@ -41,7 +41,7 @@ function initNav() {
   const siteNav = document.getElementById('site-nav');
   const mainHeader = document.getElementById('main-header');
   const menuButton = document.getElementById('menu-button');
-  
+
   disableHeadStyleSheet();
 
   jtd.addEvent(menuButton, 'click', function(e){
@@ -72,7 +72,7 @@ function initNav() {
 }
 
 // The page-specific <style> in the <head> is needed only when JS is disabled.
-// Moreover, it incorrectly overrides dynamic stylesheets set by setTheme(theme). 
+// Moreover, it incorrectly overrides dynamic stylesheets set by setTheme(theme).
 // The page-specific stylesheet is assumed to have index 1 in the list of stylesheets.
 
 function disableHeadStyleSheet() {
@@ -465,13 +465,56 @@ function searchLoaded(index, docs) {
 // Switch theme
 
 jtd.getTheme = function() {
-  var cssFileHref = document.querySelector('[rel="stylesheet"]').getAttribute('href');
+  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 cssFile = document.querySelector('[rel="stylesheet"]');
-  cssFile.setAttribute('href', '{{ "assets/css/just-the-docs-" | relative_url }}' + theme + '.css');
+  function createThemeStylesheet(theme, media) {
+    var link  = document.createElement('link');
+    link.rel  = 'stylesheet';
+    link.type = 'text/css';
+    link.href = "{{ '/assets/css/just-the-docs-*.css' | relative_url }}".replace("*",theme);
+    if(media) link.media = media;
+    return link;
+  }
+  var cssFiles = [...document.querySelectorAll('[rel="stylesheet"]')];
+  if(theme === "auto") {
+    cssFiles.at(-1).insertAdjacentElement('afterend', createThemeStylesheet('light', '(prefers-color-scheme: light)'));
+    cssFiles.at(-1).insertAdjacentElement('afterend', createThemeStylesheet('dark', '(prefers-color-scheme: dark)'));
+  } else {
+    cssFiles.at(-1).insertAdjacentElement('afterend', createThemeStylesheet(theme || "default"));
+  }
+  setTimeout(() => cssFiles.forEach(it => it.remove()), 100);
+}
+
+jtd.switchThemeButton = function(button, event) {
+  {% if site.color_scheme_options and site.color_scheme_options.switch_options %}
+  const themes = {{ site.color_scheme_options.switch_options | jsonify }};
+  {% else %}
+  const themes = ["auto", "light", "dark"];
+  {% endif %}
+  var currentTheme = jtd.getTheme();
+  var nextTheme = themes[(themes.indexOf(currentTheme)+1)%themes.length];
+  jtd.setTheme(nextTheme);
+  button.getElementsByTagName('svg')[0].getElementsByTagName('use')[0].setAttribute('href',`#svg-${nextTheme}`);
+  {% if site.color_scheme_options and site.color_scheme_options.enable_localstorage  %}
+  window.localStorage.setItem('theme', nextTheme);
+  {% endif %}
+}
+
+function initSwitchThemeButton() {
+  var buttons = [...document.getElementsByClassName("color-scheme-switch-theme-button")];
+  {% if site.color_scheme_options and site.color_scheme_options.enable_localstorage  != false %}
+  theme = window.localStorage.getItem('theme');
+  if(theme != null){
+    buttons.forEach(button => button.getElementsByTagName('svg')[0].getElementsByTagName('use')[0].setAttribute('href',`#svg-${theme}`));
+  }
+  {% endif %}
+  buttons.forEach(button => jtd.addEvent(button, 'click', event => jtd.switchThemeButton(button, event)));
 }
 
 // Note: pathname can have a trailing slash on a local jekyll server
@@ -533,6 +576,9 @@ jtd.onReady(function(){
   {%- if site.search_enabled != false %}
   initSearch();
   {%- endif %}
+  {%- if site.enable_switch_color_scheme != false %}
+  initSwitchThemeButton();
+  {%- endif %}
   activateNav();
   scrollNav();
 });