The Complete Guide

Creating a GitHub Pages Website

Host static sites - or full Jekyll builds - for free, forever.

No server required HTTPS by default Custom domains supported
Commands for Only terminal snippets change.

What is GitHub Pages?

GitHub Pages is a free static site hosting service provided by GitHub. It takes HTML, CSS, and JavaScript files directly from a repository, optionally runs them through a build process (like Jekyll), and publishes the result as a live website - complete with HTTPS.

Key Features

  • Free hosting for static websites
  • Custom domain support (optional)
  • SSL/HTTPS encryption enabled by default
  • Deep Git integration for version control
  • Jekyll support built into the platform
  • Unlimited bandwidth for reasonably-sized sites
  • GitHub Actions for custom build pipelines
Types of GitHub Pages
  • User / Organization site - username.github.io
  • Project site - username.github.io/repository
  • Custom domain - your own domain name
Limitations

GitHub Pages cannot run:

  • Server-side languages (PHP, Ruby, Python, Node)
  • Databases or dynamic server logic
  • Server-side authentication
  • Heavy background processing
  • Sites larger than 1 GB (soft limit)
  • More than 100 GB bandwidth/month (soft limit)
Perfect For
  • Personal portfolios
  • Project documentation
  • Blogs (with Jekyll)
  • Resume websites
  • Educational resources
  • Product landing pages
  • Small business sites

Prerequisites

Before you start, make sure you have the following covered:

GitHub Account
  1. Go to github.com
  2. Click Sign up
  3. Choose a username (this becomes part of your URL)
  4. Verify your email address

Your username becomes part of your GitHub Pages URL: username.github.io

Basic Knowledge
  • Basic HTML and CSS (JavaScript is helpful but not required)
  • Creating and editing text files
  • Basic Git concepts (helpful but optional)
  • File organisation & folder structure

New to Git? Don't worry - we cover everything you need.

Tools
  • A code editor (VS Code recommended)
  • Git installed (required for Path B)
  • A modern browser
  • Ruby + Bundler (for Path B only)

On Windows, install Git for Windows - it ships with Git Bash, which runs the Linux-style commands in this guide verbatim.

macOS and Linux already have a usable terminal, so nothing extra is required.

Choose Your Path

There are two ways to build a GitHub Pages site, and you can mix them:

Path A

Simple Static Site

Plain HTML, CSS and JavaScript committed directly. Fastest to set up, no build step, no local tooling required.

  • Perfect for landing pages and small sites
  • No Ruby or Node needed
  • Live in under 5 minutes
Jump to Path A

Path A - Simple Static Site

