Static sites are fast, secure, and surprisingly easy to set up—especially when you pair Jekyll with GitHub Pages. In this guide we’ll walk through every step, from installing Jekyll on your computer to seeing your brand‑new site live on the web. No prior Ruby or Git experience is required; just follow the instructions and you’ll have a polished site in under an hour.
What You’ll Need
- A computer running macOS, Linux, or Windows 10/11
- Administrative access to install software
- A free GitHub account
- Basic familiarity with the command line (we’ll show every command)
- Internet connection for downloading packages and pushing code
Step 1: Install Ruby, RubyGems, and Bundler
Jekyll is a Ruby gem, so you need a working Ruby environment first. On macOS you can use Homebrew, on Ubuntu apt, and on Windows the RubyInstaller.
macOS:
brew install ruby
export PATH="$(brew --prefix ruby)/bin:$PATH"
Ubuntu/Debian:
sudo apt update
sudo apt install ruby-full build-essential zlib1g-dev
Windows (run PowerShell as Administrator):
choco install ruby
refreshenv
After Ruby is installed, verify the version (Jekyll requires Ruby ≥ 2.7):
ruby -v
Now install Bundler, which will manage Jekyll’s dependencies:
gem install bundler
If you see permission errors, add sudo on macOS/Linux or run PowerShell as admin on Windows.
Step 2: Install Jekyll and Create a New Site
With Bundler ready, install Jekyll globally:
gem install jekyll
Now create a fresh Jekyll project called my‑blog (feel free to pick any name):
jekyll new my-blog
cd my-blog
This command scaffolds a complete site structure, including a default theme, sample posts, and a configuration file (_config.yml). Open the folder in your favorite editor to explore the files.
Step 3: Preview the Site Locally
Before pushing anything to GitHub, make sure the site builds correctly on your machine. Use Bundler to install the gems defined in the project’s Gemfile and start the development server:
bundle install
bundle exec jekyll serve
The server will be available at http://localhost:4000. Open that URL in a browser; you should see the default Jekyll theme with a “Hello World!” post. If you make changes to markdown files, the server automatically reloads—great for quick iteration.
Step 4: Initialize a Git Repository and Push to GitHub
GitHub Pages works by serving the contents of a Git repository. First, create a new empty repository on GitHub (click “New” → give it a name, e.g., my-blog, leave it public, and **don’t** initialize with a README).
Back in your terminal, initialize Git, add the remote, and push the initial commit:
git init
git add .
git commit -m "Initial Jekyll site"
git branch -M main
git remote add origin https://github.com/your‑username/my‑blog.git
git push -u origin main
Replace your‑username with your actual GitHub handle. After the push finishes, you’ll see the code on GitHub but the site won’t be live yet.
Step 5: Configure GitHub Pages to Use the Correct Branch
Navigate to your repository’s Settings → Pages. Under “Source”, select the main branch and the / (root) folder, then click “Save”. GitHub will start a build; within a minute you’ll get a URL like https://your‑username.github.io/my‑blog/. Click it to verify the site is live.
If you prefer the gh‑pages branch (common for project sites), you can create it and push the compiled _site folder there. For a beginner’s personal site, the root of main is the simplest approach.
Step 6: Customize Your Site’s Appearance
Now that the basics work, it’s time to make the site yours. Open _config.yml and edit the following fields:
title: My Awesome Blog
email: [email protected]
description: >- # this means to ignore newlines until "baseurl"
A blog about tech, travel, and life.
baseurl: "" # the subpath of your site, e.g. "/blog"
url: "https://your-username.github.io" # the base hostname & protocol
Save the file, then run bundle exec jekyll serve again to see the changes. You can also replace the default theme by adding a theme: line (e.g., theme: minima) or by installing a third‑party theme via Gemfile.
To add a new page, create a markdown file in the root, for example about.md:
---
layout: page
title: About Me
permalink: /about/
---
Write a short bio here.
Commit and push the new file; GitHub Pages will rebuild automatically.
Step 7: Enable a Custom Domain (Optional)
If you own a domain like example.com, you can point it to your GitHub Pages site. In the repository, create a file named CNAME (no extension) containing only your domain name:
example.com
Then, at your domain registrar, add an A record pointing to GitHub’s IP addresses (185.199.108.153, .109, .110, .111) or a CNAME record pointing to your-username.github.io. DNS propagation may take up to 48 hours, but once it’s live, your site will be accessible via the custom domain.
Common Mistakes to Avoid
1. Forgetting to run bundle install after cloning. The Gemfile lists required gems; without installing them the site won’t build.
2. Pushing the _site folder instead of the source. GitHub Pages builds the site for you; committing the generated _site can cause duplicate builds or broken URLs.
3. Using the wrong branch for Pages. The default for user/organization sites is the main (or master) branch’s root. Selecting gh‑pages without actually having that branch will result in a 404.
4. Ignoring the baseurl setting. When your site lives under a subfolder (e.g., github.io/project/), you must set baseurl accordingly; otherwise links break.
5. Not committing the CNAME file. If you add a custom domain but forget to push the CNAME, GitHub won’t serve the domain correctly.
Tips and Tricks
• Use a local development theme. Add gem "minima" to your Gemfile and run bundle install to experiment with different looks without altering the live site.
• Leverage plugins. GitHub Pages supports a curated set of plugins (e.g., jekyll-seo-tag, jekyll-sitemap). Add them to _config.yml and to the Gemfile to improve SEO and navigation.
• Write posts in Markdown. Jekyll automatically converts .md files in the _posts directory to HTML. Use the front matter to set title, date, categories, and tags.
• Enable drafts. Place unfinished posts in _drafts and preview them with bundle exec jekyll serve --drafts. Drafts never get published unless you move them to _posts.
• Automate deployment. Connect your repository to a CI service like GitHub Actions to run jekyll build on every push, ensuring the site always compiles cleanly.
Frequently Asked Questions
Do I need to pay for GitHub Pages?
No. GitHub Pages is free for public repositories. Private repositories are also supported with a free GitHub account, but they require a paid plan for Pages.
Can I use Jekyll on Windows?
Absolutely. Install Ruby via the RubyInstaller, then follow the same gem commands. The only hiccup is occasional native‑extension compilation errors; installing the MSYS2 toolchain (offered during RubyInstaller setup) resolves most issues.
Why does my site show a 404 after I push changes?
Common causes are an incorrect baseurl setting, forgetting to push the CNAME file for a custom domain, or selecting the wrong branch in the Pages settings. Double‑check those three items and re‑trigger a build by committing a trivial change.
Conclusion
Building a static site with Jekyll and hosting it on GitHub Pages gives you a powerful, low‑maintenance web presence. By following the steps above—installing Ruby, creating a Jekyll project, pushing to GitHub, and configuring Pages—you’ll have a live site in minutes. From here you can explore themes, plugins, and custom domains to make the site truly yours. Happy coding, and enjoy the speed and security that static sites provide!
Photo by Portraits of Modern Dairy on Unsplash
