jekyll-theme-zer0 0.15.2 → 0.17.0

data/scripts/lib/preview_generator.py

@@ -101,6 +101,8 @@ class PreviewGenerator:
         output_dir: str = "assets/images/previews",
         image_style: str = "digital art, professional blog illustration",
         image_size: str = "1024x1024",
+        assets_prefix: str = "/assets",
+        auto_prefix: bool = True,
         dry_run: bool = False,
         verbose: bool = False,
         force: bool = False,
@@ -110,6 +112,8 @@ class PreviewGenerator:
         self.output_dir = project_root / output_dir
         self.image_style = image_style
         self.image_size = image_size
+        self.assets_prefix = assets_prefix
+        self.auto_prefix = auto_prefix
         self.dry_run = dry_run
         self.verbose = verbose
         self.force = force
@@ -129,6 +133,27 @@ class PreviewGenerator:
         if self.verbose:
             log(msg, "debug")
     
+    def normalize_preview_path(self, preview_path: Optional[str]) -> Optional[str]:
+        """Normalize a preview path by adding assets_prefix if needed.
+        
+        This allows users to omit the /assets/ prefix in frontmatter:
+        - /images/previews/my-image.png -> /assets/images/previews/my-image.png
+        - /assets/images/previews/my-image.png -> unchanged
+        - https://example.com/image.png -> unchanged (external URL)
+        """
+        if not preview_path:
+            return preview_path
+        
+        # External URLs pass through unchanged
+        if preview_path.startswith('http://') or preview_path.startswith('https://'):
+            return preview_path
+        
+        # If auto_prefix is enabled and path doesn't contain assets_prefix
+        if self.auto_prefix and self.assets_prefix not in preview_path:
+            return f"{self.assets_prefix}{preview_path}"
+        
+        return preview_path
+    
     def parse_front_matter(self, file_path: Path) -> Optional[ContentFile]:
         """Parse front matter and content from a markdown file."""
         try:
@@ -178,19 +203,19 @@ class PreviewGenerator:
         if not preview_path:
             return False
         
+        # Normalize the path first (adds assets_prefix if needed)
+        normalized_path = self.normalize_preview_path(preview_path)
+        if not normalized_path:
+            return False
+        
         # Handle absolute and relative paths
-        clean_path = preview_path.lstrip('/')
+        clean_path = normalized_path.lstrip('/')
         
         # Check direct path
         full_path = self.project_root / clean_path
         if full_path.exists():
             return True
         
-        # Check in assets directory
-        assets_path = self.project_root / 'assets' / clean_path
-        if assets_path.exists():
-            return True
-        
         return False
     
     def generate_prompt(self, content: ContentFile) -> str:
@@ -395,12 +420,131 @@ class PreviewGenerator:
                 prompt_used=prompt,
             )
     
