tools-only JekyllSetup Workflow
Configure Jekyll for your GitHub Pages site.
Checklist
- Choose a theme
- Create _config.yml
- Setup directory structure
- Configure front matter
- Test locally (optional)
- Deploy and verify
Step 1: Choose a Theme
Supported Themes (Zero Configuration)
| Theme | Style |
|---|---|
jekyll-theme-architect |
Blueprint/technical |
jekyll-theme-cayman |
Clean, modern |
jekyll-theme-dinky |
Playful |
jekyll-theme-hacker |
Terminal/hacker |
jekyll-theme-leap-day |
Yellow notebook |
jekyll-theme-merlot |
Warm, inviting |
jekyll-theme-midnight |
Dark, sophisticated |
jekyll-theme-minima |
Minimal blog |
jekyll-theme-minimal |
Simple, clean |
jekyll-theme-modernist |
Modern, sleek |
jekyll-theme-slate |
Gray, professional |
jekyll-theme-tactile |
Textured |
jekyll-theme-time-machine |
Retro futuristic |
Remote Themes (Any GitHub Jekyll Theme)
Use remote_theme to use themes not in the supported list.
Step 2: Create _config.yml
Minimal Configuration
theme: jekyll-theme-minimal
title: My Site
description: A description of my site
Full Configuration
# Theme
theme: jekyll-theme-minimal
# Or use remote theme:
# remote_theme: pages-themes/minimal@v0.2.0
# Site Settings
title: My Site
description: A description of my site
url: https://username.github.io
baseurl: "" # or "/repository-name" for project sites
# Author
author:
name: Your Name
email: your@email.com
# Build Settings
markdown: kramdown
highlighter: rouge
# Plugins (optional)
plugins:
- jekyll-feed
- jekyll-seo-tag
- jekyll-sitemap
# Exclude from build
exclude:
- README.md
- Gemfile
- Gemfile.lock
- node_modules
- vendor
Step 3: Directory Structure
Basic Structure
.
├── _config.yml # Site configuration
├── index.md # Homepage
├── about.md # About page
├── _posts/ # Blog posts
│ └── 2024-01-01-welcome.md
├── assets/
│ ├── css/
│ │ └── style.scss # Custom styles
│ └── images/
└── _layouts/ # Custom layouts (optional)
└── default.html
Blog Post Naming Convention
_posts/YYYY-MM-DD-title.md
Example: _posts/2024-01-15-my-first-post.md
Step 4: Configure Front Matter
Page Front Matter
---
layout: default
title: Page Title
description: Page description for SEO
permalink: /custom-url/
---
Page content here...
Blog Post Front Matter
---
layout: post
title: "Blog Post Title"
date: 2024-01-15 10:00:00 -0500
categories: [category1, category2]
tags: [tag1, tag2]
author: Your Name
---
Post content here...
Step 5: Customize Theme
Custom CSS
Create assets/css/style.scss:
---
---
@import "{{ site.theme }}";
// Custom styles below
body {
font-family: 'Your Font', sans-serif;
}
h1, h2, h3 {
color: #333;
}
// Add more custom styles...
Custom Layout
- Find theme's
_layouts/default.htmlin theme repository - Copy contents to your
_layouts/default.html - Modify as needed
Example custom layout:
<!DOCTYPE html>
<html lang="en">
<head>
<meta charset="UTF-8">
<meta name="viewport" content="width=device-width, initial-scale=1.0">
<title>{{ page.title }} | {{ site.title }}</title>
<link rel="stylesheet" href="{{ '/assets/css/style.css' | relative_url }}">
</head>
<body>
<header>
<h1>{{ site.title }}</h1>
<nav>
<a href="{{ '/' | relative_url }}">Home</a>
<a href="{{ '/about' | relative_url }}">About</a>
</nav>
</header>
<main>
{{ content }}
</main>
<footer>
<p>© {{ site.time | date: '%Y' }} {{ site.author.name }}</p>
</footer>
</body>
</html>
Step 6: Test Locally (Optional)
Prerequisites
# Install Ruby (if not installed)
# macOS: brew install ruby
# Ubuntu: sudo apt install ruby-full
# Install Bundler
gem install bundler
Setup
Create Gemfile:
source "https://rubygems.org"
gem "github-pages", group: :jekyll_plugins
# Optional plugins
gem "jekyll-feed"
gem "jekyll-seo-tag"
Run Locally
# Install dependencies
bundle install
# Ruby 3.0+ may need:
bundle add webrick
# Start local server
bundle exec jekyll serve
# Or with live reload
bundle exec jekyll serve --livereload
# Access at http://localhost:4000
Step 7: Deploy
# Commit changes
git add .
git commit -m "Setup Jekyll site"
git push origin main
Wait up to 10 minutes for deployment.
Common Issues
Theme Not Applying
- Verify theme name in
_config.ymlis correct - Clear browser cache
- Check for YAML syntax errors
Custom CSS Not Loading
- Ensure front matter dashes
---at top of SCSS file - Verify @import statement matches theme name
- Check file is in correct location
Build Errors
- Check Actions tab for error messages
- Verify YAML front matter syntax
- Ensure all plugins are supported
Useful Liquid Tags
<!-- Link to another page -->
[About]({{ '/about' | relative_url }})
<!-- Include image -->
<!-- Loop through posts -->
{% for post in site.posts %}
<h2><a href="{{ post.url }}">{{ post.title }}</a></h2>
<p>{{ post.excerpt }}</p>
{% endfor %}
<!-- Site metadata -->
{{ site.github.repository_name }}
{{ site.github.project_title }}