Your Free Website Is Waiting on GitHub
You have a project to showcase, a portfolio to build, or a simple idea to share with the world. The thought of buying a domain, finding hosting, and wrestling with complex control panels feels overwhelming and expensive. What if you could publish a professional-looking site directly from the code you write, for absolutely no cost?
That’s the promise of GitHub Pages. This powerful feature turns your code repository into a live website, hosted by GitHub itself. It’s the secret weapon for developers, students, and creators who want a fast, reliable, and free web presence.
This guide will walk you through every step, from creating your first repository to customizing your site with themes and a custom domain. By the end, you’ll have a live website on the internet, built and managed with the tools developers use every day.
Understanding GitHub Pages and Jekyll
Before we dive into the steps, it helps to know how the magic works. GitHub Pages is a static site hosting service. It takes the HTML, CSS, and JavaScript files from a specific branch in your repository and serves them as a website.
The engine behind many GitHub Pages sites is Jekyll, a static site generator. Think of Jekyll as a smart assistant. You can give it content written in simple Markdown (a lightweight formatting language) and tell it to use a certain theme. Jekyll then automatically builds the final HTML pages, applying the layout, navigation, and styles for you.
The best part? This process is entirely automated. When you push a change to your repository, GitHub’s servers run Jekyll to rebuild your site and update it within seconds. You manage your content like code, and your website updates itself.
What You’ll Need to Get Started
You don’t need to be a coding expert, but you will need a few things ready. First, a GitHub account. If you don’t have one, head to github.com and sign up—it’s free. Second, a basic understanding of how to edit text files will be helpful. We’ll be working with simple formats.
Optionally, having Git installed on your computer gives you more control. Git is the version control system that GitHub is built on. Using the command line or a desktop app lets you work on your site locally and then sync it to GitHub. For this guide, we’ll start with the simplest method: doing everything directly on GitHub’s website.
Step-by-Step: Creating Your First GitHub Pages Site
Let’s build a site from scratch. We’ll create a repository, add a simple homepage, and activate GitHub Pages. Follow these steps closely.
Create a Special Repository
Log into your GitHub account. In the top-right corner, click the “+” icon and select “New repository”. This is where your website’s code will live.
You must name this repository in a very specific way for your personal site. The format is your-username.github.io. For example, if your GitHub username is “alexsmith”, your repository must be named “alexsmith.github.io”. This special naming convention tells GitHub that this repo holds the files for your primary user site.
Keep the repository public (private repos can use Pages, but on paid plans). You can initialize it with a README file, which is a good practice. Then, click “Create repository”.
Activate GitHub Pages in Settings
Once your repository is created, you’ll be taken to its main page. Click on the “Settings” tab in the top navigation. In the left sidebar, find and click “Pages”. This is the control center for your website.
Under the “Source” section, you’ll see a dropdown menu. Click it and select the branch you want to deploy from. For a brand-new repo, select “main”. Then, click “Save”.
Within a minute, a message will appear at the top of the Pages settings: “Your site is live at https://your-username.github.io”. Congratulations! You’ve just launched a website. It’s empty right now, but it’s live.
Create Your First Web Page
Go back to the “Code” tab of your repository. You should see your README.md file. We need to add an index.html file, which is the default homepage every web server looks for.
Click the “Add file” button and select “Create new file”. In the filename input box, type “index.html”. In the large editor area below, paste the following basic HTML structure.
<!DOCTYPE html>
<html>
<head>
<title>My GitHub Site</title>
</head>
<body>
<h1>Hello, World!</h1>
<p>My website, hosted for free on GitHub Pages.</p>
</body>
</html>
Scroll to the bottom of the page. In the “Commit new file” section, you can add a short description like “Add initial homepage”. Click the green “Commit new file” button.
Now, wait about 30-60 seconds and then open a new browser tab. Go to the URL GitHub gave you: https://your-username.github.io. You should see your “Hello, World!” page. You’ve officially published content to the web.
Making Your Site Useful with Themes and Content
A plain HTML page works, but the real power comes from using Jekyll themes. GitHub provides a curated selection of professional themes that you can apply with a single config file.
Applying a Jekyll Theme
In your repository, create another new file. Name it “_config.yml”. The underscore at the beginning is important. This YAML file holds the configuration for your Jekyll site.
Inside this file, add the following lines to choose a theme. Let’s start with a popular, clean theme called “minima”.
theme: minima
title: Your Awesome Site
description: A description of your site for search engines.
Commit this file. Next, you need to replace your index.html file with an index.md (Markdown) file that Jekyll can process. Delete the index.html file (go to the file, click the trash can icon, and commit the deletion).
Now, create a new file named “index.md”. Do not use the .html extension. Inside this file, you can write simple Markdown content.
---
layout: home
---
# Welcome to My Site
This is my homepage, built with Jekyll and the Minima theme.
- It's fast and secure.
- It's easy to update.
- It's completely free.
The three dashes at the top with “layout: home” are called front matter. They tell Jekyll to use the “home” layout from the Minima theme. The rest is Markdown, which will be converted into styled HTML.
After committing this file, your site will automatically rebuild. Refresh your live URL. You should see a dramatically different, styled website with a header, footer, and proper typography. The theme has transformed your simple text.
Adding More Pages and Posts
To add an “About” page, create a new file in your repository named “about.md”. In its front matter, specify a page layout and a title.
---
layout: page
title: About Me
---
This is the story of my site and who I am.
You can write all about your project here.
Jekyll and the Minima theme will automatically link this page in the site navigation. For a blog, you can create a “_posts” directory. Inside it, add files with a specific date format: YYYY-MM-DD-title-of-post.md. Jekyll will automatically list these as blog posts.
Common Issues and How to Fix Them
Even with a smooth process, you might hit a snag. Here are solutions to the most frequent problems.
My Site Isn’t Updating
GitHub’s build process can take up to two minutes after a commit. First, be patient. If it’s been longer, check the build status. Go to your repository, click the “Actions” tab. You should see a workflow run for “pages build and deployment”. If it has a red X, it failed. Click on it to see the error log.
The most common cause is a syntax error in your “_config.yml” file. YAML is very picky about indentation and colons. Ensure your formatting is correct. Another common issue is using an unsupported theme plugin. Stick to the themes listed in the GitHub Pages documentation for guaranteed compatibility.
My CSS or Theme Isn’t Showing
If your site reverts to plain HTML or the styling breaks, you likely have a conflict between files. Remember, when using Jekyll, your main content files should be .md (Markdown) with proper front matter, not .html. If you have an old index.html file, it will take precedence over an index.md file. Delete the .html file and ensure your .md file has the correct front matter.
Also, double-check that the theme name in your “_config.yml” is spelled exactly as listed in the docs. A typo here means Jekyll won’t apply any styling.
I Want to Use a Custom Domain
You can use your own domain name (like www.yourname.com) with your GitHub Pages site. First, in your repository’s Pages settings, type your custom domain into the “Custom domain” field and click Save. This creates a file in your repo called CNAME.
Then, you must go to your domain registrar’s website (where you bought the domain, like GoDaddy or Namecheap) and configure DNS records. You need to create either an A record pointing to GitHub’s IP addresses or a CNAME record pointing to your-username.github.io. The exact steps vary by registrar. GitHub’s documentation has detailed guides for most popular services.
Beyond the Basics: Advanced Workflows
Once you’re comfortable, you can unlock more power. Using Git on your local computer allows you to write posts, test changes, and preview your site before publishing.
Install Git, clone your repository to your computer, and install Jekyll locally. This lets you run `bundle exec jekyll serve` to see your site at localhost:4000. Every change you save will instantly refresh the local preview. This is the professional workflow.
You can also fork existing website templates or themes from other GitHub users. Explore the “Pages” topic on GitHub to find thousands of ready-to-use portfolio, blog, and documentation sites. Forking one gives you a complete, working site that you can then customize with your own content.
Your Free Web Presence Is Ready
You now have a live website, hosted on one of the most reliable platforms on the internet, without spending a dollar. The process of updating it is as simple as editing a text file and committing a change. You’ve learned the core workflow: repository, configuration, Markdown content, and the automatic build.
The next step is to make it yours. Experiment with different themes from the GitHub Pages settings. Add an “About” page with your story. Create a post in the “_posts” folder to share an update. The structure is in place.
This approach scales with you. What starts as a simple homepage can grow into a technical blog, a project portfolio, or full documentation for your software. You control the content, the style, and the platform. Start building, and let your ideas find their audience.