Follow these steps to have a live website in under five minutes.

  1. Create a new repository

    Create a public repository named exactly:

    username.github.io

    Replace username with your GitHub username. The naming convention is what tells GitHub to serve the repo as your root site.

    Important: On free accounts the repository must be public for Pages to work.
  2. Initialise with a README

    • Tick Add a README file
    • (Optional) Choose a licence
    • Click Create repository
  3. Add your first HTML file

    Create a file named index.html in the repository root:

    index.html
    <!DOCTYPE html>
    <html lang="en">
    <head>
        <meta charset="UTF-8">
        <meta name="viewport" content="width=device-width, initial-scale=1">
        <title>My GitHub Pages Site</title>
        <style>
            body {
                font-family: system-ui, sans-serif;
                max-width: 800px;
                margin: 0 auto;
                padding: 2rem;
                line-height: 1.6;
                color: #24292e;
            }
            h1 { color: #0366d6; }
        </style>
    </head>
    <body>
        <h1>Hello World!</h1>
        <p>My GitHub Pages site is live.</p>
        <p>Visit: <code>https://username.github.io</code></p>
    </body>
    </html>

    You can add it directly on GitHub: Add file → Create new file, paste the code, then commit.

  4. Enable GitHub Pages

    In your repository, go to Settings → Pages:

    • Under Source, choose Deploy from a branch
    • Select the main branch
    • Select the / (root) folder
    • Click Save
    Deployment takes 1-2 minutes. You'll see “Your site is live at…” when it's ready.
  5. Visit your site

    Open a new tab and go to:

    https://username.github.io

    You should see your Hello World page in all its glory.

    Pro tip: Modern browsers will add https:// for you - you can just type username.github.io.
  6. Customise it

    Add more files to your repository:

    • style.css - external stylesheet
    • script.js - interactivity
    • about.html - extra pages
    • images/ - image assets

    Link your CSS in HTML like so:

    <link rel="stylesheet" href="style.css">
  7. Add a splash of JavaScript

    Create script.js:

    script.js
    document.addEventListener('DOMContentLoaded', () => {
        const button  = document.getElementById('demoButton');
        const message = document.getElementById('demoMessage');
    
        button.addEventListener('click', () => {
            message.textContent = 'Button clicked! JavaScript is working.';
            message.style.color = '#28a745';
    
            button.style.transform = 'scale(0.95)';
            setTimeout(() => { button.style.transform = 'scale(1)'; }, 150);
        });
    });

    Then include it in your HTML just before </body>:

    <p id="demoMessage">Click the button to test JavaScript.</p>
    <button id="demoButton">Click Me!</button>
    <script src="script.js"></script>

Quick sanity check

From a terminal, verify your site is live. Note that Windows PowerShell aliases curl to Invoke-WebRequest, so use curl.exe to get the real thing.

curl.exe -I https://username.github.io
curl -I https://username.github.io

Look for HTTP/2 200. If you see that, you're good to go.

Path B - Jekyll-Powered Site

Jekyll is a static site generator written in Ruby. It's built into GitHub Pages, so you don't even need to run a build step yourself - GitHub will build your site automatically when you push. The benefit is that you can use layouts, includes, data files, Markdown, and Liquid templating to avoid repeating yourself.

Two ways to run Jekyll: locally (best for development - you see changes instantly) or entirely through GitHub's hosted builder (fine for simple sites). We cover both.

1. Install Jekyll locally

Jekyll needs Ruby. Follow the guide for your operating system:

Windows
  1. Install RubyInstaller for Windows (Ruby+Devkit 3.x)
  2. Run the installer and keep ridk install ticked
  3. In the popup, choose option 3 (MSYS2 + MINGW)
  4. Open a new terminal and run:
gem install jekyll bundler

If gem isn't recognised, your terminal was opened before the installer finished. Close it, open a fresh one, and try again.

macOS / Linux

Use your system package manager, then install the gems:

# macOS (with Homebrew)
brew install ruby
gem install jekyll bundler

# Ubuntu / Debian
sudo apt install ruby-full build-essential
gem install jekyll bundler

On some distros gem install needs sudo, or you can install into your home directory with gem install --user-install.

Verify the install (this works the same on every platform):

jekyll -v
bundle -v

2. Create your project

Scaffold a new Jekyll site (or create the folders by hand):

jekyll new my-site --blank
cd my-site

The --blank flag gives you a bare scaffold - no theme, no boilerplate - which is ideal if you want full control over the markup.

Here's a recommended structure. You don't need every folder - start with the ones you need:

my-site/
├── _data/                 # JSON / YAML / CSV files for templates
│   └── navigation.yml
├── _includes/             # Reusable partials
│   ├── head.html
│   ├── header.html
│   └── footer.html
├── _layouts/              # Page templates
│   └── default.html
├── _posts/                # Blog posts (Markdown)
├── _sass/                 # SCSS partials (optional)
├── assets/
│   ├── css/
│   │   └── style.css
│   ├── js/
│   │   └── scripts.js
│   └── images/
├── _config.yml            # Site config
├── Gemfile
├── Gemfile.lock
├── .gitignore
├── index.html             # Home page
└── README.md

Create the required files at the project root:

Gemfile
source 'https://rubygems.org'

gem 'jekyll', '~> 4.3'
gem 'jekyll-sitemap'
gem 'jekyll-seo-tag'
gem 'jekyll-relative-links'
gem 'webrick'
gem 'wdm', '>= 0.1.0', platforms: [:mingw, :x64_mingw, :mswin]
gem 'tzinfo'
gem 'tzinfo-data'
Windows note: wdm, tzinfo and tzinfo-data exist to keep file-watching and time zones working correctly on Windows and JRuby. They are harmless on other platforms because the gems are platform-gated.
.gitignore
_site/
.sass-cache/
.jekyll-cache/
.jekyll-metadata
.bundle/
vendor/
.DS_Store

Install the gems:

bundle install

3. Configure _config.yml

This file is the control centre of your Jekyll site. Every time you change it, you must restart the local server.

_config.yml
# ---------------------------------------------------------------------------
# Identity
# ---------------------------------------------------------------------------
title: My Jekyll Site
tagline: "Built with Jekyll, hosted on GitHub Pages"
description: A site built with Jekyll and hosted for free on GitHub Pages.

url: "https://username.github.io"   # production domain - no trailing slash
baseurl: ""                         # "" for user sites, "/repo" for project sites

lang: en-NZ
locale: en_NZ
og_locale: en_NZ
timezone: Pacific/Auckland

# ---------------------------------------------------------------------------
# SEO / social metadata (consumed by jekyll-seo-tag)
# ---------------------------------------------------------------------------
title_separator: "|"
twitter:
  card: summary_large_image

author:
  name: Your Name
  url: https://github.com/username

favicon: /assets/images/favicon.ico

# ---------------------------------------------------------------------------
# Single source of truth for outbound links
# Referenced in templates as {{ site.links.github }} etc.
# ---------------------------------------------------------------------------
links:
  email: you@example.com
  github: https://github.com/username
  discord: https://discord.gg/xxxxxxxx

# ---------------------------------------------------------------------------
# Build behaviour
# ---------------------------------------------------------------------------
incremental: true

markdown: kramdown
kramdown:
  input: GFM
  hard_wrap: false
  toc_levels: 2..6
  syntax_highlighter: rouge   # or: nil to render plain <code> blocks

sass:
  style: compressed
  quiet_deps: true

permalink: pretty

# ---------------------------------------------------------------------------
# Plugins (GitHub Pages whitelist)
# ---------------------------------------------------------------------------
plugins:
  - jekyll-seo-tag
  - jekyll-sitemap
  - jekyll-feed
  - jekyll-relative-links

relative_links:
  enabled: true
  collections: true

# ---------------------------------------------------------------------------
# Keep build/dev files out of the generated site
# ---------------------------------------------------------------------------
exclude:
  - Gemfile
  - Gemfile.lock
  - node_modules
  - vendor
  - README.md
  - LICENSE
  - run.bat

# ---------------------------------------------------------------------------
# Collections
# ---------------------------------------------------------------------------
collections:
  projects:
    output: true
    permalink: /projects/:path/

# ---------------------------------------------------------------------------
# Front matter defaults - apply top to bottom, later rules win
# ---------------------------------------------------------------------------
defaults:
  - scope:
      path: ""
    values:
      layout: "default"
      image:
        path: /assets/images/social-card.png
        alt: "My Jekyll Site"

  - scope:
      path: ""
      type: posts
    values:
      layout: post
      permalink: /blog/:year/:month/:day/:title/

  - scope:
      path: "pages"
    values:
      permalink: /pages/:basename/
Important: Your url and baseurl must match how GitHub serves the site. For a user site (username.github.io), baseurl should be empty. For a project site (username.github.io/repo), set it to "/repo".

What each block actually does

  • url + baseurl - the two values every absolute link is built from. Getting these wrong is the single most common cause of "my CSS works locally but 404s on Pages".
  • locale / lang / og_locale - lang sets the <html lang> attribute, locale and og_locale feed SEO tags. The xx_YY convention matters for OpenGraph.
  • timezone - an IANA identifier (Pacific/Auckland, Europe/London). Affects every Liquid date: filter, including the copyright year in your footer.
  • title_separator + twitter: card - formatting for the tags that {% seo %} emits. Set once, forget forever.
  • links: - a single map of every outbound URL. Change a Discord invite in one place instead of hunting through twenty templates.
  • kramdown.hard_wrap - false for hand-wrapped prose guides (single newlines are ignored); true when you want a single newline to become a <br>.
  • kramdown.syntax_highlighter: nil - renders fenced code as plain <code> blocks with no colouring. Use rouge when you want highlighting.
  • sass.style: compressed - minifies your SCSS output. quiet_deps silences deprecation warnings from third-party stylesheets.
  • permalink: pretty - produces /about/ instead of /about.html.
  • exclude: - nothing here is secret (it's all still in the repo), but it keeps Gemfile, node_modules/, vendor/ and local scripts out of the published _site/.
  • defaults: - front matter applied by scope. Rules are evaluated top to bottom and the last matching rule wins, so put your broadest rule first and your most specific rule last.

Plugin whitelist: jekyll-seo-tag, jekyll-sitemap, jekyll-feed, jekyll-relative-links and friends are all on GitHub's approved list. If you build with GitHub Actions instead (see below), that list stops applying and you can use any plugin you like.

If you're publishing a blog, add jekyll-feed to the plugin list - it generates /feed.xml automatically. On a project repo you may also want repository: and github_username: at the top level, which some plugins and themes read when building absolute GitHub links.

4. Layouts & includes

Layouts are the shells your pages get wrapped in. Includes are reusable snippets you drop inside layouts (or pages). Together they eliminate nearly all repetition.

_layouts/default.html
<!DOCTYPE html>
<html lang="{{ site.lang | default: 'en' }}">
<head>
  {% include head.html %}
</head>
<body>
  <a class="skip-link" href="#main-content">Skip to content</a>

  <header class="header">{% include header.html %}</header>

  <main id="main-content">{{ content }}</main>

  {% include footer.html %}
</body>
</html>
_includes/head.html
<meta charset="UTF-8">
<meta name="viewport" content="width=device-width, initial-scale=1">
<title>{{ page.title | default: site.title }}</title>
<meta name="description" content="{{ page.description | default: site.description }}">

{% seo %}

<link rel="stylesheet" href="{{ '/assets/css/style.css' | relative_url }}">
_includes/header.html
<nav class="main-nav">
  <a href="{{ '/' | relative_url }}">Home</a>
  <a href="{{ '/about/' | relative_url }}">About</a>
  <a href="{{ '/blog/' | relative_url }}">Blog</a>
</nav>
_includes/footer.html
<footer>
  <p>&copy; {{ site.time | date: '%Y' }} {{ site.title }}</p>
</footer>

Now any page can opt into the layout via front matter:

index.html
---
layout: default
title: Home
---

<h1>Welcome</h1>
<p>This page is rendered inside the default layout.</p>
Liquid tip: {{ content }} is where each page's body gets injected. {% include file.html %} pulls in a partial from _includes/.

5. Data files

Any JSON, YAML, or CSV file inside _data/ is automatically available in your templates. This is perfect for navigation menus, team lists, product catalogues, or any content you'd rather keep separate from markup.

_data/navigation.yml
- title: Home
  url: /
- title: About
  url: /about/
- title: Blog
  url: /blog/
- title: Contact
  url: /contact/

Loop through it anywhere:

<ul>
  {% for item in site.data.navigation %}
    <li><a href="{{ item.url | relative_url }}">{{ item.title }}</a></li>
  {% endfor %}
</ul>
Real-world example: this site's Maps page reads every release from _data/releases.json, which is generated by a GitHub Actions workflow. Zero API calls from the visitor's browser.

6. Collections

Collections let you group related documents (projects, recipes, team members) and give them their own templates - a bit like pages, but managed together.

_config.yml (add)
collections:
  projects:
    output: true
    permalink: /projects/:path/

Create _projects/my-first-project.md:

---
layout: project
title: My First Project
---

A short description of the project goes here.

Render it from anywhere:

{% for project in site.projects %}
  <a href="{{ project.url | relative_url }}">{{ project.title }}</a>
{% endfor %}
Permalink patterns: /:collection/:path/ keeps every collection neatly namespaced, while /:name/ uses the filename. Pair a collection with a scoped entry under defaults: so every document in it gets the right layout automatically.

7. Local development

Jekyll ships with a built-in dev server with live reload:

bundle exec jekyll serve --livereload

Then open http://127.0.0.1:4000. Every saved change appears automatically.

Handy flags

--livereload            # auto-refresh the browser
--drafts                # include files in _drafts/
--future                # include posts dated in the future
--unpublished           # include posts marked published: false
--host 0.0.0.0          # expose the server to your LAN
--port 4001             # use a different port
--baseurl ""            # override baseurl temporarily

These flags are identical on every platform - only the way you launch them tends to differ. A small launcher script saves a lot of typing:

run.bat
@echo off
cd /d "%~dp0"

echo Cleaning site...
call bundle exec jekyll clean || exit /b

echo Starting Jekyll server on 127.0.0.1:4000 with live reload...

start cmd /k "cd /d "%~dp0" && bundle exec jekyll serve --livereload --host 127.0.0.1 --baseurl="

echo Waiting for server to start...
set "PORT=4000"
set "TIMEOUT=30"

for /l %%i in (1,1,%TIMEOUT%) do (
    timeout /t 1 /nobreak >nul
    netstat -an | find ":%PORT% " | find "LISTENING" >nul && goto :ready
)

echo WARNING: Server not responding after %TIMEOUT% seconds. Opening browser anyway.

:ready
start http://127.0.0.1:4000/
run.sh
#!/usr/bin/env bash
set -e
cd "$(dirname "$0")"

if ! command -v bundle >/dev/null 2>&1; then
    echo "Bundler not found. Install it first:"
    echo "    gem install jekyll bundler"
    exit 1
fi

bundle exec jekyll clean

echo
echo "Starting Jekyll with live reload."
echo "Local address: http://127.0.0.1:4000"
echo "Press Ctrl+C to stop."
echo

bundle exec jekyll serve --livereload --open-url

Double-click run.bat, or run it from any terminal in the project folder - it switches to its own directory first, so the working directory doesn't matter. The script cleans the previous build, launches Jekyll in a separate console window, polls the port for up to 30 seconds, then opens your browser once the server is actually listening. Add run.bat to exclude: in _config.yml so it never ends up in _site/.

Make it executable once with chmod +x run.sh, then run ./run.sh. Add run.sh to exclude: in _config.yml so it never ends up in _site/.

Deploying with GitHub Actions

The easiest way to publish a Jekyll site is to let GitHub build it for you. You don't need to commit the generated _site/ folder - a workflow builds it on every push and deploys it.

  1. Enable Pages

    Go to Settings → Pages and set Source to GitHub Actions.

  2. Add the deploy workflow

    Create .github/workflows/jekyll.yml:

    .github/workflows/jekyll.yml
    name: Build and Deploy Jekyll Site
    
    on:
      push:
        branches: ["main"]
      workflow_dispatch: {}
    
    permissions:
      contents: read
      pages: write
      id-token: write
    
    concurrency:
      group: "pages"
      cancel-in-progress: false
    
    jobs:
      build:
        runs-on: ubuntu-latest
        steps:
          - name: Checkout
            uses: actions/checkout@v4
    
          - name: Setup Ruby
            uses: ruby/setup-ruby@v1
            with:
              ruby-version: "3.2"
              bundler-cache: true
    
          - name: Setup Pages
            id: pages
            uses: actions/configure-pages@v5
    
          - name: Build with Jekyll
            run: bundle exec jekyll build --baseurl "${{ steps.pages.outputs.base_path }}"
            env:
              JEKYLL_ENV: production
    
          - name: Upload artifact
            uses: actions/upload-pages-artifact@v3
            with:
              path: "_site"
    
      deploy:
        environment:
          name: github-pages
          url: ${{ steps.deployment.outputs.page_url }}
        runs-on: ubuntu-latest
        needs: build
        steps:
          - name: Deploy to GitHub Pages
            id: deployment
            uses: actions/deploy-pages@v4
  3. Push and watch

    git add .
    git commit -m "Add Jekyll site"
    git push origin main

    Open the Actions tab on GitHub to follow the build. When it's green, your site is live.

    Windows tip: if Git reports “LF will be replaced by CRLF” warnings, that's normal and harmless. If you'd rather not see them, add a .gitattributes file with * text=auto eol=lf.
  4. Going further: a data-fetching workflow

    You can also use Actions to generate data that Jekyll reads at build time. This project does exactly that - a scheduled workflow pulls GitHub Releases into _data/releases.json, then triggers a rebuild.

    .github/workflows/fetch-releases.yml (excerpt)
    on:
      schedule:
        - cron: "0 */6 * * *"        # every 6 hours
      release:
        types: [published, edited]
      workflow_dispatch: {}
    
    permissions:
      contents: write
    
    jobs:
      fetch:
        runs-on: ubuntu-latest
        steps:
          - uses: actions/checkout@v4
            with: { ref: main }
          - uses: actions/github-script@v7
            with:
              script: |
                const fs = require('fs');
                const releases = await github.paginate(
                  github.rest.repos.listReleases,
                  { owner: context.repo.owner, repo: context.repo.repo, per_page: 100 }
                );
                fs.mkdirSync('_data', { recursive: true });
                fs.writeFileSync('_data/releases.json',
                  JSON.stringify(releases, null, 2));
          - run: |
              git config user.name "github-actions[bot]"
              git config user.email "github-actions[bot]@users.noreply.github.com"
              git add _data/releases.json
              git diff --staged --quiet || git commit -m "chore: update data"
              git push
Why not just build locally? You can - commit the _site/ folder and point Pages at it. But Actions gives you reproducible builds, no local Ruby required, and a clean repo. It's the recommended path.

Using a Custom Domain

You can serve your site from your own domain (e.g. yourdomain.com) instead of the default *.github.io address.

Step 1 - Buy a domain
  • Namecheap
  • Cloudflare Registrar
  • Porkbun
  • Google Domains / Squarespace

Prices are typically $10-15/year for a .com.

Step 2 - Add a CNAME file

In your repo root, create a file called CNAME (no extension) containing just your domain:

yourdomain.com

Or, if you want the www subdomain:

www.yourdomain.com
Step 3 - Configure DNS

At your registrar's DNS panel, add:

A records pointing to GitHub's IPs:

185.199.108.153
185.199.109.153
185.199.110.153
185.199.111.153

…or a CNAME record for www pointing to:

username.github.io
HTTPS: GitHub will automatically provision a Let's Encrypt certificate for your custom domain. This can take up to 24 hours after DNS propagates. Enable Enforce HTTPS in Settings → Pages once it's available.

Verify it worked

# Should return the GitHub Pages IPs
nslookup yourdomain.com

# PowerShell-native alternative with more detail
Resolve-DnsName yourdomain.com

# Should return a 200
curl.exe -I https://yourdomain.com

# Should show the TLS certificate details
curl.exe -vI https://yourdomain.com
# Should return the GitHub Pages IPs
dig +short yourdomain.com

# Should return a 200
curl -I https://yourdomain.com

# Should return your SSL certificate details
openssl s_client -connect yourdomain.com:443 -servername yourdomain.com < /dev/null

Common Issues & Troubleshooting

404 - Page Not Found

Solutions:

  • Repo must be named username.github.io (for user sites)
  • Pages must be enabled under Settings → Pages
  • You need an index.html in the published folder
  • Wait 1-2 minutes after first enabling Pages
  • Check the Actions tab for build failures
CSS / JS Not Loading

Solutions:

  • Paths are case-sensitive on Linux servers
  • Use relative_url in Jekyll: {{ '/assets/css/style.css' | relative_url }}
  • Hard-refresh the browser (Ctrl+F5 / Cmd+Shift+R)
  • Open DevTools (F12) → Console for errors

Windows filesystems are case-insensitive. A file saved as Style.css will load fine locally and then 404 on GitHub Pages. Rename files in lowercase from the start.

Updates Not Showing

Solutions:

  • Builds take 1-2 minutes - wait and refresh
  • Check the Actions tab for the latest run
  • Clear browser cache or try an incognito window
  • Confirm your branch is the one Pages is deploying from
Jekyll Build Failures

Common causes and how to fix them:

  • YAML syntax error - check _config.yml and front matter for stray colons or tabs
  • Liquid tag mismatch - every {% if %} needs a matching {% endif %}
  • Missing plugin - only plugins in this list are allowed with GitHub's hosted builder
  • Case-sensitive paths - Layouts/ and layouts/ are not the same thing

Using the Actions workflow above sidesteps the plugin whitelist entirely, because the build runs on your own runner rather than GitHub's Pages builder.

Custom Domain Not Working
  • DNS propagation can take up to 48 hours
  • Confirm the CNAME file is in the published folder
  • Check for old A records pointing elsewhere
  • Ensure you don't have conflicting AAAA records
  • Re-run your DNS lookup to confirm the IPs have updated
Slow or Stale Builds
  • Enable incremental: true in _config.yml (local only)
  • Cache gems with bundler-cache: true in Actions
  • Use concurrency in workflows to cancel outdated runs
  • Keep _site/ out of git via .gitignore

Debugging cheat-sheet

# Is the site reachable?
curl.exe -I https://username.github.io

# Where does the DNS point?
nslookup yourdomain.com
Resolve-DnsName yourdomain.com

# What certificate is being served?
curl.exe -vI https://yourdomain.com

# What does the local build produce?
bundle exec jekyll build --trace

# Serve with verbose output
bundle exec jekyll serve --verbose
# Is the site reachable?
curl -I https://username.github.io

# Where does the DNS point?
dig +short yourdomain.com

# What certificate is being served?
openssl s_client -connect yourdomain.com:443 -servername yourdomain.com < /dev/null

# What does the local build produce?
bundle exec jekyll build --trace

# Serve with verbose output
bundle exec jekyll serve --verbose

Prefer the Unix tools? Git Bash (installed with Git for Windows) gives you dig, openssl and a real curl - the Linux column above works verbatim inside it.

Resources & Further Learning

Next Steps

Advanced Features
  • Use Jekyll for blogging (_posts/)
  • Add Google Analytics or Plausible
  • Wire up a contact form (Formspree, Netlify Forms)
  • Create a custom 404.html
  • Add an RSS feed via jekyll-feed
  • Enable jekyll-seo-tag and jekyll-sitemap
  • Turn the site into a PWA with a manifest.json, icon set, and a service worker
Development Tips
  • Always work on a branch, merge via PR
  • Test locally before pushing
  • Keep _site/ out of Git
  • Use GitHub Actions for CI/CD
  • Learn responsive design with clamp() and CSS grid
  • Prefer relative_url filters to hard-coded paths
  • Route every outbound link through site.links so URLs change in one place