+    def generate_image_xai(self, prompt: str, output_path: Path) -> GenerationResult:
+        """Generate image using xAI Grok API."""
+        if not HAS_REQUESTS:
+            return GenerationResult(
+                success=False,
+                image_path=None,
+                preview_url=None,
+                error="requests package not installed. Run: pip install requests",
+                prompt_used=prompt,
+            )
+        
+        api_key = os.environ.get('XAI_API_KEY')
+        if not api_key:
+            return GenerationResult(
+                success=False,
+                image_path=None,
+                preview_url=None,
+                error="XAI_API_KEY environment variable not set",
+                prompt_used=prompt,
+            )
+        
+        try:
+            # xAI has a max prompt length of 1024 characters
+            truncated_prompt = prompt[:1000] if len(prompt) > 1000 else prompt
+            self.debug(f"Generating with xAI Grok, prompt: {truncated_prompt[:200]}...")
+            
+            # xAI uses OpenAI-compatible API format
+            response = requests.post(
+                "https://api.x.ai/v1/images/generations",
+                headers={
+                    "Authorization": f"Bearer {api_key}",
+                    "Content-Type": "application/json",
+                },
+                json={
+                    "model": "grok-2-image",
+                    "prompt": truncated_prompt,
+                    "n": 1,
+                },
+                timeout=120,  # 2 minute timeout for image generation
+            )
+            response.raise_for_status()
+            
+            data = response.json()
+            
+            # xAI returns base64-encoded images
+            if 'data' not in data or not data['data']:
+                return GenerationResult(
+                    success=False,
+                    image_path=None,
+                    preview_url=None,
+                    error="No image data in response",
+                    prompt_used=prompt,
+                )
+            
+            image_data = data['data'][0]
+            
+            # Check if it's a URL or base64
+            if 'url' in image_data:
+                # Download from URL
+                img_response = requests.get(image_data['url'], timeout=60)
+                img_response.raise_for_status()
+                output_path.write_bytes(img_response.content)
+            elif 'b64_json' in image_data:
+                # Decode base64
+                import base64
+                image_bytes = base64.b64decode(image_data['b64_json'])
+                output_path.write_bytes(image_bytes)
+            else:
+                return GenerationResult(
+                    success=False,
+                    image_path=None,
+                    preview_url=None,
+                    error="Unexpected response format from xAI",
+                    prompt_used=prompt,
+                )
+            
+            return GenerationResult(
+                success=True,
+                image_path=str(output_path),
+                preview_url=str(output_path.relative_to(self.project_root)),
+                error=None,
+                prompt_used=prompt,
+            )
+            
+        except requests.exceptions.HTTPError as e:
+            error_msg = str(e)
+            try:
+                error_data = e.response.json()
+                self.debug(f"xAI error response: {error_data}")
+                if 'error' in error_data:
+                    error_msg = error_data['error'].get('message', str(error_data['error']))
+                elif 'detail' in error_data:
+                    error_msg = str(error_data['detail'])
+                else:
+                    error_msg = str(error_data)
+            except:
+                # Try to get raw text
+                try:
+                    error_msg = e.response.text[:500]
+                except:
+                    pass
+            return GenerationResult(
+                success=False,
+                image_path=None,
+                preview_url=None,
+                error=f"xAI API error: {error_msg}",
+                prompt_used=prompt,
+            )
+        except Exception as e:
+            return GenerationResult(
+                success=False,
+                image_path=None,
+                preview_url=None,
+                error=str(e),
+                prompt_used=prompt,
+            )
+    
     def generate_image(self, prompt: str, output_path: Path) -> GenerationResult:
         """Generate image using configured provider."""
         if self.provider == "openai":
             return self.generate_image_openai(prompt, output_path)
         elif self.provider == "stability":
             return self.generate_image_stability(prompt, output_path)
+        elif self.provider == "xai":
+            return self.generate_image_xai(prompt, output_path)
         else:
             return GenerationResult(
                 success=False,
@@ -559,9 +703,9 @@ def main():
     )
     parser.add_argument(
         '-p', '--provider',
-        choices=['openai', 'stability'],
+        choices=['openai', 'stability', 'xai'],
         default='openai',
-        help="AI provider for image generation"
+        help="AI provider for image generation (openai, stability, xai)"
     )
     parser.add_argument(
         '-d', '--dry-run',
@@ -593,6 +737,16 @@ def main():
         default='digital art, professional blog illustration, clean design',
         help="Image style prompt"
     )
+    parser.add_argument(
+        '--assets-prefix',
+        default='/assets',
+        help="Prefix to prepend to relative preview paths (default: /assets)"
+    )
+    parser.add_argument(
+        '--no-auto-prefix',
+        action='store_true',
+        help="Disable automatic assets prefix prepending"
+    )
     
     args = parser.parse_args()
     
@@ -606,6 +760,8 @@ def main():
         provider=args.provider,
         output_dir=args.output_dir,
         image_style=args.style,
+        assets_prefix=args.assets_prefix,
+        auto_prefix=not args.no_auto_prefix,
         dry_run=args.dry_run,
         verbose=args.verbose,
         force=args.force,

data/scripts/migrate-nav-modes.sh

