jekyll-theme-zer0 0.15.2 → 0.17.0

data/_plugins/preview_image_generator.rb

@@ -33,6 +33,8 @@ module Jekyll
       'style' => 'retro pixel art, 8-bit video game aesthetic, vibrant colors, nostalgic, clean pixel graphics',
       'style_modifiers' => 'pixelated, retro gaming style, CRT screen glow effect, limited color palette',
       'output_dir' => 'assets/images/previews',
+      'assets_prefix' => '/assets',
+      'auto_prefix' => true,
       'auto_generate' => false,
       'collections' => ['posts', 'docs', 'quickstart']
     }.freeze
@@ -52,18 +54,37 @@ module Jekyll
       site = doc.site
       config = self.config(site)
       
+      # Normalize the preview path using assets_prefix
+      normalized_preview = normalize_preview_path(preview, config)
+      
       # Build the full path
-      preview_path = if preview.start_with?('/')
-                       File.join(site.source, preview)
-                     elsif preview.start_with?('http')
+      preview_path = if normalized_preview.start_with?('/')
+                       File.join(site.source, normalized_preview.sub(/^\//, ''))
+                     elsif normalized_preview.start_with?('http')
                        return true  # External URL, assume it exists
                      else
-                       File.join(site.source, config['output_dir'], preview)
+                       File.join(site.source, config['output_dir'], normalized_preview)
                      end
       
       File.exist?(preview_path)
     end
 
+    # Normalize a preview path by adding assets_prefix if needed
+    def self.normalize_preview_path(preview, config)
+      return preview if preview.nil? || preview.to_s.strip.empty?
+      return preview if preview.start_with?('http')
+      
+      assets_prefix = config['assets_prefix'] || '/assets'
+      auto_prefix = config['auto_prefix'] != false  # Default to true
+      
+      # If auto_prefix is enabled and path doesn't already contain assets_prefix
+      if auto_prefix && !preview.include?(assets_prefix)
+        "#{assets_prefix}#{preview}"
+      else
+        preview
+      end
+    end
+
     # Get the preview image path for a document
     def self.preview_path(doc)
       preview = doc.data['preview']
@@ -72,11 +93,11 @@ module Jekyll
       site = doc.site
       config = self.config(site)
       
-      # If it's already a full path or URL, return as-is
-      return preview if preview.start_with?('/') || preview.start_with?('http')
+      # If it's an external URL, return as-is
+      return preview if preview.start_with?('http')
       
-      # Build relative path from output_dir
-      "#{config['output_dir']}/#{preview}"
+      # Normalize path with assets_prefix
+      normalize_preview_path(preview, config)
     end
 
     # Get list of documents missing preview images

data/_sass/core/_nav-tree.scss

@@ -0,0 +1,145 @@
+// ===================================================================
+// NAV TREE - Sidebar Navigation Tree Styles
+// ===================================================================
+//
+// File: _nav-tree.scss
+// Path: _sass/core/_nav-tree.scss
+// Purpose: Styles for the hierarchical navigation tree component
+//
+// Features:
+// - Collapsible tree nodes with smooth transitions
+// - Active state highlighting
+// - Hover effects
+// - Chevron rotation on expand/collapse
+// - Nested indentation
+//
+// ===================================================================
+
+// Navigation Tree Container
+.nav-tree {
+  font-size: 0.875rem;
+}
+
+.nav-tree-root {
+  margin: 0;
+  padding: 0;
+}
+
+// Navigation Tree Items
+.nav-tree-item {
+  margin-bottom: 0.125rem;
+  
+  // Nested items get additional indentation via ps-3 class
+}
+
+// Navigation Tree Links
+.nav-tree-link {
+  color: var(--bs-body-color);
+  transition: color 0.15s ease-in-out, background-color 0.15s ease-in-out;
+  
+  &:hover {
+    color: var(--bs-primary);
+    background-color: var(--bs-tertiary-bg);
+  }
+  
+  &.active {
+    color: var(--bs-primary);
+    background-color: var(--bs-primary-bg-subtle);
+    font-weight: 500;
+  }
+}
+
+// Navigation Tree Text (non-link items)
+.nav-tree-text {
+  color: var(--bs-secondary-color);
+}
+
+// Navigation Tree Toggle Buttons
+.nav-tree-toggle {
+  color: var(--bs-body-color);
+  text-decoration: none;
+  border: none;
+  background: transparent;
+  transition: color 0.15s ease-in-out;
+  
+  &:hover {
+    color: var(--bs-primary);
+  }
+  
+  &:focus {
+    outline: none;
+    box-shadow: 0 0 0 0.25rem rgba(var(--bs-primary-rgb), 0.25);
+  }
+  
+  // Chevron rotation
+  .bi-chevron-down,
+  .nav-tree-chevron {
+    transition: transform 0.2s ease-in-out;
+  }
+  
+  &.collapsed {
+    .bi-chevron-down,
+    .nav-tree-chevron {
+      transform: rotate(-90deg);
+    }
+  }
+}
+
+// Children container
+.nav-tree-children {
+  margin-top: 0.25rem;
+  border-left: 1px solid var(--bs-border-color);
+  margin-left: 0.5rem;
+  padding-left: 0.75rem;
+}
+
+// Collapse animation
+.nav-tree .collapse {
+  transition: height 0.2s ease-in-out;
+}
+
+// Depth-based styling
+.nav-tree-item[data-depth="0"] > .nav-tree-link,
+.nav-tree-item[data-depth="0"] > div > .nav-tree-link,
+.nav-tree-item[data-depth="0"] > .nav-tree-toggle {
+  font-weight: 500;
+}
+
+.nav-tree-item[data-depth="1"] > .nav-tree-link,
+.nav-tree-item[data-depth="1"] > div > .nav-tree-link {
+  font-weight: normal;
+}
+
+.nav-tree-item[data-depth="2"] > .nav-tree-link,
+.nav-tree-item[data-depth="2"] > div > .nav-tree-link {
+  font-size: 0.8125rem;
+  color: var(--bs-secondary-color);
+  
+  &.active {
+    color: var(--bs-primary);
+  }
+}
+
+// Keyboard navigation focus state
+.keyboard-nav .nav-tree-link:focus,
+.keyboard-nav .nav-tree-toggle:focus {
+  outline: 2px solid var(--bs-primary);
+  outline-offset: 2px;
+}
+
+// Dark mode adjustments
+[data-bs-theme="dark"] {
+  .nav-tree-link {
+    &:hover {
+      background-color: rgba(255, 255, 255, 0.05);
+    }
+    
+    &.active {
+      background-color: rgba(var(--bs-primary-rgb), 0.15);
+    }
+  }
+  
+  .nav-tree-children {
+    border-left-color: var(--bs-border-color);
+  }
+}

data/_sass/custom.scss

@@ -5,6 +5,9 @@
 // Import notebook-specific styles
 @import "notebooks";
 
+// Import navigation tree styles
+@import "core/nav-tree";
+
 html, body {
     max-width: 100%;
     // overflow-x: hidden;

data/assets/js/modules/navigation/config.js

@@ -0,0 +1,149 @@
+/**
+ * ===================================================================
+ * NAVIGATION CONFIG - Shared Configuration for Navigation Modules
+ * ===================================================================
+ * 
+ * File: config.js
+ * Path: assets/js/modules/navigation/config.js
+ * Purpose: Centralized configuration for all navigation modules
+ * 
+ * Usage:
+ *   import { config } from './config.js';
+ *   const toc = document.querySelector(config.selectors.toc);
+ * 
+ * ===================================================================
+ */
+
+export const config = {
+    // ===================================================================
+    // DOM SELECTORS
+    // ===================================================================
+    selectors: {
+        // Table of Contents
+        toc: '#TableOfContents',
+        tocLinks: '#TableOfContents a',
+        tocContainer: '.bd-toc .offcanvas-body',
+        
+        // Sidebars
+        leftSidebar: '#bdSidebar',
+        rightSidebar: '#tocContents',
+        
+        // Content areas
+        mainContent: '.bd-content',
+        
+        // Navigation elements
+        navTree: '.nav-tree',
+        navTreeToggle: '[data-nav-toggle]',
+        
+        // Offcanvas
+        offcanvas: '.offcanvas'
+    },
+
+    // ===================================================================
+    // SCROLL SPY SETTINGS
+    // ===================================================================
+    scrollSpy: {
+        // Root margin for Intersection Observer
+        // Negative values account for fixed headers
+        rootMargin: '-80px 0px -80px 0px',
+        
+        // Intersection threshold levels
+        threshold: [0, 0.25, 0.5, 0.75, 1]
+    },
+
+    // ===================================================================
+    // SMOOTH SCROLL SETTINGS
+    // ===================================================================
+    smoothScroll: {
+        // Offset for fixed headers when scrolling to anchor
+        offset: 80,
+        
+        // Scroll behavior
+        behavior: 'smooth'
+    },
+
+    // ===================================================================
+    // KEYBOARD SHORTCUTS
+    // ===================================================================
+    keyboard: {
+        // Enable/disable keyboard shortcuts
+        enabled: true,
+        
+        // Key mappings
+        keys: {
+            previousSection: '[',
+            nextSection: ']',
+            search: '/',
+            toggleSidebar: 'b',
+            toggleToc: 't'
+        }
+    },
+
+    // ===================================================================
+    // SWIPE GESTURES
+    // ===================================================================
+    gestures: {
+        // Enable/disable swipe gestures
+        enabled: true,
+        
+        // Minimum distance (px) for swipe to register
+        threshold: 50,
+        
+        // Edge detection zone (px) for sidebar swipes
+        edgeZone: 50
+    },
+
+    // ===================================================================
+    // SIDEBAR STATE PERSISTENCE
+    // ===================================================================
+    state: {
+        // localStorage key prefix
+        storagePrefix: 'zer0-nav-',
+        
+        // Keys for different state values
+        keys: {
+            expandedNodes: 'expanded-nodes',
+            sidebarOpen: 'sidebar-open',
+            tocOpen: 'toc-open'
+        }
+    },
+
+    // ===================================================================
+    // DEBOUNCE/THROTTLE TIMINGS
+    // ===================================================================
+    timing: {
+        debounceDelay: 100,
+        scrollDebounce: 50
+    },
+
+    // ===================================================================
+    // BREAKPOINTS (match Bootstrap 5)
+    // ===================================================================
+    breakpoints: {
+        sm: 576,
+        md: 768,
+        lg: 992,
+        xl: 1200,
+        xxl: 1400
+    }
+};
+
+/**
+ * Check if viewport is below a breakpoint
+ * @param {string} breakpoint - Breakpoint name (sm, md, lg, xl, xxl)
+ * @returns {boolean}
+ */
+export function isBelowBreakpoint(breakpoint) {
+    return window.innerWidth < config.breakpoints[breakpoint];
+}
+
+/**
+ * Check if viewport is at or above a breakpoint
+ * @param {string} breakpoint - Breakpoint name (sm, md, lg, xl, xxl)
+ * @returns {boolean}
+ */
+export function isAtOrAboveBreakpoint(breakpoint) {
+    return window.innerWidth >= config.breakpoints[breakpoint];
+}
+
+export default config;

data/assets/js/modules/navigation/focus.js

@@ -0,0 +1,189 @@
+/**
+ * ===================================================================
+ * FOCUS MANAGER - Accessibility Enhancements
+ * ===================================================================
+ * 
+ * File: focus.js
+ * Path: assets/js/modules/navigation/focus.js
+ * Purpose: Focus management for accessibility in navigation components
+ * 
+ * Features:
+ * - Returns focus to trigger element when offcanvas closes
+ * - Manages focus trap in modal/offcanvas contexts
+ * - Provides focus ring styling hooks
+ * 
+ * Usage:
+ *   import { FocusManager } from './focus.js';
+ *   const focus = new FocusManager();
+ * 
+ * ===================================================================
+ */
+
+import { config } from './config.js';
+
+/**
+ * Get all elements safely
+ * @param {string} selector - CSS selector
+ * @returns {NodeList}
+ */
+function getElements(selector) {
+    try {
+        return document.querySelectorAll(selector);
+    } catch (error) {
+        return [];
+    }
+}
+
+export class FocusManager {
+    constructor() {
+        this._boundHandleHidden = this._handleOffcanvasHidden.bind(this);
+        this._init();
+    }
+
+    /**
+     * Initialize focus management
+     * @private
+     */
+    _init() {
+        // Handle focus return when offcanvas closes
+        const offcanvasElements = getElements(config.selectors.offcanvas);
+        
+        offcanvasElements.forEach(offcanvas => {
+            offcanvas.addEventListener('hidden.bs.offcanvas', this._boundHandleHidden);
+        });
+
+        // Add focus-visible polyfill behavior
+        this._setupFocusVisible();
+
+        console.log(`FocusManager: Initialized with ${offcanvasElements.length} offcanvas elements`);
+    }
+
+    /**
+     * Handle offcanvas hidden event - return focus to trigger
+     * @private
+     * @param {Event} event
+     */
+    _handleOffcanvasHidden(event) {
+        const offcanvas = event.target;
+        this.returnFocus(offcanvas);
+    }
+
+    /**
+     * Return focus to the trigger element that opened an offcanvas
+     * @param {Element} offcanvas - The offcanvas element
+     */
+    returnFocus(offcanvas) {
+        const triggerId = offcanvas.id;
+        
+        // Find the trigger button that opened this offcanvas
+        const trigger = document.querySelector(
+            `[data-bs-target="#${triggerId}"], [href="#${triggerId}"]`
+        );
+        
+        if (trigger) {
+            // Small delay to ensure offcanvas animation completes
+            requestAnimationFrame(() => {
+                trigger.focus();
+            });
+        }
+    }
+
+    /**
+     * Setup focus-visible behavior for keyboard users
+     * @private
+     */
+    _setupFocusVisible() {
+        // Add class to body when user is navigating with keyboard
+        let hadKeyboardEvent = false;
+        
+        document.addEventListener('keydown', (e) => {
+            if (e.key === 'Tab') {
+                hadKeyboardEvent = true;
+                document.body.classList.add('keyboard-nav');
+            }
+        });
+
+        document.addEventListener('mousedown', () => {
+            hadKeyboardEvent = false;
+            document.body.classList.remove('keyboard-nav');
+        });
+    }
+
+    /**
+     * Focus the first focusable element within a container
+     * @param {Element} container
+     */
+    focusFirst(container) {
+        const focusable = container.querySelector(
+            'button, [href], input, select, textarea, [tabindex]:not([tabindex="-1"])'
+        );
+        if (focusable) {
+            focusable.focus();
+        }
+    }
+
+    /**
+     * Focus the last focusable element within a container
+     * @param {Element} container
+     */
+    focusLast(container) {
+        const focusables = container.querySelectorAll(
+            'button, [href], input, select, textarea, [tabindex]:not([tabindex="-1"])'
+        );
+        if (focusables.length > 0) {
+            focusables[focusables.length - 1].focus();
+        }
+    }
+
+    /**
+     * Trap focus within a container (for modals/offcanvas)
+     * @param {Element} container
+     * @returns {Function} Cleanup function to remove trap
+     */
+    trapFocus(container) {
+        const focusableElements = container.querySelectorAll(
+            'button, [href], input, select, textarea, [tabindex]:not([tabindex="-1"])'
+        );
+        
+        const firstFocusable = focusableElements[0];
+        const lastFocusable = focusableElements[focusableElements.length - 1];
+
+        const handleKeydown = (e) => {
+            if (e.key !== 'Tab') return;
+
+            if (e.shiftKey) {
+                // Shift + Tab
+                if (document.activeElement === firstFocusable) {
+                    e.preventDefault();
+                    lastFocusable.focus();
+                }
+            } else {
+                // Tab
+                if (document.activeElement === lastFocusable) {
+                    e.preventDefault();
+                    firstFocusable.focus();
+                }
+            }
+        };
+
+        container.addEventListener('keydown', handleKeydown);
+
+        // Return cleanup function
+        return () => {
+            container.removeEventListener('keydown', handleKeydown);
+        };
+    }
+
+    /**
+     * Cleanup event listeners
+     */
+    destroy() {
+        const offcanvasElements = getElements(config.selectors.offcanvas);
+        offcanvasElements.forEach(offcanvas => {
+            offcanvas.removeEventListener('hidden.bs.offcanvas', this._boundHandleHidden);
+        });
+        console.log('FocusManager: Destroyed');
+    }
+}
+
+export default FocusManager;