fix(docs): implement comprehensive Jekyll debugging and theme fixes

- Add extensive build tracing and HTML structure validation
- Switch from remote_theme to local theme for better CI compatibility
- Add layout defaults for all pages and API documentation
- Create API index page with proper navigation structure
- Update all API HTML files with layout: default frontmatter
- Add GitHub API-based deployment verification
- Add live site validation with curl testing
- Create debug workflow for manual troubleshooting

Author: schamane

.github/workflows/debug-docs.yml

@@ -0,0 +1,68 @@
+name: Debug Documentation Build
+
+on:
+  workflow_dispatch:
+    inputs:
+      debug_level:
+        description: 'Debug level (1-3)'
+        required: true
+        default: '2'
+        type: choice
+        options:
+          - '1'
+          - '2'
+          - '3'
+
+permissions:
+  contents: read
+
+jobs:
+  debug-build:
+    runs-on: ubuntu-latest
+    steps:
+      - name: Checkout repository
+        uses: actions/checkout@v4
+
+      - name: Setup Ruby
+        uses: ruby/setup-ruby@v1
+        with:
+          ruby-version: "3.2"
+          bundler-cache: true
+          working-directory: docs
+
+      - name: Debug Jekyll Build
+        env:
+          GH_TOKEN: ${{ secrets.GH_TOKEN }}
+          DEBUG_LEVEL: ${{ github.event.inputs.debug_level }}
+        run: |
+          echo "=== Debug Level: $DEBUG_LEVEL ==="
+          
+          # Level 1: Basic info
+          bundle exec jekyll --version
+          bundle list | grep -E "(jekyll|just-the-docs|sass)"
+          
+          echo "=== Configuration ==="
+          grep -E "^(theme|remote_theme|baseurl)" _config.yml
+          
+          # Level 2: Build with trace
+          if [ "$DEBUG_LEVEL" -ge 2 ]; then
+            echo "=== Building with verbose output ==="
+            bundle exec jekyll build --baseurl="/node-syslog" --verbose --trace
+          fi
+          
+          # Level 3: Full analysis
+          if [ "$DEBUG_LEVEL" -ge 3 ]; then
+            echo "=== Full site analysis ==="
+            find _site -type f -name "*.html" -exec echo "=== {} ===" \; -exec head -30 {} \;
+            
+            echo "=== Asset analysis ==="
+            find _site -name "*.css" -o -name "*.js" | head -20
+            
+            echo "=== Theme check ==="
+            if [ -f "_site/assets/css/just-the-docs.css" ]; then
+              echo "✅ Theme CSS found"
+            else
+              echo "❌ Theme CSS missing"
+            fi
+          fi
+        working-directory: docs

.github/workflows/docs.yml

@@ -169,18 +169,87 @@ jobs:
           bundler-cache: true
           working-directory: docs
 
-      - name: Build Jekyll site
+      - name: Trace Jekyll Build Process
         run: |