@@ -0,0 +1,146 @@
+#!/bin/bash
+# ===================================================================
+# MIGRATE NAV MODES - Update Front Matter Navigation Values
+# ===================================================================
+#
+# File: migrate-nav-modes.sh
+# Path: scripts/migrate-nav-modes.sh
+# Purpose: Update front matter nav values from old to new modes
+#
+# Migration Map:
+#   dynamic    → auto
+#   searchCats → categories
+#   docs       → tree
+#   about      → tree
+#   quickstart → tree
+#   main       → tree
+#
+# Usage:
+#   ./scripts/migrate-nav-modes.sh           # Dry run (preview changes)
+#   ./scripts/migrate-nav-modes.sh --apply   # Apply changes
+#
+# ===================================================================
+
+set -eo pipefail
+
+# Colors for output
+RED='\033[0;31m'
+GREEN='\033[0;32m'
+YELLOW='\033[1;33m'
+BLUE='\033[0;34m'
+NC='\033[0m' # No Color
+
+# Script configuration
+PAGES_DIR="pages"
+DRY_RUN=true
+
+# Parse arguments
+if [[ "${1:-}" == "--apply" ]]; then
+    DRY_RUN=false
+fi
+
+echo -e "${BLUE}═══════════════════════════════════════════════════════════════${NC}"
+echo -e "${BLUE}  Navigation Mode Migration Script${NC}"
+echo -e "${BLUE}═══════════════════════════════════════════════════════════════${NC}"
+echo ""
+
+if $DRY_RUN; then
+    echo -e "${YELLOW}Running in DRY RUN mode. No files will be modified.${NC}"
+    echo -e "${YELLOW}Use --apply to make actual changes.${NC}"
+else
+    echo -e "${RED}Running in APPLY mode. Files will be modified.${NC}"
+fi
+echo ""
+
+# Migration patterns (old → new)
+# Using simple arrays instead of associative arrays for compatibility
+OLD_PATTERNS=("nav: dynamic" "nav: searchCats")
+NEW_PATTERNS=("nav: auto" "nav: categories")
+
+# Files that explicitly set nav values (not inherited from _config.yml)
+EXPLICIT_NAV_PATTERNS=(
+    "nav: dynamic"
+    "nav: searchCats"
+    "nav: docs"
+    "nav: about"
+    "nav: quickstart"
+    "nav: main"
+)
+
+# Count changes
+TOTAL_FILES=0
+TOTAL_CHANGES=0
+
+echo -e "${BLUE}Scanning for files with explicit nav values...${NC}"
+echo ""
+
+# Find all markdown files
+while IFS= read -r -d '' file; do
+    file_changes=0
+    
+    # Check if file has any nav patterns
+    for pattern in "${EXPLICIT_NAV_PATTERNS[@]}"; do
+        if grep -q "$pattern" "$file" 2>/dev/null; then
+            ((file_changes++)) || true
+        fi
+    done
+    
+    if [[ $file_changes -gt 0 ]]; then
+        ((TOTAL_FILES++)) || true
+        echo -e "${GREEN}Found:${NC} $file"
+        
+        # Show what would change
+        for i in "${!OLD_PATTERNS[@]}"; do
+            old_pattern="${OLD_PATTERNS[$i]}"
+            new_pattern="${NEW_PATTERNS[$i]}"
+            if grep -q "$old_pattern" "$file" 2>/dev/null; then
+                echo -e "  ${YELLOW}Change:${NC} '$old_pattern' → '$new_pattern'"
+                ((TOTAL_CHANGES++)) || true
+                
+                if ! $DRY_RUN; then
+                    # Apply the change using sed
+                    if [[ "$OSTYPE" == "darwin"* ]]; then
+                        sed -i '' "s/$old_pattern/$new_pattern/g" "$file"
+                    else
+                        sed -i "s/$old_pattern/$new_pattern/g" "$file"
+                    fi
+                fi
+            fi
+        done
+        
+        # Check for named nav files that should use tree mode
+        # Note: These are trickier because we want to keep the YAML file reference
+        # but change how the template interprets them
+        for named_nav in "docs" "about" "quickstart" "main"; do
+            if grep -q "nav: $named_nav" "$file" 2>/dev/null; then
+                echo -e "  ${BLUE}Note:${NC} 'nav: $named_nav' - YAML file will be used with tree mode"
+                # No automatic migration - sidebar-left.html handles this via fallthrough
+            fi
+        done
+        
+        echo ""
+    fi
+done < <(find "$PAGES_DIR" -name "*.md" -print0 2>/dev/null)
+
+echo -e "${BLUE}═══════════════════════════════════════════════════════════════${NC}"
+echo -e "${BLUE}  Summary${NC}"
+echo -e "${BLUE}═══════════════════════════════════════════════════════════════${NC}"
+echo ""
+echo -e "Files scanned:  ${GREEN}$(find "$PAGES_DIR" -name "*.md" 2>/dev/null | wc -l | tr -d ' ')${NC}"
+echo -e "Files affected: ${GREEN}$TOTAL_FILES${NC}"
+echo -e "Changes made:   ${GREEN}$TOTAL_CHANGES${NC}"
+echo ""
+
+if $DRY_RUN; then
+    echo -e "${YELLOW}This was a dry run. To apply changes, run:${NC}"
+    echo -e "  ${GREEN}./scripts/migrate-nav-modes.sh --apply${NC}"
+else
+    echo -e "${GREEN}Migration complete!${NC}"
+fi
+
+echo ""
+echo -e "${BLUE}Navigation Mode Reference:${NC}"
+echo "  auto       - Auto-generated from collection documents"
+echo "  tree       - YAML-defined hierarchical navigation"
+echo "  categories - Category-based grouping"
+echo ""

