Clean up the styling

builder/scss.mjs

@@ -10,6 +10,17 @@
 // `_sass/custom/custom.scss` in the site root shadowed the gem's empty
 // upstream version. The same shadowing now happens via load-path ordering.
 //
+// TWO sass.compile() calls are used:
+//   1. just-the-docs-combined.scss -- light theme
+//   2. just-the-docs-dark.scss     -- dark theme (html.dark-mode { ... })
+// The results are concatenated into a single CSS asset.
+//
+// Two separate compilations are required because Dart Sass maintains one
+// module cache per compile() call, and a module URL can only be loaded once
+// per compilation with one variable configuration.  The dark theme needs
+// modules.scss loaded with different variable values, which is only possible
+// in a fresh compilation with its own empty cache.
+//
 // Failure modes:
 //   SETUP   -- sass not installed: throw. There is no pre-compiled fallback;
 //              `npm install` is the fix. The error message points there.
@@ -26,35 +37,44 @@ import { fileURLToPath } from "node:url";
 
 const __dirname = path.dirname(fileURLToPath(import.meta.url));
 const VENDOR_JTD_SASS = path.join(__dirname, "vendor", "just-the-docs", "_sass");
-const SCSS_REL = path.join("assets", "css", "just-the-docs-combined.scss");
+const SCSS_LIGHT_REL = path.join("assets", "css", "just-the-docs-combined.scss");
+const SCSS_DARK_REL  = path.join("assets", "css", "just-the-docs-dark.scss");
 
 export async function compileScss(srcRoot) {
   let sass;
   try {
-    sass = (await import("sass")).default;
+    sass = await import("sass");
   } catch (err) {
     throw new Error(
       "scss: sass not installed. Run `npm install` at the repo root to fetch it.",
       { cause: err },
     );
   }
 
-  const scssPath = path.join(srcRoot, SCSS_REL);
+  const loadPaths = [
+    path.join(srcRoot, "_sass"),  // our customizations first
+    VENDOR_JTD_SASS,              // gem fallback
+  ];
 
-  let result;
+  const compileOpts = {
+    style: "expanded",
+    sourceMap: false,
+    loadPaths,
+  };
+
+  let lightResult, darkResult;
+  try {
+    lightResult = sass.compile(path.join(srcRoot, SCSS_LIGHT_REL), compileOpts);
+  } catch (err) {
+    console.warn(`scss (light): compilation failed:\n  ${err.message}`);
+    return { compiled: false, failed: true };
+  }
   try {
-    result = sass.compile(scssPath, {
-      style: "expanded",
-      sourceMap: false,
-      loadPaths: [
-        path.join(srcRoot, "_sass"),  // our customizations first
-        VENDOR_JTD_SASS,               // gem fallback
-      ],
-    });
+    darkResult = sass.compile(path.join(srcRoot, SCSS_DARK_REL), compileOpts);
   } catch (err) {
-    console.warn(`scss: compilation failed:\n  ${err.message}`);
+    console.warn(`scss (dark): compilation failed:\n  ${err.message}`);
     return { compiled: false, failed: true };
   }
 
-  return { compiled: true, css: result.css };
+  return { compiled: true, css: lightResult.css + "\n" + darkResult.css };
 }

builder/vendor/just-the-docs/README.md

@@ -9,7 +9,7 @@ everything here either feeds a compile step or is copied verbatim into
 
 | Path | Origin | Used by |
 |---|---|---|
