GitHub Pages Complete Guide

Step-by-Step Reference for Publishing Apps

For Google App Script Users Learning GitHub

☎ ✉ ƒ ✆

📝 Table of Contents

What is GitHub Pages?

GitHub Pages is a FREE website hosting service from GitHub. It turns your code files into live websites that anyone can visit on the internet.

Think of it like this:

  • Google App Script: Your code runs on Google's servers
  • GitHub Pages: Your HTML file becomes a live website on GitHub's servers
Perfect for single-file HTML apps! Your entire project (HTML, CSS, JavaScript) in ONE file.

What You Can Do:

  • Publish calculators, games, tools
  • Share portfolio projects
  • Host documentation
  • Create landing pages

What You Cannot Do:

  • Run server-side code (PHP, Python servers, etc.)
  • Store user data permanently (no database)
  • Upload files larger than 100MB

Setting Up Your GitHub Account

1 Create Your Account

  1. Go to https://github.com
  2. Click the "Sign up" button (top right)
  3. Enter your email address
  4. Create a password (use something secure!)
  5. Choose a username (this will be in your website URL)
  6. Complete the verification puzzle
  7. Click "Create account"
Your username becomes part of your website URL: https://username.github.io

2 Verify Your Email

  1. Check your email inbox
  2. Find the email from GitHub
  3. Click the verification link
  4. You're ready to start!

Creating Your First Project (Repository)

A repository (or "repo") is like a project folder. Each website needs its own repository.

1 Create New Repository

  1. Log into GitHub
  2. Click the green "New" button (top left corner)
  3. Or click your profile picture → "Your repositories" → "New"
Look for the green "New" button near the top left of the page

2 Fill Out Repository Details

  1. Repository name: Choose a name (e.g., my-calculator)
  2. Description: Optional, but helpful (e.g., "Simple calculator app")
  3. Public/Private: Choose Public (required for free GitHub Pages)
  4. Check: "Add a README file"
  5. Click the green "Create repository" button
Repository names become part of your URL: https://username.github.io/repository-name
Use lowercase letters and hyphens only in repository names. No spaces or special characters!

Publishing Your HTML File

1 Add Your HTML File

  1. Inside your repository, click "Add file" button
  2. Select "Create new file"
  3. Name your file: index.html
  4. Copy and paste your entire HTML code into the editor
  5. Scroll to bottom
  6. Click green "Commit new file" button
The file MUST be named index.html (all lowercase) for GitHub Pages to work automatically!

2 Enable GitHub Pages

  1. Click the "Settings" tab (top of your repository)
  2. Look at the left sidebar
  3. Scroll down and click "Pages"
  4. Under "Source" (or "Branch"), select "main" from the dropdown
  5. Click "Save"
  6. Wait 1-2 minutes
  7. Refresh the page
  8. You'll see a blue/green box with your website link!
Your website URL will be: https://yourusername.github.io/repository-name

3 Visit Your Live Website!

Click the link provided or type it into your browser. Your app is now live on the internet!

Understanding the .nojekyll File

What is Jekyll?

Jekyll is a tool GitHub uses automatically to process your files. It was designed for blogs and documentation sites.

The Problem:

Jekyll can "break" or hide some of your files, especially:

  • Files or folders starting with underscore (_myfile.js)
  • Certain JavaScript frameworks
  • Files with special characters
If your JavaScript or CSS mysteriously stops working after publishing, Jekyll might be interfering!

The Solution: .nojekyll File

This tiny file tells GitHub: "Don't process my files, just publish them exactly as they are!"

1 When to Add .nojekyll

Add this file if:

  • Your JavaScript/CSS works locally but breaks on GitHub Pages
  • You're using files/folders with underscores
  • You want to prevent any processing (safer choice)

2 How to Create .nojekyll

  1. In your repository, click "Add file"
  2. Click "Create new file"
  3. Type the filename: .nojekyll (yes, it starts with a dot!)
  4. Leave the file completely empty (no text needed!)
  5. Scroll down and click "Commit new file"
For simple single-file HTML apps, you usually DON'T need .nojekyll. Only add it if you encounter problems!
After adding .nojekyll, your files will be published exactly as you wrote them, with no modifications.

Updating Your Project (Copy-Paste Method)

This is the easiest way to update your website - just like you do in App Script!

1 Edit Your HTML File

  1. Go to your repository
  2. Click on index.html
  3. Click the pencil icon (top right, says "Edit this file")
  4. Select all the old code (long press and select all)
  5. Delete it
  6. Paste your new code

2 Save Your Changes

  1. Scroll to the bottom
  2. In "Commit changes" box, you can add a note (optional)
  3. Click green "Commit changes" button

3 Wait for Update

  1. Wait 1-2 minutes for GitHub to rebuild your site
  2. Check the "Actions" tab to see progress (optional)
  3. Visit your website and refresh
