ITBlogPros Deployment Troubleshooting Guide

Issue: New articles build locally but don't appear on itblogpros.com

✅ Step-by-Step Diagnostic Process

Step 1: Verify GitHub Pages Configuration

  1. Go to your repository on GitHub
  2. Navigate to Settings → Pages
  3. Check these settings:
  4. Click Save if you made changes
  5. Wait 2-3 minutes

Expected Result: You should see a green checkmark with "Your site is live at https://itblogpros.com"

Step 2: Check GitHub Actions Build Status

  1. Go to your repository
  2. Click the Actions tab at the top
  3. Look at your most recent workflow runs

What to Look For:

✅ Green checkmark = Build succeeded, site should be deployed
❌ Red X = Build failed, site won't deploy
🟡 Yellow dot = Build in progress, wait a few minutes

If you see a red X:

  1. Click on the failed workflow
  2. Click on "build-and-deploy" job
  3. Expand the "Build site with Eleventy" step
  4. Read the error message
  5. Common errors:

Step 3: Verify Your Articles Have Correct Front Matter

Open your recent articles and verify:

---
title: "Your Title"
date: "2025-10-02T10:00:00.000Z"  # ⚠️ Must be in the past!
tags:
  - post  # ⚠️ MUST include "post" tag!
  - wifi
  - router
---

Common Mistakes:

Step 4: Test Locally First

Before pushing to GitHub, always test locally:

# Clean build
rm -rf _site

# Build fresh
npx @11ty/eleventy --serve

# Check http://localhost:8080
# - Does article appear?
# - Any console errors?
# - Links working?

If it doesn't work locally, it won't work on GitHub!

Step 5: Clear Browser Cache

Your articles might be deployed but your browser is showing cached content.

Methods to Clear Cache:

  1. Hard Refresh:

  2. Incognito/Private Mode:

  3. Different Device:

  4. Clear Browser Cache Completely:

Step 6: Check DNS and Domain Configuration

If nothing above works, verify your domain is configured correctly:

  1. Go to your domain registrar (where you bought itblogpros.com)

  2. Check DNS settings:

  3. Wait up to 24 hours for DNS changes to propagate

Step 7: Force GitHub Pages Rebuild

Sometimes GitHub Pages gets "stuck" and needs a manual kick:

  1. Go to your repository
  2. Go to the gh-pages branch
  3. Make a tiny change (add a space to README)
  4. Commit the change
  5. Wait 2-3 minutes

OR

  1. Go to Settings → Pages
  2. Change the source to main branch
  3. Save
  4. Wait 30 seconds
  5. Change back to gh-pages branch
  6. Save
  7. Wait 2-3 minutes

🔧 Common Error Messages and Fixes

"404: File not found" on GitHub Pages

Cause: Article isn't in the _site directory after build

Fix:

  1. Check article has "post" tag
  2. Rebuild locally: npx @11ty/eleventy
  3. Check if article appears in _site/ folder
  4. If not there locally, it won't be on GitHub

"ENOENT: no such file or directory"

Cause: Path is case-sensitive on Linux/GitHub but not on Windows

Fix:

  1. Check file paths in includes: _includes/layout.njk not _includes/Layout.njk
  2. Check image paths: /images/photo.jpg not /Images/photo.jpg
  3. Rebuild and redeploy

"Unexpected token" or "YAMLException"

Cause: Invalid YAML syntax in front matter

Fix:

  1. Check for unmatched quotes: title: "WiFi 7 vs WiFi 6"
  2. Check proper indentation (use spaces, not tabs)
  3. Validate YAML at https://www.yamllint.com/

"Module not found"

Cause: Missing npm package

Fix:

  1. Make sure package.json includes all dependencies
  2. On GitHub, workflow runs npm ci which requires package-lock.json
  3. Commit both package.json AND package-lock.json

📱 Quick Verification Checklist

Before asking for help, verify:

🆘 Still Not Working?

If you've tried everything above:

  1. Check GitHub Actions Logs:

  2. Check _site Directory:

    # Build locally
npx @11ty/eleventy

# Check if article exists
dir _site\2025\10\02\  # Windows
ls _site/2025/10/02/   # Mac/Linux

  3. Verify Article Metadata:

  4. Check Live vs Local:

💡 Pro Tips

Prevent Future Issues

  1. Always Build Locally First

    npx @11ty/eleventy --serve

    If it doesn't work locally, fix it before pushing to GitHub

  2. Use Article Template Copy ARTICLE-TEMPLATE.md for consistent formatting

  3. Check Actions After Every Push

  4. Add .gitignore (optional but recommended)

    _site/
node_modules/
.DS_Store

  5. Use Relative Dates Instead of hardcoding dates, use:

    date +"%Y-%m-%dT%H:%M:%S.000Z"

🎯 Most Common Solutions

90% of deployment issues are one of these:

  1. GitHub Pages looking at wrong branch

  2. Browser cache

  3. Missing "post" tag

  4. Future date

  5. GitHub Actions failing

📞 Getting Help

If you're still stuck:

  1. Check GitHub Actions logs for exact error
  2. Share the error message
  3. Verify the article works locally first
  4. Include article front matter in your question

Remember: If it works locally but not on GitHub, it's almost always:

Good luck! 🚀