Jekyll Blog Setup Guide: From Zero to Live in 30 Minutes (2026)

Jekyll is the most popular static site generator for personal blogs — and for good reason. It’s free to host on GitHub Pages, blazing fast, and once set up, publishing a new post takes under a minute. This guide takes you from zero to a live blog in 30 minutes.

What You’ll Build

By the end of this guide you will have:

A Jekyll blog running locally
A chosen theme applied
Your first post published
The site live on GitHub Pages at yourusername.github.io

Step 1: Install Ruby and Jekyll (5 minutes)

Jekyll is a Ruby gem, so you need Ruby installed first.

macOS

macOS ships with an old Ruby version. Use rbenv instead:

brew install rbenv ruby-build
rbenv install 3.2.0
rbenv global 3.2.0
gem install jekyll bundler

Windows

Download and install RubyInstaller. Then:

gem install jekyll bundler

Linux (Ubuntu/Debian)

sudo apt-get install ruby-full build-essential
gem install jekyll bundler

Verify your installation:

jekyll -v
# jekyll 4.3.x

Step 2: Create a New Jekyll Site (2 minutes)

jekyll new my-blog
cd my-blog
bundle exec jekyll serve

Visit http://localhost:4000 — you’ll see your new blog with the default Minima theme.

Step 3: Choose and Install a Theme (5 minutes)

The default Minima theme is fine to start, but here are better options depending on your goals:

Goal	Recommended Theme
Developer tech blog	Chirpy
Minimal writing focus	Lanyon or Hyde
Feature-rich blog	Minimal Mistakes
Beautiful cover images	Huxpro
Beginner-friendly	Jekyll Now

Installing Chirpy (example)

# Option 1: Use the Chirpy starter template
git clone https://github.com/cotes2020/chirpy-starter my-blog
cd my-blog
bundle install
bundle exec jekyll serve

Step 4: Configure Your Blog (5 minutes)

Open _config.yml and update the key settings:

title: "My Blog"
tagline: "Writing about code, design, and ideas"
description: "A personal blog by Your Name"

url: "https://yourusername.github.io"
baseurl: ""

author:
  name: "Your Name"
  email: "you@example.com"

# Social links
github_username: yourusername
twitter_username: yourusername

# Build settings
lang: en
timezone: America/New_York

Save the file and your local preview updates automatically.

Step 5: Write Your First Post (5 minutes)

Jekyll posts live in the _posts/ directory. Create a new file named YYYY-MM-DD-your-post-title.md:

touch _posts/2026-06-01-my-first-post.md

Open the file and add:

---
title: "My First Jekyll Post"
date: 2026-06-01
categories: [Blogging]
tags: [jekyll, first-post]
---

Welcome to my blog! This is my first post written in Markdown.

## Why I Started This Blog

Here's my story...

## What I'll Write About

- Code and development
- Design tips
- Things I'm learning

Save it — your post appears at http://localhost:4000 immediately.

Step 6: Add Pages (2 minutes)

Create an About page:

touch _pages/about.md

---
title: "About"
permalink: /about/
---

Hi, I'm Your Name. I write about code, design, and ideas.

Step 7: Deploy to GitHub Pages (5 minutes)

Step 7a: Create a GitHub repository

Go to github.com/new and create a repository named yourusername.github.io.

Step 7b: Push your blog

cd my-blog
git init
git add .
git commit -m "Initial commit"
git branch -M main
git remote add origin https://github.com/yourusername/yourusername.github.io.git
git push -u origin main

Step 7c: Enable GitHub Pages

Go to your repository → Settings → Pages → set source to Deploy from branch → select main → save.

Your blog is live at https://yourusername.github.io within 2 minutes.

Publishing New Posts

From now on, publishing is simple:

Create a new file in _posts/ with today’s date in the filename
Write in Markdown
Commit and push:

git add _posts/2026-06-02-my-second-post.md
git commit -m "Add second post"
git push

GitHub Pages rebuilds your site automatically. Your post is live within 60 seconds.

Recommended Next Steps

Once your blog is live:

Add Google Analytics — track your traffic from day one
Set up a custom domain — yourblog.com instead of yourusername.github.io
Add comments — Giscus (GitHub Discussions) is the most popular free option for Jekyll
Submit your sitemap — go to Google Search Console and submit https://yourusername.github.io/sitemap.xml
Write consistently — even one post per week compounds significantly over a year

Browse Jekyll Blog Themes

Need a better theme for your blog? Browse our full collection of Jekyll blog themes — with live demos, GitHub star counts, and free vs premium filters.

References

Choosing the right permalink structure

Before your blog has any traffic, choosing your permalink structure is important — changing it later breaks every existing URL and requires 301 redirects to preserve SEO value.

Jekyll’s default permalink for posts is /:categories/:year/:month/:day/:title/. For most blogs, this is unnecessarily long and date-heavy. A cleaner approach is to set a simpler permalink in _config.yml:

# Clean URLs without dates
permalink: /blog/:title/

# Or with just the year for context
permalink: /blog/:year/:title/