If you don't see changes, clear your browser cache or try opening in private/incognito mode

Common Challenges & Solutions

Challenge 1: "404 - Page Not Found"

Your website shows a 404 error when you visit it.

Solutions:

  • Make sure your file is named exactly index.html (lowercase)
  • Wait 5 minutes after enabling Pages - it takes time!
  • Check Settings → Pages - make sure it says "Your site is live at..."
  • Make sure your repository is Public, not Private

Challenge 2: "My site shows old version"

You updated your code but the website still shows the old version.

Solutions:

  • Wait 2-5 minutes for GitHub to rebuild
  • Check "Actions" tab for green checkmark (means deployment finished)
  • Try opening in incognito/private window
  • Clear all browser cache and cookies

Challenge 3: "CSS/JavaScript not working"

Your styling or scripts work locally but not on GitHub Pages.

Solutions:

  • Make sure everything is in ONE file (index.html)
  • Check for file path errors (no external file links)
  • Add .nojekyll file to your repository
  • Open browser console to see error messages
  • Make sure you're using <style> tags for CSS and <script> tags for JavaScript

Challenge 4: "100% HTML warning"

This is NOT an error! GitHub is just showing what type of code your project contains.

What it means:

  • 100% HTML = Your project is pure HTML (perfectly fine!)
  • It's just a label showing code composition
  • Single-file apps are usually 100% HTML
  • You can completely ignore this

Challenge 5: "Images not showing"

Your images work locally but disappear on GitHub Pages.

Solutions:

  • Use full URLs for images: https://example.com/image.jpg
  • Or use Base64 encoded images directly in HTML
  • Upload images to repository and use relative paths: ./image.jpg
  • Use image hosting services (Imgur, Cloudinary, etc.)

Challenge 6: "Can't find the Settings tab"

You don't see a Settings tab in your repository.

Solutions:

  • Make sure you're in YOUR repository, not someone else's
  • Settings tab is at the top, usually the last tab on the right
  • You must be the repository owner to see Settings

Challenge 7: "My code has errors"

Your HTML/CSS/JavaScript has bugs and won't work properly.

Solutions:

  • Test your code locally first (open HTML file in browser)
  • Use browser console to see error messages
  • Check for missing closing tags: </div>, </script>, etc.
  • Validate HTML at: https://validator.w3.org/
  • Check for typos in function names

Best Practices for Single-File Apps

1. File Organization

Recommended Structure
<!DOCTYPE html>
<html>
<head>
    <meta charset="UTF-8">
    <meta name="viewport" content="width=device-width, initial-scale=1.0">
    <title>Your App Name</title>
    
    <!-- All your CSS here -->
    <style>
        /* Your styles */
    </style>
</head>
<body>
    <!-- Your HTML content here -->
    
    <!-- All your JavaScript at the end -->
    <script>
        // Your code
    </script>
</body>
</html>

2. Keep It Simple

  • One file is easier to manage
  • No need for separate CSS/JS files for small projects
  • Easier to copy-paste and update

3. Test Before Publishing

  • Save your HTML file on your phone
  • Open it in a browser
  • Make sure everything works
  • Then upload to GitHub

4. Use Meaningful Names

  • Repository: tax-calculator (not project1)
  • Main file: Always index.html
  • Commit messages: "Fixed calculator bug" (not "update")

5. Comment Your Code

Good Practice
<!-- Calculator Display -->
<div id="display">0</div>

<script>
    // Function to add two numbers
    function add(a, b) {
        return a + b;
    }
</script>

6. Always Include Viewport Meta Tag

Essential for Mobile
<meta name="viewport" content="width=device-width, initial-scale=1.0">

7. Use External Libraries via CDN

Instead of downloading libraries, link to them:

Example
<!-- For charts -->
<script src="https://cdn.jsdelivr.net/npm/chart.js"></script>

<!-- For styling -->
<link href="https://cdn.jsdelivr.net/npm/bootstrap@5.3.0/dist/css/bootstrap.min.css" rel="stylesheet">

Practice Examples

Example 1: Simple Counter App