-| `_sass/` | Gem's `_sass/` at v0.10.1, byte-for-byte (`base.scss`, `buttons.scss`, `code.scss`, `color_schemes/`, `custom/setup.scss` + the gem's empty `custom/custom.scss`, `modules.scss`, `support/`, `utilities/`, `vendor/normalize.scss/normalize.scss`, `vendor/OneLightJekyll/syntax.scss`, `vendor/OneDarkJekyll/syntax.scss`, ...). | [`builder/scss.mjs`](../../scss.mjs) compiles `docs/assets/css/just-the-docs-combined.scss` against these sources via Dart Sass; the load-path ordering puts `docs/_sass/` first so our `custom/custom.scss` shadows the gem's empty one. |
+| `_sass/` | Gem's `_sass/` at v0.10.1, byte-for-byte (`base.scss`, `buttons.scss`, `code.scss`, `color_schemes/`, `custom/setup.scss` + the gem's empty `custom/custom.scss`, `modules.scss`, `support/`, `utilities/`, `vendor/normalize.scss/normalize.scss`, ...). | [`builder/scss.mjs`](../../scss.mjs) compiles `docs/assets/css/just-the-docs-combined.scss` against these sources via Dart Sass; the load-path ordering puts `docs/_sass/` first so our `custom/custom.scss` shadows the gem's empty one. |
 | `assets/js/just-the-docs.js` | Gem's `assets/js/just-the-docs.js` at v0.10.1, **patched in tree**. | [`builder/write.mjs`](../../write.mjs)'s `copyTheme` copies it to `_site/assets/js/just-the-docs.js`; [`builder/offline.mjs`](../../offline.mjs) re-derives an offline-mode variant via [`acorn`](https://www.npmjs.com/package/acorn)-AST patching. |
 | `assets/js/vendor/lunr.min.js` | Gem's `assets/js/vendor/lunr.min.js` at v0.10.1, unmodified. | Copied verbatim by `copyTheme`. The search index that drives it is the in-process [`builder/search.mjs`](../../search.mjs) output (`assets/js/search-data.json`). |
 
@@ -55,24 +55,33 @@ Bumping the just-the-docs version is a deliberate operation. Procedure:
       builder/vendor/just-the-docs/assets/js/vendor/lunr.min.js
    ```
 
-3. Re-apply the copy-button patch in `assets/js/just-the-docs.js` (see
+3. Delete the unused vendor syntax themes that are not used by this site
+   (syntax highlighting comes from the twinBASIC IDE theme via
+   `builder/highlight-theme.mjs` instead):
+
+   ```sh
+   rm -rf builder/vendor/just-the-docs/_sass/vendor/OneLightJekyll
+   rm -rf builder/vendor/just-the-docs/_sass/vendor/OneDarkJekyll
+   ```
+
+4. Re-apply the copy-button patch in `assets/js/just-the-docs.js` (see
    above). Diffing against the previous vendored copy via `git diff` is
    the easiest way to spot what needs to come back.
 
-4. Inspect the entry point at `docs/assets/css/just-the-docs-combined.scss`
+5. Inspect the entry point at `docs/assets/css/just-the-docs-combined.scss`
    --- if the upstream `_includes/css/just-the-docs.scss.liquid` Liquid
    template changed shape between versions, the entry point needs to track
    it. The current entry point mirrors v0.10.1's: `support/support`,
    `custom/setup`, `color_schemes/<scheme>`, `modules`, plus the
    `callouts.scss.liquid` `div.opaque` rule and the `custom.scss.liquid`
    `@import "./custom/custom"`.
 
-5. Inspect the offline JS patcher in [`builder/offline.mjs`](../../offline.mjs)
+6. Inspect the offline JS patcher in [`builder/offline.mjs`](../../offline.mjs)
    --- `deriveOfflineJtdJs` slices in replacements for the upstream `navLink`
    and `initSearch` functions; if upstream rewrote either, the replacement
    bodies may need a refresh.
 
-6. Run `build.bat && check.bat`. The link check catches missing CSS / JS
+7. Run `build.bat && check.bat`. The link check catches missing CSS / JS
    references immediately; visual regressions are best caught by spinning
    up a preview and checking both light and dark modes.
 

builder/vendor/just-the-docs/_sass/base.scss

@@ -1,3 +1,5 @@
+@use "support/support" as *;
+
 // Base element style overrides
 // stylelint-disable selector-no-type, selector-max-type, selector-max-specificity, selector-max-id
 

builder/vendor/just-the-docs/_sass/buttons.scss

@@ -1,3 +1,6 @@
+@use "sass:color";
+@use "support/support" as *;
+
 // Buttons and things that look like buttons
 // stylelint-disable color-named
 
@@ -35,27 +38,27 @@
 
   &:hover,
   &.zeroclipboard-is-hover {
-    color: darken($link-color, 2%);
+    color: color.adjust($link-color, $lightness: -2%);
   }
 
   &:hover,
   &:active,
   &.zeroclipboard-is-hover,
   &.zeroclipboard-is-active {
     text-decoration: none;
-    background-color: darken($base-button-color, 1%);
+    background-color: color.adjust($base-button-color, $lightness: -1%);
   }
 
   &:active,
   &.selected,
   &.zeroclipboard-is-active {
-    background-color: darken($base-button-color, 3%);
+    background-color: color.adjust($base-button-color, $lightness: -3%);
     background-image: none;
     box-shadow: inset 0 2px 4px rgba(0, 0, 0, 0.15);
   }
 
   &.selected:hover {
-    background-color: darken(#dcdcdc, 5%);
+    background-color: color.adjust(#dcdcdc, $lightness: -5%);
   }
 
   &:disabled,
@@ -80,7 +83,7 @@
   &:active,
   &.zeroclipboard-is-hover,
   &.zeroclipboard-is-active {
-    color: darken($link-color, 4%);
+    color: color.adjust($link-color, $lightness: -4%);
     text-decoration: none;
     background-color: transparent;
     box-shadow: inset 0 0 0 3px $grey-lt-300;

builder/vendor/just-the-docs/_sass/code.scss

@@ -1,3 +1,5 @@
+@use "support/support" as *;
+
 // Code and syntax highlighting
 // stylelint-disable selector-no-qualifying-type, declaration-block-semicolon-newline-after,declaration-block-single-line-max-declarations, selector-no-type, selector-max-type, scss/comment-no-empty
 
@@ -226,19 +228,19 @@ code.language-mermaid {
   border: 0;
 }
 
-// Override OneDarkJekyll Colors for Code Blocks
+// Code block background and line-number colors
 .highlight,
 pre.highlight {
   background: $code-background-color; // Code Background
   // For Backwards Compatibility Before $code-linenumber-color was added
-  @if variable-exists(code-linenumber-color) {
+  @if $code-linenumber-color {
     color: $code-linenumber-color; // Code Line Numbers
   } @else {
     color: $body-text-color; // Code Line Numbers
   }
 }
 
-// Override OneDarkJekyll Colors for Code Blocks
+// Code block background and line-number colors
 .highlight pre {
   background: $code-background-color; // Code Background
 }

builder/vendor/just-the-docs/_sass/color_schemes/dark.scss

@@ -1,3 +1,5 @@
+@use "sass:color";
+
 $color-scheme: dark;
 $body-background-color: $grey-dk-300;
 $body-heading-color: $grey-lt-000;
@@ -7,12 +9,10 @@ $nav-child-link-color: $grey-dk-000;
 $sidebar-color: $grey-dk-300;
 $base-button-color: $grey-dk-250;
 $btn-primary-color: $blue-200;
-$code-background-color: #31343f; // OneDarkJekyll default for syntax-one-dark-vivid
-$code-linenumber-color: #dee2f7; // OneDarkJekyll .nf for syntax-one-dark-vivid
-$feedback-color: darken($sidebar-color, 3%);
+$code-background-color: #31343f;
+$code-linenumber-color: #dee2f7;
+$feedback-color: color.adjust($sidebar-color, $lightness: -3%);
 $table-background-color: $grey-dk-250;
 $search-background-color: $grey-dk-250;
 $search-result-preview-color: $grey-dk-000;
 $border-color: $grey-dk-200;
-
-@import "./vendor/OneDarkJekyll/syntax"; // this is the one-dark-vivid atom syntax theme

builder/vendor/just-the-docs/_sass/color_schemes/light.scss

@@ -1,3 +1,5 @@
+@use "sass:color";
+
 $color-scheme: light !default;
 $body-background-color: $white !default;
 $body-heading-color: $grey-dk-300 !default;
@@ -8,9 +10,7 @@ $sidebar-color: $grey-lt-000 !default;
 $base-button-color: #f7f7f7 !default;
 $btn-primary-color: $purple-100 !default;
 $code-background-color: $grey-lt-000 !default;
-$feedback-color: darken($sidebar-color, 3%) !default;
+$feedback-color: color.adjust($sidebar-color, $lightness: -3%) !default;
 $table-background-color: $white !default;
 $search-background-color: $white !default;
 $search-result-preview-color: $grey-dk-000 !default;
-
-@import "./vendor/OneLightJekyll/syntax";

builder/vendor/just-the-docs/_sass/content.scss

@@ -1,4 +1,5 @@
 @charset "UTF-8";
+@use "support/support" as *;
 
 // Styles for rendered markdown in the .main-content container
 // stylelint-disable selector-no-type, max-nesting-depth, selector-max-compound-selectors, selector-max-type, selector-max-specificity, selector-max-id

builder/vendor/just-the-docs/_sass/labels.scss

@@ -1,3 +1,5 @@
+@use "support/support" as *;
+
 // Labels (not the form kind)
 
 // this :not() prevents a style clash with Mermaid.js's

builder/vendor/just-the-docs/_sass/layout.scss

@@ -1,3 +1,5 @@
+@use "support/support" as *;
+
 // The basic two column layout
 
 .side-bar {
@@ -144,7 +146,7 @@
   }
 }
 
-@if variable-exists(logo) {
+@if $logo {
   .site-logo {
     width: 100%;
     height: 100%;

builder/vendor/just-the-docs/_sass/modules.scss

@@ -1,17 +1,21 @@
-// Import external dependencies
-@import "./vendor/normalize.scss/normalize";
+// Forward support so the entry point can configure theme variables through
+// this aggregator (e.g. @use "modules" with ($logo: "/favicon.png")).
+@forward "./support/support";
+
+// External dependency
+@use "./vendor/normalize.scss/normalize";
 
 // Modules
-@import "./base";
-@import "./layout";
-@import "./content";
-@import "./navigation";
-@import "./typography";
-@import "./labels";
-@import "./buttons";
-@import "./search";
-@import "./tables";
-@import "./code";
-@import "./utilities/utilities";
-@import "./print";
-@import "./skiptomain";
+@use "./base";
+@use "./layout";
+@use "./content";
+@use "./navigation";
+@use "./typography";
+@use "./labels";
+@use "./buttons";
+@use "./search";
+@use "./tables";
+@use "./code";
+@use "./utilities/utilities";
+@use "./print";
+@use "./skiptomain";

builder/vendor/just-the-docs/_sass/navigation.scss

@@ -1,3 +1,5 @@
+@use "support/support" as *;
+
 // Main nav, breadcrumb, etc...
 // stylelint-disable selector-no-type, max-nesting-depth, selector-max-compound-selectors, selector-max-type, selector-max-specificity
 

builder/vendor/just-the-docs/_sass/print.scss

@@ -1,3 +1,5 @@
+@use "support/support" as *;
+
 // stylelint-disable selector-max-specificity, selector-max-id, selector-max-type, selector-no-qualifying-type
 
 @media print {

builder/vendor/just-the-docs/_sass/search.scss

@@ -1,3 +1,5 @@
+@use "support/support" as *;
+
 // Search input and autocomplete
 
 .search {

builder/vendor/just-the-docs/_sass/skiptomain.scss

@@ -1,3 +1,5 @@
+@use "support/support" as *;
+
 // Skipnav
 // Skip to main content
 

builder/vendor/just-the-docs/_sass/support/_variables.scss

@@ -1,3 +1,6 @@
+@use "sass:map";
+@use "sass:color";
+
 // Typography
 
 // prettier-ignore
@@ -75,16 +78,16 @@ $spacers: (
   sp-9: $spacing-unit * 3.5,
   sp-10: $spacing-unit * 4,
 ) !default;
-$sp-1: map-get($spacers, sp-1) !default; // 0.25 rem == 4px
-$sp-2: map-get($spacers, sp-2) !default; // 0.5  rem == 8px
-$sp-3: map-get($spacers, sp-3) !default; // 0.75 rem == 12px
-$sp-4: map-get($spacers, sp-4) !default; // 1    rem == 16px
-$sp-5: map-get($spacers, sp-5) !default; // 1.5  rem == 24px
-$sp-6: map-get($spacers, sp-6) !default; // 2    rem == 32px
-$sp-7: map-get($spacers, sp-7) !default; // 2.5  rem == 40px
-$sp-8: map-get($spacers, sp-8) !default; // 3    rem == 48px
-$sp-9: map-get($spacers, sp-9) !default; // 3.5  rem == 56px
-$sp-10: map-get($spacers, sp-10) !default; // 4  rem == 64px
+$sp-1: map.get($spacers, sp-1) !default; // 0.25 rem == 4px
+$sp-2: map.get($spacers, sp-2) !default; // 0.5  rem == 8px
+$sp-3: map.get($spacers, sp-3) !default; // 0.75 rem == 12px
+$sp-4: map.get($spacers, sp-4) !default; // 1    rem == 16px
+$sp-5: map.get($spacers, sp-5) !default; // 1.5  rem == 24px
+$sp-6: map.get($spacers, sp-6) !default; // 2    rem == 32px
+$sp-7: map.get($spacers, sp-7) !default; // 2.5  rem == 40px
+$sp-8: map.get($spacers, sp-8) !default; // 3    rem == 48px
+$sp-9: map.get($spacers, sp-9) !default; // 3.5  rem == 56px
+$sp-10: map.get($spacers, sp-10) !default; // 4  rem == 64px
 
 // Borders
 
@@ -115,3 +118,22 @@ $media-queries: (
   lg: $content-width + $nav-width,
   xl: 87.5rem,
 ) !default;
+
+// Theme variables -- light defaults (overridden per-load for the dark theme)
+
+$logo: null !default;
+$color-scheme: light !default;
+$body-background-color: $white !default;
+$body-heading-color: $grey-dk-300 !default;
+$body-text-color: $grey-dk-100 !default;
+$link-color: $purple-000 !default;
+$nav-child-link-color: $grey-dk-100 !default;
+$sidebar-color: $grey-lt-000 !default;
+$base-button-color: #f7f7f7 !default;
+$btn-primary-color: $purple-100 !default;
+$code-background-color: $grey-lt-000 !default;
+$code-linenumber-color: null !default;
+$feedback-color: color.adjust($sidebar-color, $lightness: -3%) !default;
+$table-background-color: $white !default;
+$search-background-color: $white !default;
+$search-result-preview-color: $grey-dk-000 !default;