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

CHANGELOG.md

@@ -19,16 +19,6 @@ Code changes to `main` that are *not* in the latest release:
 
 - N/A
 
-## Release v0.6.1
-
-Hi all, this is a small patch release that only includes one change: resolving a bug introduced in 0.6.0 that causes a JS error for pages excluded from navigation.
-
-### Bugfixes
-
-- Fixed: JS error for pages excluded from navigation by [@pdmosses] in [#1332]
-
-[#1332]: https://github.com/just-the-docs/just-the-docs/pull/1332
-
 ## Release v0.6.0
 
 Hi all, this is a minor release that introduces performance improvements for build times on large sites, correctly sets the `color-scheme` property, and fixes invalid HTML. However, it introduces some potentially-breaking *internal* changes to undocumented features of the theme.

Gemfile.lock

@@ -1,7 +1,7 @@
 PATH
   remote: .
   specs:
-    just-the-docs (0.6.1)
+    just-the-docs (0.6.0)
       jekyll (>= 3.8.5)
       jekyll-include-cache
       jekyll-seo-tag (>= 2.0)

_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

@@ -14,7 +14,48 @@
   <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 %}
 

_includes/head_nav.html

@@ -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

@@ -76,10 +76,8 @@ function initNav() {
 // The page-specific stylesheet is assumed to have index 1 in the list of stylesheets.
 
 function disableHeadStyleSheet() {
-  if (document.styleSheets[1]) {
   document.styleSheets[1].disabled = true;
 }
-}
 
 {%- if site.search_enabled != false %}
 // Site search
@@ -467,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"]');
+  function createThemeStylesheet(theme, media) {
-  cssFile.setAttribute('href', '{{ "assets/css/just-the-docs-" | relative_url }}' + theme + '.css');
+    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
@@ -535,6 +576,9 @@ jtd.onReady(function(){
   {%- if site.search_enabled != false %}
   initSearch();
   {%- endif %}
+  {%- if site.enable_switch_color_scheme != false %}
+  initSwitchThemeButton();
+  {%- endif %}
   activateNav();
   scrollNav();
 });

just-the-docs.gemspec

@@ -2,7 +2,7 @@
 
 Gem::Specification.new do |spec|
   spec.name          = "just-the-docs"
-  spec.version       = "0.6.1"
+  spec.version       = "0.6.0"
   spec.authors       = ["Patrick Marsceill", "Matthew Wang"]
   spec.email         = ["patrick.marsceill@gmail.com", "matt@matthewwang.me"]