Copy this entire code
<!DOCTYPE html>
<html>
<head>
    <meta charset="UTF-8">
    <meta name="viewport" content="width=device-width, initial-scale=1.0">
    <title>Counter App</title>
    <style>
        * { margin: 0; padding: 0; box-sizing: border-box; }
        body {
            font-family: Arial;
            text-align: center;
            padding: 20px;
            background: linear-gradient(135deg, #5A67D8, #4C51BF);
            min-height: 100vh;
        }
        .container {
            background: white;
            padding: 30px;
            border-radius: 15px;
            max-width: 400px;
            margin: 50px auto;
        }
        #count {
            font-size: 60px;
            color: #5A67D8;
            margin: 20px 0;
        }
        button {
            padding: 15px 25px;
            font-size: 18px;
            margin: 8px;
            cursor: pointer;
            border: none;
            border-radius: 8px;
            background: #5A67D8;
            color: white;
            width: 80px;
        }
        button:active { background: #4C51BF; transform: scale(0.95); }
    </style>
</head>
<body>
    <div class="container">
        <h1>Counter App</h1>
        <div id="count">0</div>
        <button onclick="decrease()">-</button>
        <button onclick="reset()">Reset</button>
        <button onclick="increase()">+</button>
    </div>
    
    <script>
        let count = 0;
        function increase() { count++; updateDisplay(); }
        function decrease() { count--; updateDisplay(); }
        function reset() { count = 0; updateDisplay(); }
        function updateDisplay() {
            document.getElementById('count').innerText = count;
        }
    </script>
</body>
</html>

Example 2: Simple To-Do List

Copy this entire code
<!DOCTYPE html>
<html>
<head>
    <meta charset="UTF-8">
    <meta name="viewport" content="width=device-width, initial-scale=1.0">
    <title>To-Do List</title>
    <style>
        * { margin: 0; padding: 0; box-sizing: border-box; }
        body {
            font-family: Arial;
            background: #F7FAFC;
            padding: 20px;
        }
        .container {
            max-width: 500px;
            margin: 20px auto;
            background: white;
            padding: 20px;
            border-radius: 10px;
            box-shadow: 0 5px 20px rgba(0,0,0,0.1);
        }
        h1 { color: #5A67D8; margin-bottom: 15px; }
        input {
            width: 70%;
            padding: 12px;
            font-size: 16px;
            border: 2px solid #E2E8F0;
            border-radius: 5px;
        }
        button {
            padding: 12px 20px;
            font-size: 16px;
            background: #5A67D8;
            color: white;
            border: none;
            border-radius: 5px;
            cursor: pointer;
        }
        button:active { background: #4C51BF; }
        ul { list-style: none; margin-top: 15px; }
        li {
            padding: 12px;
            background: #F7FAFC;
            margin: 8px 0;
            border-radius: 5px;
            cursor: pointer;
        }
        li:active { background: #E2E8F0; }
        .completed {
            text-decoration: line-through;
            opacity: 0.6;
        }
    </style>
</head>
<body>
    <div class="container">
        <h1>My To-Do List</h1>
        <input type="text" id="taskInput" placeholder="Enter a task...">
        <button onclick="addTask()">Add</button>
        <ul id="taskList"></ul>
    </div>
    
    <script>
        function addTask() {
            const input = document.getElementById('taskInput');
            const task = input.value.trim();
            if (task === '') { alert('Please enter a task!'); return; }
            const li = document.createElement('li');
            li.textContent = task;
            li.onclick = function() { this.classList.toggle('completed'); };
            document.getElementById('taskList').appendChild(li);
            input.value = '';
        }
        document.getElementById('taskInput').addEventListener('keypress', function(e) {
            if (e.key === 'Enter') addTask();
        });
    </script>
</body>
</html>
Try these examples! Create a new repository for each one and see them live on GitHub Pages.

Quick Reference Checklist

Publishing a New Project:

  • Create GitHub account (if needed)
  • Click "New" repository button
  • Name your repository (lowercase, hyphens only)
  • Make it Public
  • Check "Add README file"
  • Create repository
  • Add file → Create new file
  • Name it index.html
  • Paste your HTML code
  • Commit new file
  • Go to Settings → Pages
  • Select "main" branch
  • Click Save
  • Wait 2-5 minutes
  • Visit your website URL!

Updating Your Project:

  • Go to your repository
  • Click on index.html
  • Click pencil icon
  • Select all
  • Paste new code
  • Commit changes
  • Wait 1-2 minutes
  • Refresh your browser

Troubleshooting Checklist:

  • File named index.html exactly?
  • Repository is Public?
  • Pages enabled in Settings?
  • Waited 5 minutes?
  • Refreshed browser?
  • Checked Actions tab for errors?
  • Tried incognito mode?
  • Added .nojekyll if needed?

Key URLs to Remember:

  • GitHub: https://github.com
  • Your Profile: https://github.com/yourusername
  • Your Website: https://yourusername.github.io/repo-name

Final Tips for Success

Start Simple: Your first project should be simple. Don't try to build something complex right away.
Save this HTML file on your phone! You can open it anytime in your browser to reference these instructions.
Practice makes perfect! Create 2-3 test projects to get comfortable with the process before publishing your real work.

Learning Path:

  1. Create account and first repository (today!)
  2. Publish one of the example projects above
  3. Make a simple project of your own
  4. Practice updating it several times
  5. Try more complex projects
  6. Share your projects with others!

Resources:

  • GitHub Pages Docs: https://pages.github.com
  • GitHub Help: https://docs.github.com
  • HTML Validator: https://validator.w3.org
  • Free Code Resources: https://www.freecodecamp.org
↑