fix(docs): implement comprehensive Jekyll debugging and theme fixes #88
This file contains hidden or bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
| name: Build and Deploy Documentation | |
| on: | |
| push: | |
| branches: [main] | |
| pull_request: | |
| branches: [main] | |
| workflow_dispatch: | |
| concurrency: | |
| group: "docs" | |
| cancel-in-progress: false | |
| permissions: | |
| contents: write | |
| pages: write | |
| jobs: | |
| # === PARALLEL BUILD STAGE === | |
| setup-build-environment: | |
| name: Setup Build Environment | |
| runs-on: ubuntu-latest | |
| outputs: | |
| node-version: ${{ steps.node.outputs.version }} | |
| cache-key: ${{ steps.cache.outputs.key }} | |
| steps: | |
| - name: Checkout repository | |
| uses: actions/checkout@v4 | |
| - name: Setup pnpm | |
| uses: pnpm/action-setup@v3 | |
| with: | |
| version: latest | |
| - name: Setup Node.js | |
| id: node | |
| uses: actions/setup-node@v4 | |
| with: | |
| node-version: "22" | |
| cache: "pnpm" | |
| - name: Generate cache key | |
| id: cache | |
| run: echo "key=deps-$(node -v)-$(pnpm -v)-${{ hashFiles('pnpm-lock.yaml') }}" >> $GITHUB_OUTPUT | |
| build-typescript: | |
| name: Build TypeScript | |
| runs-on: ubuntu-latest | |
| needs: setup-build-environment | |
| steps: | |
| - name: Checkout repository | |
| uses: actions/checkout@v4 | |
| - name: Setup Node.js and pnpm | |
| uses: ./.github/actions/setup-node-pnpm | |
| - name: Cache dependencies | |
| uses: actions/cache@v4 | |
| with: | |
| path: ~/.pnpm-store | |
| key: ${{ needs.setup-build-environment.outputs.cache-key }} | |
| - name: Install dependencies | |
| run: pnpm install --frozen-lockfile --ignore-scripts | |
| - name: Build TypeScript | |
| run: pnpm run build | |
| generate-api-docs: | |
| name: Generate API Documentation | |
| runs-on: ubuntu-latest | |
| needs: setup-build-environment | |
| steps: | |
| - name: Checkout repository | |
| uses: actions/checkout@v4 | |
| - name: Setup Node.js and pnpm | |
| uses: ./.github/actions/setup-node-pnpm | |
| - name: Cache dependencies | |
| uses: actions/cache@v4 | |
| with: | |
| path: ~/.pnpm-store | |
| key: ${{ needs.setup-build-environment.outputs.cache-key }} | |
| - name: Install dependencies | |
| run: pnpm install --frozen-lockfile --ignore-scripts | |
| - name: Generate API docs | |
| run: pnpm run docs:build | |
| setup-jekyll: | |
| name: Setup Jekyll Environment | |
| runs-on: ubuntu-latest | |
| needs: setup-build-environment | |
| 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: Validate Build Environment | |
| run: | | |
| echo "🔍 Validating build environment..." | |
| # Check Ruby version | |
| RUBY_VERSION=$(ruby -e 'puts RUBY_VERSION') | |
| echo "Ruby version: $RUBY_VERSION" | |
| # Check Bundler version | |
| BUNDLER_VERSION=$(bundle --version) | |
| echo "Bundler version: $BUNDLER_VERSION" | |
| # Verify all gems are installed | |
| if bundle check; then | |
| echo "✅ All dependencies satisfied" | |
| else | |
| echo "❌ Missing dependencies" | |
| exit 1 | |
| fi | |
| working-directory: docs | |
| - name: Update just-the-docs | |
| run: bundle update just-the-docs | |
| working-directory: docs | |
| - name: Verify Jekyll and just-the-docs versions | |
| run: | | |
| echo "Checking Jekyll version..." | |
| JEKYLL_VERSION=$(bundle exec jekyll --version | cut -d' ' -f2) | |
| echo "Installed Jekyll version: $JEKYLL_VERSION" | |
| EXPECTED_JEKYLL_MIN="4.3.0" | |
| if [[ "$(printf '%s\n' "$EXPECTED_JEKYLL_MIN" "$JEKYLL_VERSION" | sort -V | head -n1)" == "$EXPECTED_JEKYLL_MIN" ]]; then | |
| echo "✅ Jekyll version is compatible: $JEKYLL_VERSION (>= $EXPECTED_JEKYLL_MIN)" | |
| else | |
| echo "❌ Jekyll version too old. Got: $JEKYLL_VERSION, Expected: >= $EXPECTED_JEKYLL_MIN" | |
| exit 1 | |
| fi | |
| echo "Checking just-the-docs version..." | |
| JTD_VERSION=$(bundle list | grep just-the-docs | awk '{print $2}') | |
| echo "Installed just-the-docs version: $JTD_VERSION" | |
| echo "✅ just-the-docs version verified" | |
| working-directory: docs | |
| # === DEPLOY STAGE === | |
| build-and-deploy: | |
| name: Build and Deploy Documentation | |
| runs-on: ubuntu-latest | |
| needs: [build-typescript, generate-api-docs, setup-jekyll] | |
| if: github.ref == 'refs/heads/main' | |
| environment: | |
| name: github-pages | |
| url: ${{ steps.deployment.outputs.page_url }} | |
| 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: Trace Jekyll Build Process | |
| run: | | |
| 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 | |
| run: | | |
| echo "📁 Adding .nojekyll file..." | |
| echo "Current directory: $(pwd)" | |
| echo "_site directory contents:" | |
| ls -la _site/ || echo "_site directory not found" | |
| if [ ! -d "_site" ]; then | |
| echo "❌ _site directory does not exist. Jekyll build may have failed." | |
| echo "Creating _site directory manually..." | |
| mkdir -p _site | |
| fi | |
| touch _site/.nojekyll | |
| echo "✅ Created _site/.nojekyll" | |
| # Remove any conflicting .nojekyll in api directory | |
| rm -f _site/api/.nojekyll | |
| echo "✅ Cleaned up api/.nojekyll" | |
| echo "Final _site directory contents:" | |
| ls -la _site/ | |
| working-directory: docs | |
| - name: Verify build output | |
| run: | | |
| echo "📁 Generated files:" | |
| find _site -type f | head -20 | |
| echo "" | |
| echo "📁 Total files: $(find _site -type f | wc -l)" | |
| echo "📁 Total directories: $(find _site -type d | wc -l)" | |
| # Check for essential files | |
| if [ -f "_site/index.html" ]; then | |
| echo "✅ Main index.html found" | |
| else | |
| echo "❌ Main index.html missing" | |
| exit 1 | |
| fi | |
| if [ -f "_site/_api/index.html" ]; then | |
| echo "✅ API documentation found" | |
| else | |
| echo "⚠️ API documentation not found" | |
| fi | |
| working-directory: docs | |
| - name: Deploy to GitHub Pages | |
| id: deployment | |
| uses: peaceiris/actions-gh-pages@v3 | |
| with: | |
| github_token: ${{ secrets.GITHUB_TOKEN }} | |
| publish_dir: ./docs/_site | |
| publish_branch: gh-pages | |
| keep_files: false | |
| # cname: node-syslog.schamane.de | |
| - name: Verify Deployment via GitHub API | |
| env: | |
| GH_TOKEN: ${{ secrets.GH_TOKEN }} | |
| run: | | |
| 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 }} | |
| run: | | |
| 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" |