data/scripts/update-preview-paths.sh

@@ -0,0 +1,145 @@
+#!/bin/bash
+#
+# update-preview-paths.sh
+# 
+# Updates all preview paths in markdown frontmatter to remove the /assets/ prefix.
+# This aligns with the new auto_prefix feature that automatically prepends /assets/.
+#
+# Usage:
+#   ./scripts/update-preview-paths.sh           # Dry run (preview changes)
+#   ./scripts/update-preview-paths.sh --apply   # Apply changes
+#
+# Example transformation:
+#   preview: /assets/images/previews/my-image.png
+#   becomes:
+#   preview: /images/previews/my-image.png
+#
+
+set -euo pipefail
+
+# Colors for output
+RED='\033[0;31m'
+GREEN='\033[0;32m'
+YELLOW='\033[1;33m'
+BLUE='\033[0;34m'
+CYAN='\033[0;36m'
+NC='\033[0m' # No Color
+
+# Script directory
+SCRIPT_DIR="$(cd "$(dirname "${BASH_SOURCE[0]}")" && pwd)"
+PROJECT_ROOT="$(cd "$SCRIPT_DIR/.." && pwd)"
+
+# Counters
+TOTAL_FILES=0
+MODIFIED_FILES=0
+SKIPPED_FILES=0
+
+# Mode
+DRY_RUN=true
+
+# Parse arguments
+for arg in "$@"; do
+    case $arg in
+        --apply)
+            DRY_RUN=false
+            shift
+            ;;
+        --help|-h)
+            echo "Usage: $0 [--apply]"
+            echo ""
+            echo "Updates preview paths in markdown frontmatter to remove /assets/ prefix."
+            echo ""
+            echo "Options:"
+            echo "  --apply    Apply changes (default is dry run)"
+            echo "  --help     Show this help message"
+            exit 0
+            ;;
+    esac
+done
+
+log_info() {
+    echo -e "${BLUE}[INFO]${NC} $1"
+}
+
+log_success() {
+    echo -e "${GREEN}[SUCCESS]${NC} $1"
+}
+
+log_warning() {
+    echo -e "${YELLOW}[WARNING]${NC} $1"
+}
+
+log_change() {
+    echo -e "${CYAN}[CHANGE]${NC} $1"
+}
+
+echo ""
+echo -e "${BLUE}========================================${NC}"
+echo -e "${BLUE}🔄 Preview Path Updater${NC}"
+echo -e "${BLUE}========================================${NC}"
+echo ""
+
+if [ "$DRY_RUN" = true ]; then
+    log_warning "DRY RUN MODE - No files will be modified"
+    log_info "Run with --apply to make changes"
+else
+    log_warning "APPLY MODE - Files will be modified"
+fi
+echo ""
+
+# Find all markdown files in pages directory
+find "$PROJECT_ROOT/pages" -name "*.md" -type f | while read -r file; do
+    TOTAL_FILES=$((TOTAL_FILES + 1))
+    
+    # Check if file has a preview field with /assets/ prefix
+    if grep -q "^preview: /assets/" "$file" 2>/dev/null; then
+        # Extract current preview path
+        current_path=$(grep "^preview:" "$file" | head -1 | sed 's/^preview: //')
+        
+        # Remove /assets/ prefix
+        new_path=$(echo "$current_path" | sed 's|^/assets/|/|')
+        
+        log_change "$file"
+        echo "  Old: $current_path"
+        echo "  New: $new_path"
+        
+        if [ "$DRY_RUN" = false ]; then
+            # Use sed to replace the preview line
+            if [[ "$OSTYPE" == "darwin"* ]]; then
+                # macOS sed requires empty string for -i
+                sed -i '' "s|^preview: /assets/|preview: /|" "$file"
+            else
+                # Linux sed
+                sed -i "s|^preview: /assets/|preview: /|" "$file"
+            fi
+            log_success "Updated: $file"
+        fi
+        
+        MODIFIED_FILES=$((MODIFIED_FILES + 1))
+    else
+        SKIPPED_FILES=$((SKIPPED_FILES + 1))
+    fi
+done
+
+echo ""
+echo -e "${CYAN}========================================${NC}"
+echo -e "${CYAN}📊 Summary${NC}"
+echo -e "${CYAN}========================================${NC}"
+
+# Re-count since subshell doesn't persist variables
+MODIFIED_COUNT=$(find "$PROJECT_ROOT/pages" -name "*.md" -type f -exec grep -l "^preview: /assets/" {} \; 2>/dev/null | wc -l | tr -d ' ')
+TOTAL_COUNT=$(find "$PROJECT_ROOT/pages" -name "*.md" -type f | wc -l | tr -d ' ')
+
+if [ "$DRY_RUN" = true ]; then
+    echo "  Files to update: $MODIFIED_COUNT"
+    echo "  Total markdown files: $TOTAL_COUNT"
+    echo ""
+    log_info "Run with --apply to make these changes"
+else
+    # After applying, count should be 0
+    REMAINING=$(find "$PROJECT_ROOT/pages" -name "*.md" -type f -exec grep -l "^preview: /assets/" {} \; 2>/dev/null | wc -l | tr -d ' ')
+    echo "  Files updated: $MODIFIED_COUNT"
+    echo "  Files remaining: $REMAINING"
+    echo "  Total markdown files: $TOTAL_COUNT"
+fi
+echo ""

