feat : Add JSON‑driven background image support (#316)

* Add background JSON support

- Load background map from JSON
- Store user preference
- Update DOMContentLoaded handler

* Refactor background-switcher.js

- Replace hardcoded BG_MAP with empty object
- Convert loadBackgroundMap to async/await
- Simplify DOMContentLoaded listener using async function
- Improve readability and eliminate data duplication

* Update background-switcher.js path and warning

- Use DOCUMENTATION_OPTIONS.URL_ROOT for robust JSON path
- Clarify warning when JSON fails to load

* Fix pre-commit workflow

- Remove duplicate pre-commit execution
- Keep only standard all-files check
- Fix CI failure caused by redundant hook stages

* Revert: Restore manual hook stage test

- Keep both pre-commit execution stages
- Standard hooks and manual hooks both needed
- Rename second step for clarity

* Apply prettier formatting

- Format background-switcher.js
- Format backgrounds.json
- Ensure code style consistency

* refactor: improve separation of concerns in loadBackgroundMap

- loadBackgroundMap now returns data (or null on failure) instead of
  directly modifying the module-level BG_MAP variable
- Added robust data validation in DOMContentLoaded handler to ensure
  the loaded JSON is a valid object before populating BG_MAP
- Addresses code review feedback for better maintainability and testability

* refactor: use Object.prototype.toString for robust type checking

- Replace multi-condition object check with more idiomatic approach
- Object.prototype.toString.call() handles edge cases like typeof null
- Addresses code review feedback for cleaner validation logic

Author: NssGourav

.github/workflows/pre-commit.yml

@@ -52,5 +52,5 @@ jobs:
 
       - name: 🏃🏻‍♂️‍➡️ Run pre-commit
         run: pre-commit run --color=always --all-files
-      - name: 🏃🏻‍♂️‍➡️ Run pre-commit
+      - name: 🏃🏻‍♂️‍➡️ Run pre-commit (manual hooks)
         run: pre-commit run --color=always --all-files --hook-stage manual

doc/source/_static/data/backgrounds.json

@@ -0,0 +1,18 @@
+{
+  "shades-games-club": "the-big-issue",
+  "first-event": "first-event-second-game",
+  "second-event": "second-event",
+  "third-event": "third-event-beers-in-play",
+  "fourth-event": "fourth-event",
+  "fifth-event": "fifth-event",
+  "sixth-event": "sixth-event",
+  "catan": "catan",
+  "chess": "chess",
+  "c-o-o-l-chess": "cool-chess",
+  "harmegedo": "harmegedo",
+  "history-of-64-shades": "history",
+  "quaternity": "quaternity-wooden-set",
+  "the-first-challenger": "first-event-first-game",
+  "top-pitfalls": "top-pitfalls",
+  "uno-show-em-no-mercy": "uno-show-em-no-mercy"
+}

doc/source/_static/js/background-switcher.js

@@ -1,25 +1,33 @@
-// Map page IDs to their corresponding background image URLs
-const BG_MAP = {
-  'shades-games-club': 'the-big-issue',
-  'first-event': 'first-event-second-game',
-  'second-event': 'second-event',
-  'third-event': 'third-event-beers-in-play',
-  'fourth-event': 'fourth-event',
-  'fifth-event': 'fifth-event',
-  'sixth-event': 'sixth-event',
-  catan: 'catan',
-  chess: 'chess',
-  'c-o-o-l-chess': 'cool-chess',
-  harmegedo: 'harmegedo',
-  'history-of-64-shades': 'history',
-  quaternity: 'quaternity-wooden-set',
-  'the-first-challenger': 'first-event-first-game',
-  'top-pitfalls': 'top-pitfalls',
-  'uno-show-em-no-mercy': 'uno-show-em-no-mercy',
-};
+const BG_MAP = {};
 
 const BACKGROUND_KEY = 'sphinx_background_preference';
 
+/**
+ * Load the background map from a JSON file using async/await.
+ */
+async function loadBackgroundMap() {
+  const jsonUrl = (window.DOCUMENTATION_OPTIONS?.URL_ROOT || '') + '_static/data/backgrounds.json';
+  try {
+    const response = await fetch(jsonUrl);
+    if (!response.ok) {
+      console.warn('Failed to load background map JSON; background images will be disabled.');
+      return null;
+    }
+    return await response.json();
+  } catch (err) {
+    console.error('Error loading background map JSON:', err);
+    return null;
+  }
+}
+
+/**
+ * Load user's background preference and apply it.
+ */
+function loadBackgroundPreference() {
+  const storedBackground = localStorage.getItem(BACKGROUND_KEY) || 'on';
+  window.setBackground(storedBackground);
+}
+
 /**
  * Public function to turn the background image on or off.
  * Defined globally so the HTML `href="javascript:setBackground(...)` works.
@@ -62,12 +70,16 @@ window.setBackground = function (state) {
   updateBackgroundLinks(state);
 };
 
-function loadBackgroundPreference() {
-  const storedBackground = localStorage.getItem(BACKGROUND_KEY) || 'on';
-  window.setBackground(storedBackground); // Use the global function
-}
+// Wait for the document to fully load, load the map, then apply preference.
 
-// Wait for the document to fully load and load background preference
-document.addEventListener('DOMContentLoaded', function () {
+document.addEventListener('DOMContentLoaded', async function () {
+  const data = await loadBackgroundMap();
+  if (Object.prototype.toString.call(data) === '[object Object]') {
+    Object.assign(BG_MAP, data);
+  } else if (data) {
+    console.warn(
+      'Loaded background map from JSON is not a valid object; background images will be disabled.',
+    );
+  }
   loadBackgroundPreference();
 });