Getting Started with Sour Theme

Welcome to Sour Theme! 🍋 This comprehensive guide will walk you through setting up your own modern Jekyll blog using this cutting-edge template.

What you’ll learn: How to set up, customize, and deploy a professional Jekyll blog in under 20 minutes.

🚀 Quick Overview

Sour Theme is a minimal, cyberpunk-inspired Jekyll theme designed for developers and content creators who want:

✨ Core Technologies

Jekyll 4.4.1 - Lightning-fast static site generator
TailwindCSS 4.x - Utility-first CSS framework with JIT compilation
DaisyUI - Beautiful component library with 25+ themes
Modern Plugins - SEO optimization, analytics, table of contents, and more

🎯 Key Features

Multi-theme Support - Light, dark, cyberpunk, and 20+ other themes
Responsive Design - Mobile-first approach that looks great on any device
SEO Optimized - Built-in meta tags, structured data, and social media ready
Developer Friendly - Hot reloading, easy customization, GitHub Actions workflow
Performance First - Optimized builds, lazy loading, and minimal JavaScript

Prerequisites

Before you start, make sure you have:

Ruby (version 2.7 or higher)
Node.js (version 16 or higher)
Git for version control
A GitHub account (for deployment)

Step 1: Get the Template

Choose one of these options:

Option A: Use Template (Recommended)

Go to the Sour Theme repository
Click the green “Use this template” button
Create your new repository with a descriptive name like my-blog

Option B: Fork Repository

Fork the repository on GitHub
Clone your fork locally

Option C: Clone Directly

git clone https://github.com/jeremycardona/jekyll-theme-sour.git my-blog
cd my-blog
rm -rf .git && git init  # Start fresh git history

Step 2: Install Dependencies

# Install both Ruby gems and Node.js packages
make install

# Or install separately:
bundle install    # Ruby dependencies
npm install      # Node.js dependencies

Step 3: Customize Your Site

Update Site Configuration

Edit _config.yml with your information:

title: Your Amazing Blog
email: your-email@example.com
description: >-
  Write a compelling description of your blog. This appears in search 
  results and social media previews.
baseurl: ""                    # Remove "/jekyll-theme-sour"
url: "https://yourdomain.com"  # Your actual domain
github_username: yourusername
author: Your Name

Choose Your Theme

The template supports multiple DaisyUI themes. Edit _layouts/default.html:

<!-- Change the data-theme attribute -->
<html lang="en" data-theme="dark">  

Available themes: light, dark, cyberpunk, cupcake, emerald, corporate, retro

Step 4: Remove Template Content

Delete Example Posts

rm _posts/2024-01-*.md

Update About Page

Edit about.markdown with your information:

---
layout: default
title: About
permalink: /about/
---

# About Me

Write your story here...

Customize Homepage (Optional)

Modify index.markdown if you want to change the homepage layout.

Step 5: Create Your First Post

Create a new file in _posts/ following Jekyll’s naming convention:

# File: _posts/2024-01-15-my-first-post.md

---
layout: post
title: "My First Blog Post"
date: 2024-01-15 10:00:00 -0000
author: Your Name
tags: [Getting Started, Jekyll, Blog]
category: personal
excerpt: "Welcome to my new blog! Here's what you can expect."
toc: true  # Enable table of contents
---

Welcome to my blog! This is my first post using the Sour theme.

## What's Coming Next

Here's what I plan to write about:

- Technology tutorials
- Personal experiences
- Project showcases

Stay tuned for more content!

Step 6: Development Workflow

Start Development Server

make serve
# Opens at http://localhost:4000

Watch for Changes

The server automatically rebuilds when you:

Modify posts or pages
Update layouts or includes
Change CSS (TailwindCSS rebuilds automatically)

Build for Production

make build
# Outputs to _site/ directory

Step 7: Deploy Your Blog

GitHub Pages (Recommended)

Push to GitHub:

git add .
git commit -m "Initial blog setup"
git push origin main

Enable GitHub Actions:
- Go to your repository settings
- Navigate to “Pages” section
- Set source to “GitHub Actions” (not “Deploy from branch”)
- The included workflow will handle building and deployment
Set Custom Domain (Optional):
- Add CNAME file to root directory with your domain
- Configure DNS with your domain provider

Alternative Deployment Options

Netlify:

Connect your GitHub repository
Set build command: make build
Set publish directory: _site

Vercel:

Import your GitHub repository
Framework preset: “Other”
Build command: make build
Output directory: _site

Step 8: Ongoing Maintenance

Keep Dependencies Updated

# Update Ruby gems
bundle update

# Update Node packages
npm update

# Rebuild CSS after updates
npm run build:css

Theme Updates

To get theme improvements:

# Add original repository as upstream
git remote add upstream https://github.com/jeremycardona/jekyll-theme-sour.git

# Fetch and merge updates (carefully review changes)
git fetch upstream
git merge upstream/main

Quick Start Checklist

Customize _config.yml with your information
Choose your preferred theme in _layouts/default.html
Delete template posts from _posts/
Update about.markdown with your story
Create your first blog post
Test locally with make serve
Push to GitHub and enable GitHub Actions
Set up custom domain (optional)
Share your blog with the world!

Customization Tips

Adding New Pages

Create .md or .html files in the root directory:

---
layout: default
title: Contact
permalink: /contact/
---

# Get In Touch
[Your contact form or information]

Organizing Posts with Categories

Use categories to organize content:

category: tutorial  # Creates /category/tutorial/ page

Using Tags

Add relevant tags for better discoverability:

tags: [Jekyll, Web Development, Tutorial]

Custom CSS

Add custom styles to src/input.css:

/* Your custom styles */
.my-custom-class {
  @apply bg-primary text-primary-content p-4 rounded;
}

Need Help?

Documentation: Check the included example posts for feature demonstrations
Issues: Open an issue on the GitHub repository
Jekyll Docs: https://jekyllrb.com/docs/
TailwindCSS: https://tailwindcss.com/docs
DaisyUI: https://daisyui.com/

What’s Next?

Write quality content regularly to grow your audience
Optimize for SEO with good titles and descriptions
Engage with readers through social media links
Monitor performance with Google Analytics (add to _config.yml)
Keep learning and improving your blog

Happy blogging! 🎉

Made with ❤️ using Jekyll, TailwindCSS, and DaisyUI