metadata

@@ -1,14 +1,14 @@
 --- !ruby/object:Gem::Specification
 name: jekyll-theme-zer0
 version: !ruby/object:Gem::Version
-  version: 0.15.2
+  version: 0.17.0
 platform: ruby
 authors:
 - Amr Abdel
 autorequire: 
 bindir: bin
 cert_chain: []
-date: 2025-12-20 00:00:00.000000000 Z
+date: 2025-12-24 00:00:00.000000000 Z
 dependencies:
 - !ruby/object:Gem::Dependency
   name: jekyll
@@ -80,9 +80,11 @@ files:
 - _data/README.md
 - _data/authors.yml
 - _data/content_statistics.yml
+- _data/features.yml
 - _data/generate_statistics.rb
 - _data/generate_statistics.sh
 - _data/github-actions-example.yml
+- _data/navigation/README.md
 - _data/navigation/about.yml
 - _data/navigation/docs.yml
 - _data/navigation/home.yml
@@ -127,6 +129,7 @@ files:
 - _includes/landing/landing-install-cards.html
 - _includes/landing/landing-quick-links.html
 - _includes/navigation/breadcrumbs.html
+- _includes/navigation/nav-tree.html
 - _includes/navigation/nav_list.html
 - _includes/navigation/navbar.html
 - _includes/navigation/sidebar-categories.html
@@ -157,6 +160,7 @@ files:
 - _plugins/preview_image_generator.rb
 - _plugins/theme_version.rb
 - _sass/core/_docs.scss
+- _sass/core/_nav-tree.scss
 - _sass/core/_syntax.scss
 - _sass/core/_theme.scss
 - _sass/core/_variables.scss
@@ -183,6 +187,7 @@ files:
 - assets/images/previews/published-documentation-library.png
 - assets/images/previews/quantum-computing-explained-from-qubits-to-quantum.png
 - assets/images/previews/science.png
+- assets/images/previews/site-personalization-configuration.png
 - assets/images/previews/technology.png
 - assets/images/previews/the-complete-guide-to-startup-funding-in-2025.png
 - assets/images/previews/the-remote-work-revolution-how-global-teams-are-re.png
@@ -201,12 +206,19 @@ files:
 - assets/js/color-modes.js
 - assets/js/docs.min.js
 - assets/js/halfmoon.js
+- assets/js/modules/navigation/config.js
+- assets/js/modules/navigation/focus.js
+- assets/js/modules/navigation/gestures.js
+- assets/js/modules/navigation/index.js
+- assets/js/modules/navigation/keyboard.js
+- assets/js/modules/navigation/scroll-spy.js
+- assets/js/modules/navigation/sidebar-state.js
+- assets/js/modules/navigation/smooth-scroll.js
 - assets/js/myScript.js
 - assets/js/nanobar.min.js
 - assets/js/particles-source.js
 - assets/js/particles.js
 - assets/js/side-bar-folders.js
-- assets/js/sidebar.js
 - assets/particles.json
 - scripts/README.md
 - scripts/analyze-commits.sh
@@ -230,6 +242,7 @@ files:
 - scripts/lib/preview_generator.py
 - scripts/lib/validation.sh
 - scripts/lib/version.sh
+- scripts/migrate-nav-modes.sh
 - scripts/release
 - scripts/setup.sh
 - scripts/test-auto-version.sh
@@ -244,6 +257,7 @@ files:
 - scripts/test/lib/test_validation.sh
 - scripts/test/lib/test_version.sh
 - scripts/test/theme/validate
+- scripts/update-preview-paths.sh
 - scripts/utils/analyze-commits
 - scripts/utils/fix-markdown
 - scripts/utils/setup