The /blog/ prefix groups all posts under a consistent path, separating them from pages like /about/ and /contact/. This makes it easy to add other sections to your site later without URLs colliding.

Avoid changing the permalink format after launch. If you must change it, use jekyll-redirect-from to add redirects from old URLs to new ones. Add redirect_from: /old/url/ to individual post front matter and the plugin handles the redirect page generation.

Organising your posts with categories and tags

Categories and tags give readers a way to explore related content. In Jekyll, categories affect the URL by default (unless you use a permalink that omits :categories), while tags do not.

The practical difference: use categories for broad groupings — one or two categories per post. Use tags for specific topics — three to seven tags per post is a reasonable range.

Create archive pages for each category and tag so visitors can browse all content in a topic. Without archive pages, categories and tags in your front matter have no browsable destination. Plugins like jekyll-archives generate these pages automatically:

# Gemfile
gem "jekyll-archives"

# _config.yml
jekyll-archives:
  enabled:
    - categories
    - tags
  layouts:
    category: archive-taxonomy
    tag: archive-taxonomy
  permalinks:
    category: /category/:name/
    tag: /tag/:name/

Create _layouts/archive-taxonomy.html to render the archive page, then every category and tag automatically has a browsable page.

Writing posts that attract readers

The setup is only the beginning. The blog’s success depends on what you write and how consistently you write it.

The posts that perform best in search and get shared most often share common characteristics: they target a specific question someone is actively searching for, they answer it completely, and they do so with clarity and working examples. “How to add dark mode to Jekyll” outperforms “Some Jekyll customisation tips” in every measurable way — it addresses a specific intent and delivers a complete answer.

Write for one reader at a time. Before writing, ask: what does this person already know? What specific problem are they trying to solve? What would make them feel like the time reading this was well spent? Writing that answers these questions builds an audience; writing that addresses nobody in particular gets lost.

Format your posts for skimmability. Most readers scan before they read. Clear headings, short paragraphs, code examples in code blocks, and a logical progression from problem to solution make posts far more readable than a wall of prose. Jekyll’s kramdown renderer supports tables, footnotes, and all standard Markdown extensions — use them when they genuinely improve clarity.

Setting up comments

Jekyll is a static site generator, so it has no built-in commenting system. The most popular options for adding comments to a Jekyll blog are Giscus, Disqus, and Utterances.

Giscus uses GitHub Discussions to store comments — readers log in with GitHub to comment, and all comments live in your repository’s Discussions tab. This is the best option for developer-audience blogs because your readers are likely to have GitHub accounts, the comments are stored in a place you control, and there are no ads or tracking scripts. Setup takes about ten minutes on the Giscus website, which generates the script tag you paste into your post layout.

Disqus is the most widely-known option and works without requiring GitHub accounts. The free tier includes ads and cross-site tracking, which many readers find objectionable. The paid tier removes these. If your audience is non-technical and GitHub accounts are uncommon, Disqus is worth considering despite its drawbacks.

Utterances uses GitHub Issues instead of Discussions. It predates Giscus and is slightly less full-featured, but it works on any plan and has no ads.

Whichever system you choose, gate the script behind a user consent action if your site has European visitors — comment widgets typically set cookies and are subject to GDPR consent requirements.

Growing your blog’s readership

Publishing consistently matters more than any individual post. A blog with 50 articles posted over two years outperforms a blog with 10 articles posted in a rush, even if the 10 articles are individually better, because the sustained publishing signals to search engines that the site is active and authoritative.

Promotion compounds writing effort. Share each post on the platforms where your audience spends time — Twitter/X, LinkedIn, Hacker News (for appropriate technical content), Reddit’s relevant subreddits, and relevant newsletters. Build an email list from day one using a service like Mailchimp or ConvertKit — even if your list is tiny, it represents readers who asked to hear from you directly, which is far more valuable than social media followers.

Submit your site to niche directories and link aggregators relevant to your topic. For a Jekyll blog about web development, sites like CSS-Tricks, Dev.to (cross-post for discovery), and the Jekyll community forums are appropriate. Each relevant inbound link improves your search ranking and brings targeted readers.

Monitor your analytics monthly. Google Search Console shows you which search queries bring visitors to your blog — this is direct insight into what your audience is searching for. Use it to identify which posts to improve, which topics are gaining traction, and what new posts to write next. A blog guided by data grows faster than one guided by intuition alone.

The 30-minute setup covered in this guide is the beginning of what can become a long-running platform that compounds in value with every post you write. Browse Jekyll blog themes on JekyllHub to find a design that fits your voice and get started — the most important step is shipping your first post, even if everything is not perfect yet.

The 30-minute setup covered in this guide is the beginning of what can become a long-running platform that compounds in value with every post you write. The combination of GitHub Pages hosting, Markdown writing, and Jekyll’s build system is one of the most sustainable blogging stacks available — zero hosting costs, no database to maintain, content stored in Git, and a publishing workflow that takes less than a minute per post once the site is live.

jekyll blog jekyll setup github pages beginner guide