-          echo "🔨 Building Jekyll site..."
-          echo "Current directory: $(pwd)"
-          echo "Jekyll config:"
-          bundle exec jekyll doctor
-          echo ""
-          echo "Starting Jekyll build..."
-          bundle exec jekyll build --baseurl="/node-syslog" --verbose --trace
-          echo "✅ Jekyll build completed"
-          echo "Build output directory contents:"
-          ls -la _site/ || echo "_site directory not found"
+          echo "=== Jekyll Environment ==="
+          bundle exec jekyll --version
+          bundle list | grep -E "(jekyll|just-the-docs|sass)"
+          
+          echo "=== Jekyll Doctor Diagnosis ==="
+          bundle exec jekyll doctor --trace
+          
+          echo "=== Build Configuration ==="
+          echo "Theme config:"
+          grep -E "^(theme|remote_theme)" _config.yml
+          echo "Baseurl config:"
+          grep -E "^baseurl" _config.yml
+          
+          echo "=== Starting Verbose Build ==="
+          bundle exec jekyll build --baseurl="/node-syslog" --verbose --trace 2>&1 | tee build.log
+          
+          echo "=== Build Log Analysis ==="
+          echo "Theme-related messages:"
+          grep -i "theme\|layout\|sass" build.log || echo "No theme messages found"
+          
+          echo "=== Generated Site Structure ==="
+          find _site -type f -name "*.html" | wc -l
+          find _site -type f -name "*.css" | wc -l
+          find _site -type f -name "*.js" | wc -l
+          
+          echo "=== Critical Files Check ==="
+          for file in index.html _api/index.html; do
+            if [ -f "_site/$file" ]; then
+              echo "✅ _site/$file exists"
+              echo "First 50 lines:"
+              head -50 "_site/$file"
+              echo "---"
+            else
+              echo "❌ _site/$file missing"
+            fi
+          done
+        working-directory: docs
+
+      - name: Analyze HTML Structure
+        run: |
+          echo "=== HTML Structure Validation ==="
+          for html_file in $(find _site -name "*.html" -type f | head -5); do
+            echo "=== Analyzing: $html_file ==="
+            echo "Has DOCTYPE:"
+            head -1 "$html_file" | grep -i "<!DOCTYPE" && echo "✅" || echo "❌"
+            echo "Has <html>:"
+            grep -q "<html" "$html_file" && echo "✅" || echo "❌"
+            echo "Has <head>:"
+            grep -q "<head" "$html_file" && echo "✅" || echo "❌"
+            echo "Has <body>:"
+            grep -q "<body" "$html_file" && echo "✅" || echo "❌"
+            echo "Has <nav>:"
+            grep -q "<nav" "$html_file" && echo "✅" || echo "❌"
+            echo "Has theme CSS link:"
+            grep -q "just-the-docs.*css\|main.*css" "$html_file" && echo "✅" || echo "❌"
+            echo "---"
+          done
+        working-directory: docs
+
+      - name: Check Theme Asset Generation
+        run: |
+          echo "=== Theme Assets Investigation ==="
+          echo "CSS files in _site:"
+          find _site -name "*.css" -type f | sort
+          
+          echo "JS files in _site:"
+          find _site -name "*.js" -type f | sort
+          
+          echo "SASS processing check:"
+          if find _site -name "*.css" | grep -q "just-the-docs"; then
+            echo "✅ just-the-docs CSS found"
+          else
+            echo "❌ just-the-docs CSS missing"
+            echo "All CSS files:"
+            find _site -name "*.css" -exec ls -la {} \;
+          fi
+          
+          echo "Asset directory structure:"
+          find _site/assets -type f 2>/dev/null | head -20 || echo "No assets directory"
         working-directory: docs
 
       - name: Add .nojekyll
@@ -240,31 +309,51 @@ jobs:
           keep_files: false
           # cname: node-syslog.schamane.de
 
-      - name: List deployed files (requires GH_TOKEN)
-        if: env.GH_TOKEN != ''
+      - name: Verify Deployment via GitHub API
+        env:
+          GH_TOKEN: ${{ secrets.GH_TOKEN }}
         run: |
-          echo "📁 Files deployed to gh-pages:"
-          gh api repos/:owner/:repo/pages/build/latest | jq -r '.artifacts[].name' 2>/dev/null || echo "Using fallback listing..."
-
-          # Fallback listing
-          echo "📁 Available files in _site:"
-          find docs/_site -name "*.html" -o -name "*.css" -o -name "*.js" -o -name "*.svg" | sort | head -10
-          echo "..."
-          echo "Total HTML files: $(find docs/_site -name "*.html" | wc -l)"
-          echo "Total CSS files: $(find docs/_site -name "*.css" | wc -l)"
-          echo "Total JS files: $(find docs/_site -name "*.js" | wc -l)"
+          echo "=== Checking gh-pages branch ==="
+          gh api repos/${{ github.repository }}/git/refs/heads/gh-pages || echo "gh-pages branch not found"
+          
+          echo "=== Latest deployment commit ==="
+          gh api repos/${{ github.repository }}/commits?sha=gh-pages&per_page=1 | jq -r '.[0].commit.message'
+          
+          echo "=== Checking deployed files via API ==="
+          gh api repos/${{ github.repository }}/git/trees/gh-pages?recursive=1 | jq -r '.tree[] | select(.type == "blob") | .path' | grep -E "\\.(html|css|js)$" | head -20
+          
+          echo "=== Fetching and analyzing deployed index.html ==="
+          gh api repos/${{ github.repository }}/contents/index.html?ref=gh-pages | jq -r '.content' | base64 -d | head -50
+          
+          echo "=== Checking for theme assets in deployment ==="
+          gh api repos/${{ github.repository }}/git/trees/gh-pages?recursive=1 | jq -r '.tree[] | .path' | grep -E "(just-the-docs|main|style).*\\.(css|js)" || echo "No theme assets found"
+
+      - name: Live Site Validation
         env:
           GH_TOKEN: ${{ secrets.GH_TOKEN }}
