Add 'neutral' header option, rel v0.7.0

ChangeLog.md

@@ -1,5 +1,9 @@
 # Change Log
 
+## [0.7.0] - 2024-12-02
+
+- New: Theme option `style_header_neutral` (boolean) to integrate header background color with light/dark color-schemes. Update docs and tests accordingly.
+
 ## [0.6.0] - 2024-11-29
 
 - New: Highlight the item in the TOC at the right side ('on this page' column) when the location bar refers to an anchor that is part of the TOC.

Makefile

@@ -29,7 +29,7 @@ build-ext:  ## Build Sphinx extension.
 	npm run build
 	mkdir -p sphinx_nefertiti/static/
 	mkdir -p sphinx_nefertiti/colorsets/
-	cp site/css/bootstrap-icons.css   			sphinx_nefertiti/static/
+	cp site/css/bootstrap-icons.min.css			sphinx_nefertiti/static/
 	cp site/css/bootstrap-icons.woff2 			sphinx_nefertiti/static/
 	cp site/js/*.min.js               		  	sphinx_nefertiti/static/
 	cp site/js/*.min.js.map           		  	sphinx_nefertiti/static/

docs/source/conf.py

@@ -34,6 +34,7 @@
 releases = [
     "latest",
     release,
+    "0.6.0",
     "0.5.3",
     "0.4.2",
     "0.3.7",
@@ -87,6 +88,7 @@
     "monospace_font_size": "1.1rem",
 
     "style": "blue",
+    "style_header_neutral": True,
     "pygments_light_style": "pastie",
     "pygments_dark_style": "dracula",
 

docs/source/quick-start.rst

@@ -150,7 +150,7 @@ The following content will produced the header of the image below:
 3. Colorsets
 ============
 
-Another customizable feature of the theme is the color set. In the header of this documentation you can see a dropdown with a palette icon. The colors listed in the dropdown represent the available color sets. Try them to apply the selected color set to this documentation.
+Another customizable feature of the theme is the colorset. In the header of this documentation you can see a dropdown with a palette icon. The colors listed in the dropdown represent the available color sets. Try them to apply the selected color set to this documentation.
 
 To customize the color set in your project add an entry ``style`` to the ``html_theme_options`` setting in your ``conf.py`` module:
 
@@ -161,7 +161,9 @@ To customize the color set in your project add an entry ``style`` to the ``html_
         "style": "pink",
     }
 
-When ``style`` is not given the theme defaults to ``cyan``.
+When ``style`` is not given the theme defaults to ``default``, which is cyan.
+
+Another available setting is ``style_header_neutral``, that when is set to ``True``, makes the header color to adapt to the light or dark color-scheme setting. To test it here, use the colorset dropdown at the top right side of the header.
 
 4. Pygments styles
 ==================

docs/source/users-guide/customization/colorsets.rst

@@ -105,15 +105,21 @@ To customize the colorset in your project add an entry ``style`` to the ``html_t
         "style": "pink",
     }
 
-Save the changes and rebuild the site:
+Possible values are: ``blue``, ``indigo``, ``purple``, ``pink``, ``red``, ``orange``, ``yellow``, ``green``, ``tail`` and ``default`` (which is cyan).
 
-.. code-block:: shell
 
-    $ make clean
-    $ make html
-    $ python -m http.server -d build/html
+The ``style_header_neutral`` setting
+************************************
+
+By default the header's background color does not change when switching between light and dark schemes. If you want it to adapt to light and dark schemes, turn on the ``style_header_neutral`` setting:
+
+.. code-block:: python
+
+    html_theme_options = {
+        # ... other options ...
+        "style_header_neutral": True,
+    }
 
-Visit http://localhost:8000 to take a look at the changes.
 
 Custom CSS file
 ***************

js/src/pagetoc.js

@@ -92,7 +92,7 @@ export class LocationHashHandler {
   }
 
   hashChanged = (_) => {
-    const anchors = this.toc.querySelectorAll("a.reference.internal");
+    const anchors = this.toc?.querySelectorAll("a.reference.internal") || [];
     for (const anchor of anchors) {
       anchor.classList.remove("active");
     }

js/src/versions.js

@@ -54,7 +54,7 @@ export function feedVersionsMenu() {
     anchor.dataset.snfttVersionUrl = item.url;
     anchor.dataset.snfttVersion = item.name;
     const span = document.createElement("span");
-    span.classList.add("small", "ms-2");
+    span.classList.add("ms-2");
     span.textContent = item.name;
     const i = document.createElement("i");
     i.classList.add("bi", "bi-check", "ms-auto");

package.json

@@ -1,6 +1,6 @@
 {
   "name": "sphinx-nefertiti",
-  "version": "0.6.0",
+  "version": "0.7.0",
   "private": true,
   "description": "Nefertiti is a theme for the Sphinx Documentation Generator.",
   "engines": {

scss/_root.scss

@@ -52,7 +52,9 @@
 
   --#{$prefix}docapi-kw-color: #{$docapi-light-kw-color};
 
-  // btn-neutral variables:
+  // neutral variables:
+  // --#{$prefix}-neutral-bg-rgb: 255, 255, 255;
+  --#{$prefix}neutral-bg-rgb: #{to-rgb($scheme-light-neutral-bg)};
   --#{$prefix}btn-neutral-color: #000;
   --#{$prefix}btn-neutral-bg: #fff;
   --#{$prefix}btn-neutral-border-color: #fff;
@@ -131,7 +133,8 @@
 
   --#{$prefix}docapi-kw-color: #{$docapi-dark-kw-color};
 
-  // btn-neutral variables:
+  // neutral variables:
+  --#{$prefix}neutral-bg-rgb: #{to-rgb($scheme-dark-neutral-bg)};
   --#{$prefix}btn-neutral-color: #fff;
   --#{$prefix}btn-neutral-bg: #343a40;
   --#{$prefix}btn-neutral-border-color: #343a40;

scss/_variables-blue.scss

@@ -36,6 +36,7 @@ $blue-200: tint-color($blue, 60%) !default;
 $blue-600: shade-color($blue, 20%) !default;
 $blue-700: shade-color($blue, 40%) !default;
 $blue-800: shade-color($blue, 60%) !default;
+$blue-900: shade-color($blue, 80%) !default;
 
 $cyan-200: tint-color($cyan, 60%) !default;
 $cyan-700: shade-color($cyan, 40%) !default;
@@ -65,6 +66,7 @@ $dark:          $gray-800 !default;
 $scheme-light-body-color: $gray-700;
 $scheme-light-body-hc-color: $gray-800;
 $scheme-light-body-bg: $gray-200;
+$scheme-light-neutral-bg: $blue-100;
 $scheme-light-body-secondary-color: rgba($scheme-light-body-color, .75) !default;
 $scheme-light-body-secondary-bg: $blue-100 !default;
 $scheme-light-body-tertiary-color: rgba($scheme-light-body-color, .8) !default;
@@ -103,6 +105,7 @@ $scheme-light-table-striped-bg: tint-color($blue, 90%);
 $scheme-dark-body-color: $gray-100;
 $scheme-dark-body-hc-color: $white;
 $scheme-dark-body-bg: $gray-900;
+$scheme-dark-neutral-bg: $blue-900;
 $scheme-dark-body-secondary-color: rgba($scheme-dark-body-color, .75) !default;
 $scheme-dark-body-secondary-bg: $gray-800 !default;
 $scheme-dark-body-tertiary-color: rgba($scheme-dark-body-color, .5) !default;

scss/_variables-cyan.scss

@@ -67,6 +67,7 @@ $dark:          $gray-800 !default;
 $scheme-light-body-color: $gray-700;
 $scheme-light-body-hc-color: $gray-800;
 $scheme-light-body-bg: $gray-200;
+$scheme-light-neutral-bg: $cyan-100;
 $scheme-light-body-secondary-color: rgba($scheme-light-body-color, .9) !default;
 $scheme-light-body-secondary-bg: $cyan-100 !default;
 $scheme-light-body-tertiary-color: rgba($scheme-light-body-color, .8) !default;
@@ -104,6 +105,7 @@ $scheme-light-table-striped-bg: tint-color($cyan, 90%);
 $scheme-dark-body-color: $gray-100;
 $scheme-dark-body-hc-color: $white;
 $scheme-dark-body-bg: $gray-900;
+$scheme-dark-neutral-bg: $cyan-900;
 $scheme-dark-body-secondary-color: rgba($scheme-dark-body-color, .75) !default;
 $scheme-dark-body-secondary-bg: $gray-800 !default;
 $scheme-dark-body-tertiary-color: rgba($scheme-dark-body-color, .5) !default;

scss/_variables-green.scss

@@ -35,6 +35,7 @@ $green-100: tint-color($green, 80%) !default;
 $green-400: tint-color($green, 20%) !default;
 $green-600: shade-color($green, 20%) !default;
 $green-800: shade-color($green, 60%) !default;
+$green-900: shade-color($green, 80%) !default;
 
 $blue-200: tint-color($blue, 60%) !default;
 $blue-600: shade-color($blue, 20%) !default;
@@ -68,6 +69,7 @@ $dark:          $gray-800 !default;
 $scheme-light-body-color: $gray-700;
 $scheme-light-body-hc-color: $gray-800;
 $scheme-light-body-bg: $gray-200;
+$scheme-light-neutral-bg: $green-100;
 $scheme-light-body-secondary-color: rgba($scheme-light-body-color, .75) !default;
 $scheme-light-body-secondary-bg: $green-100 !default;
 $scheme-light-body-tertiary-color: rgba($scheme-light-body-color, .8) !default;
@@ -105,6 +107,7 @@ $scheme-light-table-striped-bg: tint-color($green, 90%);
 $scheme-dark-body-color: $gray-100;
 $scheme-dark-body-hc-color: $white;
 $scheme-dark-body-bg: $gray-900;
+$scheme-dark-neutral-bg: $green-900;
 $scheme-dark-body-secondary-color: rgba($scheme-dark-body-color, .75) !default;
 $scheme-dark-body-secondary-bg: $gray-800 !default;
 $scheme-dark-body-tertiary-color: rgba($scheme-dark-body-color, .5) !default;

scss/_variables-indigo.scss

@@ -37,6 +37,7 @@ $indigo-400: tint-color($indigo, 20%) !default;
 $indigo-500: $indigo !default;
 $indigo-700: shade-color($indigo, 40%) !default;
 $indigo-800: shade-color($indigo, 60%) !default;
+$indigo-900: shade-color($indigo, 80%) !default;
 
 $blue-100: tint-color($blue, 80%) !default;
 $blue-200: tint-color($blue, 60%) !default;
@@ -70,6 +71,7 @@ $dark:          $gray-800 !default;
 $scheme-light-body-color: $gray-700;
 $scheme-light-body-hc-color: $gray-800;
 $scheme-light-body-bg: $gray-200;
+$scheme-light-neutral-bg: $indigo-100;
 $scheme-light-body-secondary-color: rgba($scheme-light-body-color, .75) !default;
 $scheme-light-body-secondary-bg: $indigo-100 !default;
 $scheme-light-body-tertiary-color: rgba($scheme-light-body-color, .8) !default;
@@ -107,6 +109,7 @@ $scheme-light-table-striped-bg: tint-color($indigo, 90%);
 $scheme-dark-body-color: $gray-100;
 $scheme-dark-body-hc-color: $white;
 $scheme-dark-body-bg: $gray-900;
+$scheme-dark-neutral-bg: $indigo-900;
 $scheme-dark-body-secondary-color: rgba($scheme-dark-body-color, .75) !default;
 $scheme-dark-body-secondary-bg: $gray-800 !default;
 $scheme-dark-body-tertiary-color: rgba($scheme-dark-body-color, .5) !default;

scss/_variables-orange.scss

@@ -71,6 +71,7 @@ $dark:          $gray-800 !default;
 $scheme-light-body-color: $gray-700;
 $scheme-light-body-hc-color: $gray-800;
 $scheme-light-body-bg: $gray-200;
+$scheme-light-neutral-bg: $orange-100;
 $scheme-light-body-secondary-color: rgba($scheme-light-body-color, .75) !default;
 $scheme-light-body-secondary-bg: $orange-100 !default;
 $scheme-light-body-tertiary-color: rgba($scheme-light-body-color, .8) !default;
@@ -108,6 +109,7 @@ $scheme-light-table-striped-bg: tint-color($orange, 90%);
 $scheme-dark-body-color: $gray-100;
 $scheme-dark-body-hc-color: $white;
 $scheme-dark-body-bg: $gray-900;
+$scheme-dark-neutral-bg: $orange-900;
 $scheme-dark-body-secondary-color: rgba($scheme-dark-body-color, .75) !default;
 $scheme-dark-body-secondary-bg: $gray-800 !default;
 $scheme-dark-body-tertiary-color: rgba($scheme-dark-body-color, .5) !default;

scss/_variables-pink.scss

@@ -38,6 +38,7 @@ $pink-500: $pink !default;
 $pink-600: shade-color($pink, 20%) !default;
 $pink-700: shade-color($pink, 40%) !default;
 $pink-800: shade-color($pink, 60%) !default;
+$pink-900: shade-color($pink, 80%) !default;
 
 $blue-100: tint-color($blue, 80%) !default;
 $blue-200: tint-color($blue, 60%) !default;
@@ -71,6 +72,7 @@ $dark:          $gray-800 !default;
 $scheme-light-body-color: $gray-700;
 $scheme-light-body-hc-color: $gray-800;
 $scheme-light-body-bg: $gray-200;
+$scheme-light-neutral-bg: $pink-100;
 $scheme-light-body-secondary-color: rgba($scheme-light-body-color, .75) !default;
 $scheme-light-body-secondary-bg: $pink-100 !default;
 $scheme-light-body-tertiary-color: rgba($scheme-light-body-color, .8) !default;
@@ -108,6 +110,7 @@ $scheme-light-table-striped-bg: tint-color($pink, 90%);
 $scheme-dark-body-color: $gray-100;
 $scheme-dark-body-hc-color: $white;
 $scheme-dark-body-bg: $gray-900;
+$scheme-dark-neutral-bg: $pink-900;
 $scheme-dark-body-secondary-color: rgba($scheme-dark-body-color, .75) !default;
 $scheme-dark-body-secondary-bg: $gray-800 !default;
 $scheme-dark-body-tertiary-color: rgba($scheme-dark-body-color, .5) !default;

scss/_variables-purple.scss

@@ -35,6 +35,7 @@ $purple-100: tint-color($purple, 80%) !default;
 $purple-400: tint-color($purple, 20%) !default;
 $purple-500: $purple !default;
 $purple-800: shade-color($purple, 60%) !default;
+$purple-900: shade-color($purple, 80%) !default;
 
 $blue-100: tint-color($blue, 80%) !default;
 $blue-200: tint-color($blue, 60%) !default;
@@ -70,6 +71,7 @@ $dark:          $gray-800 !default;
 $scheme-light-body-color: $gray-700;
 $scheme-light-body-hc-color: $gray-800;
 $scheme-light-body-bg: $gray-200;
+$scheme-light-neutral-bg: $purple-100;
 $scheme-light-body-secondary-color: rgba($scheme-light-body-color, .75) !default;
 $scheme-light-body-secondary-bg: $purple-100 !default;
 $scheme-light-body-tertiary-color: rgba($scheme-light-body-color, .8) !default;
@@ -107,6 +109,7 @@ $scheme-light-table-striped-bg: tint-color($purple, 90%);
 $scheme-dark-body-color: $gray-100;
 $scheme-dark-body-hc-color: $white;
 $scheme-dark-body-bg: $gray-900;
+$scheme-dark-neutral-bg: $purple-900;
 $scheme-dark-body-secondary-color: rgba($scheme-dark-body-color, .75) !default;
 $scheme-dark-body-secondary-bg: $gray-800 !default;
 $scheme-dark-body-tertiary-color: rgba($scheme-dark-body-color, .5) !default;

scss/_variables-red.scss

@@ -37,6 +37,7 @@ $red-400: tint-color($red, 20%) !default;
 $red-500: $red !default;
 $red-600: shade-color($red, 20%) !default;
 $red-800: shade-color($red, 60%) !default;
+$red-900: shade-color($red, 80%) !default;
 
 $blue-100: tint-color($blue, 80%) !default;
 $blue-200: tint-color($blue, 60%) !default;
@@ -69,6 +70,7 @@ $dark:          $gray-800 !default;
 $scheme-light-body-color: $gray-700;
 $scheme-light-body-hc-color: $gray-800;
 $scheme-light-body-bg: $gray-200;
+$scheme-light-neutral-bg: $red-100;
 $scheme-light-body-secondary-color: rgba($scheme-light-body-color, .75) !default;
 $scheme-light-body-secondary-bg: $red-100 !default;
 $scheme-light-body-tertiary-color: rgba($scheme-light-body-color, .8) !default;
@@ -106,6 +108,7 @@ $scheme-light-table-striped-bg: tint-color($red, 90%);
 $scheme-dark-body-color: $gray-100;
 $scheme-dark-body-hc-color: $white;
 $scheme-dark-body-bg: $gray-900;
+$scheme-dark-neutral-bg: $red-900;
 $scheme-dark-body-secondary-color: rgba($scheme-dark-body-color, .75) !default;
 $scheme-dark-body-secondary-bg: $gray-800 !default;
 $scheme-dark-body-tertiary-color: rgba($scheme-dark-body-color, .5) !default;

scss/_variables-teal.scss

@@ -69,6 +69,7 @@ $dark:          $gray-800 !default;
 $scheme-light-body-color: $gray-700;
 $scheme-light-body-hc-color: $gray-800;
 $scheme-light-body-bg: $gray-200;
+$scheme-light-neutral-bg: $teal-100;
 $scheme-light-body-secondary-color: rgba($scheme-light-body-color, .75) !default;
 $scheme-light-body-secondary-bg: $teal-100 !default;
 $scheme-light-body-tertiary-color: rgba($scheme-light-body-color, .8) !default;
@@ -106,6 +107,7 @@ $scheme-light-table-striped-bg: tint-color($teal, 90%);
 $scheme-dark-body-color: $gray-100;
 $scheme-dark-body-hc-color: $white;
 $scheme-dark-body-bg: $gray-900;
+$scheme-dark-neutral-bg: $teal-900;
 $scheme-dark-body-secondary-color: rgba($scheme-dark-body-color, .75) !default;
 $scheme-dark-body-secondary-bg: $gray-800 !default;
 $scheme-dark-body-tertiary-color: rgba($scheme-dark-body-color, .5) !default;

scss/_variables-yellow.scss

@@ -69,6 +69,7 @@ $dark:          $gray-800 !default;
 $scheme-light-body-color: $gray-700;
 $scheme-light-body-hc-color: $gray-800;
 $scheme-light-body-bg: $gray-200;
+$scheme-light-neutral-bg: $yellow-100;
 $scheme-light-body-secondary-color: rgba($scheme-light-body-color, .75) !default;
 $scheme-light-body-secondary-bg: $yellow-100 !default;
 $scheme-light-body-tertiary-color: rgba($scheme-light-body-color, .8) !default;
@@ -106,6 +107,7 @@ $scheme-light-table-striped-bg: tint-color($yellow, 90%);
 $scheme-dark-body-color: $gray-100;
 $scheme-dark-body-hc-color: $white;
 $scheme-dark-body-bg: $gray-900;
+$scheme-dark-neutral-bg: $yellow-900;
 $scheme-dark-body-secondary-color: rgba($scheme-dark-body-color, .75) !default;
 $scheme-dark-body-secondary-bg: $gray-800 !default;
 $scheme-dark-body-tertiary-color: rgba($scheme-dark-body-color, .5) !default;

scss/components/_navbar.scss

@@ -54,6 +54,10 @@
   background-image: linear-gradient(to bottom, rgba(var(--#{$prefix}primary-rgb), 1), rgba(var(--#{$prefix}primary-rgb), .9));
   box-shadow: 0 .5rem 1rem rgba(0, 0, 0, .15), inset 0 -1px 0 rgba(0, 0, 0, .15);
 
+  &.neutral {
+    background-image: linear-gradient(to bottom, rgba(var(--#{$prefix}neutral-bg-rgb), 1), rgba(var(--#{$prefix}neutral-bg-rgb), .9));
+  }
+
   .navbar-brand {
     display: flex;
     align-items: center;
@@ -163,6 +167,7 @@
   }
 }
 
+
 /* stylelint-disable-next-line */
 #nfttNavbar {
   background-color: $primary;