Part 4: Troubleshooting & Maintenance

Fixing Problems & Keeping Your Site Running

← Back to Tutorial Home | Part 1 | Part 2 | Part 3 | Part 4: Troubleshooting

Even the most careful developers run into problems! This section will help you fix common issues, recover from mistakes, organize your files properly, and maintain your website long-term.

Common Problems & Solutions

❌ Problem: My website isn't showing up / I get a 404 error

✅ Solutions to try:
  1. Check if GitHub Pages is enabled:
    • Go to Settings → Pages
    • Make sure "Branch" is set to "main" (not "None")
    • Click Save again if needed
  2. Verify repository is Public:
    • Go to Settings → General
    • Scroll down to "Danger Zone"
    • Check if it says "This repository is public"
    • If private, click "Change visibility" to make it public
  3. Wait longer: Sometimes it takes 5-10 minutes for pages to deploy
  4. Check your URL: Make sure you're using the correct URL format:
    • https://username.github.io/repository-name/

❌ Problem: My changes aren't showing up on the live site

✅ Solutions to try:
  1. Did you commit your changes?
    • Editing isn't enough—you MUST click "Commit changes"
    • Check the file to see if your edits are there
  2. Wait 2-3 minutes: GitHub Pages needs time to rebuild
  3. Hard refresh your browser:
    • Windows/Linux: Ctrl + Shift + R
    • Mac: Cmd + Shift + R
  4. Clear cache or use incognito mode: Open site in private/incognito window
  5. Try a different browser or device: Test on your phone or different computer

❌ Problem: My images aren't showing up (broken image icon)

✅ Solutions to try:
  1. Check filename matches EXACTLY:
    • HTML says: profile.jpg
    • File must be named: profile.jpg (not Profile.jpg or profile.JPG)
    • Case-sensitive! Capital letters matter!
  2. Check file extension matches:
    • If HTML says .jpg, file must be .jpg (not .png)
  3. Check file path is correct:
    • If image is in /images folder, HTML should say: images/filename.jpg
    • No / at the beginning: images/file.jpg NOT /images/file.jpg
  4. Verify image was uploaded: Go to your images folder on GitHub and check it's there

❌ Problem: My website layout is broken / looks weird

✅ Possible causes & solutions:
  1. Missing or extra HTML tag:
    • Did you accidentally delete a <div> or </div>?
    • Every opening tag needs a closing tag
    • Use GitHub's version history to restore (see next section)
  2. CSS was changed incorrectly:
    • Did you edit the CSS file?
    • Try reverting the CSS changes
  3. File encoding issue:
    • When copying code, sometimes special characters break
    • Re-type instead of copy-pasting

❌ Problem: My PDF/document download link doesn't work

✅ Solutions to try:
  1. Check link path:
    • If file is in /files folder: href="files/resume.pdf"
    • If file is in root: href="resume.pdf"
  2. Check filename matches: Same rules as images—case-sensitive, exact match
  3. Verify file was uploaded: Check the folder on GitHub

Undoing Mistakes: Using Version History

Made a mistake and want to go back to a previous version? GitHub saves every version!

Step 27: Viewing Version History

  1. Go to your repository homepage
  2. Click on the file you want to restore (e.g., index.html)
  3. Click the "History" button (or clock icon) at the top right
  4. You'll see a list of all commits (saves) made to this file
  5. Each commit shows:
    • The commit message you wrote
    • When it was saved
    • Who saved it (you)

Step 28: Restoring a Previous Version

  1. In the History view, find the version you want to go back to
  2. Click on that commit
  3. You'll see the file as it was at that point in time
  4. Click the "View file" button
  5. Copy all the code from that version
  6. Go back to the current version of the file
  7. Click edit (pencil icon)
  8. Select all current code (Ctrl+A or Cmd+A)
  9. Delete it and paste the old version
  10. Commit with a message like "Restored previous version"
✨ Pro Tip: This is why committing frequently with clear messages is important! You can easily find and restore exactly the version you want.

File Organization Best Practices

Good File Naming Rules:

💡 Why these rules?

Folder Structure Best Practices:

your-repository/
├── index.html           (homepage)
├── about.html           (other pages)
├── projects.html
├── style.css            (or in a /css folder)
├── images/              (all images)
│   ├── profile.jpg
│   ├── project1.png
│   └── project2.png
└── files/               (documents)
    ├── resume.pdf
    └── portfolio.pdf
✨ Keep It Clean: Don't upload random files, old versions, or test files to your repository. Keep only what you need for your website!

Regular Website Maintenance

Monthly Maintenance Checklist:

Regular Tasks:

Quarterly Review Checklist:

Deeper Review:

💡 Why maintenance matters: An outdated portfolio site can hurt more than help! Keep it current to make the best impression on potential employers, clients, or collaborators.

Getting Help When You're Stuck

Where to Find Help:

1. GitHub Community:

2. Stack Overflow:

3. GitHub Pages Documentation:

4. Web Development Resources:

How to Ask Good Questions:

✨ Include these details:
  1. What you're trying to accomplish: "I want to change my navbar color"
  2. What you've tried: "I edited the CSS file and changed background-color"
  3. What's happening instead: "The color didn't change"
  4. Any error messages: Screenshots of errors or console messages
  5. Your code: Share the relevant code snippet (use code blocks)

Backing Up Your Website

GitHub automatically saves all versions, but you can also create local backups:

Downloading Your Repository:

  1. Go to your repository homepage
  2. Click the green "Code" button
  3. Select "Download ZIP"
  4. Save the ZIP file to your computer
  5. Extract it to have a local copy of all your files
💡 When to download a backup:

🎊 You're Now a GitHub Pages Pro!

You've completed the entire tutorial series and learned:

You now have the skills to manage and grow your website independently!

📝 Final Tips:
← Back to Part 3: Customization View Reference Guide →

This tutorial was created for students in the Master of Arts in Educational Innovation, Technology, and Entrepreneurship (MEITE) program at UNC Chapel Hill School of Education.