-
-      - name: List deployed files (fallback)
-        if: env.GH_TOKEN == ''
         run: |
-          echo "📁 Files deployed to gh-pages:"
-          echo "📁 Available files in _site:"
-          find docs/_site -name "*.html" -o -name "*.css" -o -name "*.js" -o -name "*.svg" | sort | head -10
-          echo "..."
-          echo "Total HTML files: $(find docs/_site -name "*.html" | wc -l)"
-          echo "Total CSS files: $(find docs/_site -name "*.css" | wc -l)"
-          echo "Total JS files: $(find docs/_site -name "*.js" | wc -l)"
-          echo ""
-          echo "📖 Documentation available at: https://schamane.github.io/node-syslog/"
+          echo "=== Waiting for deployment to propagate ==="
+          sleep 15
+          
+          echo "=== Testing live site ==="
+          SITE_URL="https://${{ github.repository_owner }}.github.io/${{ github.event.repository.name }}/"
+          echo "Testing URL: $SITE_URL"
+          
+          echo "=== Fetching live site HTML ==="
+          curl -s "$SITE_URL" | head -100 | tee live-site.html
+          
+          echo "=== Analyzing live site structure ==="
+          echo "Has DOCTYPE:"
+          grep -i "<!DOCTYPE" live-site.html && echo "✅" || echo "❌"
+          
+          echo "Has <nav> element:"
+          grep "<nav" live-site.html && echo "✅" || echo "❌"
+          
+          echo "Has theme CSS:"
+          grep -E "just-the-docs.*css|main.*css" live-site.html && echo "✅" || echo "❌"
+          
+          echo "Title tag:"
+          grep "<title>" live-site.html || echo "No title found"
+          
+          echo "=== Checking HTTP headers ==="
+          curl -I "$SITE_URL"

docs/Gemfile

@@ -1,14 +1,14 @@
 source "https://rubygems.org"
 
 # Use Ruby version compatible with Jekyll
-ruby ">= 2.6.0"
+ruby ">= 3.2.0"
 
 # Use exact versions for reproducible builds
-gem "jekyll", "~> 4.3.0"
-gem "just-the-docs", "~> 0.8.2"
+gem "jekyll", "~> 4.4.0"
+gem "just-the-docs", "~> 0.10.0"
 
 group :jekyll_plugins do
-  gem "jekyll-feed", "~> 0.15.0"
-  gem "jekyll-sitemap", "~> 1.3.0"
-  gem "jekyll-seo-tag", "~> 2.7.0"
+  gem "jekyll-feed"
+  gem "jekyll-sitemap"
+  gem "jekyll-seo-tag"
 end

docs/_api/classes/Syslog.html

@@ -1,5 +1,6 @@
 ---
-title: "Syslog"
+layout: default
+title: "Syslog Class"
 parent: API Reference
 nav_order: 2
 ---

docs/_api/functions/alert.html

@@ -1,6 +1,6 @@
 ---
+layout: default
 title: "Alert"
-
 parent: API Reference
 nav_order: auto
 ---

docs/_api/functions/createSyslog.html

@@ -1,6 +1,6 @@
 ---
+layout: default
 title: "CreateSyslog"
-
 parent: API Reference
 nav_order: auto
 ---

docs/_api/functions/critical.html

@@ -1,6 +1,6 @@
 ---
+layout: default
 title: "Critical"
-
 parent: API Reference
 nav_order: auto
 ---

docs/_api/functions/debug.html

@@ -1,6 +1,6 @@
 ---
+layout: default
 title: "Debug"
-
 parent: API Reference
 nav_order: auto
 ---

docs/_api/functions/emergency.html

@@ -1,6 +1,6 @@
 ---
+layout: default
 title: "Emergency"
-
 parent: API Reference
 nav_order: auto
 ---

docs/_api/functions/error.html

@@ -1,6 +1,6 @@
 ---
+layout: default
 title: "Error"
-
 parent: API Reference
 nav_order: auto
 ---