📝 Minimal Jekyll Blog

A modern, minimal personal blog built with Jekyll and Tailwind CSS. Perfect for developers who want a clean, professional blog on GitHub Pages.

🌟 Features

• Responsive Design - Beautiful dark theme, mobile-first approach
• Blog Posts - Markdown posts with pagination (10 per page)
• Projects Portfolio - Showcase your work
• Tags System - Organize posts by tags
• Table of Contents - Auto-generated TOC for long posts
• Social Sharing - Twitter, LinkedIn, Facebook, Reddit, Telegram
• SEO Optimized - Sitemap, meta tags, RSS feed
• Clean URLs - No .html extensions
• GitHub Actions - Automated deployment
• Docker Support - Run anywhere with zero setup
• Fast & Lightweight - Optimized performance

🚀 Getting Started

Quick Start (No Installation Needed!)

The fastest and easiest way to get your blog live:

1. Click "Use this template" button at the top of this repository
2. Create a new repository from the template
   • Name it yourusername.github.io (replace with your GitHub username)
   • Choose public
   • Click "Create repository"
3. Configure permissions
   • Go to Settings → Actions → General → Workflow permissions
   • Select Read and write permissions and save
4. Wait a few minutes for GitHub Actions to build your site

That's it! 🎉 Your blog is now live at https://yourusername.github.io

Local Development with Docker (Recommended)

Want to customize locally? Use Docker for zero dependency hassles:

Prerequisites: Just install Docker Desktop

# Clone your repository
git clone https://github.com/yourusername/yourusername.github.io.git
cd yourusername.github.io

# Start with one command
make up

# Or using docker-compose
docker-compose up

Visit http://localhost:4000 to see your blog! 🎉

Changes auto-reload with LiveReload!

Available Commands:

make help      # Show all commands
make up        # Start development server
make down      # Stop containers
make logs      # View logs
make shell     # Open shell in container
make dev       # Start with live CSS watching
make prod      # Build for production
make clean     # Clean up everything

Why Docker?

• ✅ No Ruby, Node.js, or gem installation needed
• ✅ Works identically on Windows, Mac, and Linux
• ✅ No dependency conflicts
• ✅ Clean system - everything in containers
• ✅ Easy updates - just rebuild

See docs/INSTALL.md for detailed Docker instructions.

Traditional Setup (Without Docker)

If you prefer installing dependencies locally:

Prerequisites:

• Ruby 3.0 or higher
• Node.js 18 or higher
• Bundler and npm

# Clone your repository
git clone https://github.com/yourusername/yourusername.github.io.git
cd yourusername.github.io

# Install dependencies
bundle install
npm install

# Build CSS
npm run build:css

# Run locally
bundle exec jekyll serve

Visit http://localhost:4000 to preview! 🎉

For detailed installation: See docs/INSTALL.md

📚 Documentation

Comprehensive guides to help you:

• Installation Guide - Docker & traditional setup, troubleshooting
• Customization - Make it yours
• Adding Content - Write posts and projects
• Features Guide - All features explained
• Deployment - Deploy to GitHub Pages, Netlify, and more
• FAQ - Common questions answered

⚡ Quick Customization

Edit _config.yml:

# -----------------------------------------------------------------------------
# Site settings
# -----------------------------------------------------------------------------

title: Your Name
first_name: Your
last_name: Name
greeting: "Hi, I'm Your Name!"
email: [email protected]
url: "https://yourusername.github.io"
icon: ⚛️  # emoji used as favicon

# Social Media
social:
  - icon: fa-brands fa-github
    link: https://github.com/yourusername
    name: GitHub
  - icon: fa-brands fa-x-twitter
    link: https://twitter.com/your_twitter
    name: Twitter / X
  # Add more...

# Navigation
navigation:
  - title: Articles
    url: /articles
  - title: Projects
    url: /projects
  - title: About
    url: /about

Configuration is organized into clear sections with comments.

For more: See CUSTOMIZING.md

📝 Writing Your First Post

Create _posts/2025-01-15-my-first-post.markdown:

---
layout: post
title: "My First Post"
date: 2025-01-15 10:00:00 +0000
tags: [tutorial, getting-started]
excerpt: "A brief description for SEO and previews"
---

## Welcome!

Your content here in **Markdown** format.

### Code Example

\`\`\`python
def hello():
    print("Hello, world!")
\`\`\`

### Images

![Description](/assets/images/my-image.jpg)

**Easy!** 🎉

For more details: See CONTENT.md

🐳 Docker Commands

Quick reference for Docker users:

Or use docker-compose directly:

docker-compose up          # Start
docker-compose down        # Stop
docker-compose logs -f     # View logs
docker-compose build       # Rebuild

🚢 Deploy to GitHub Pages

1. Push to GitHub

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

2. Enable GitHub Pages

   • Go to Settings → Pages
   • Select GitHub Actions as source

3. Configure Permissions

   • Go to Settings → Actions → General
   • Select Read and write permissions

4. Done! Your site deploys automatically on every push! 🎉

   Visit: https://yourusername.github.io

For detailed deployment: See DEPLOYMENT.md

📂 Project Structure

.
├── _includes/             # Reusable components
│   ├── header.html        # Site header
│   ├── share-buttons.html # Social sharing
│   └── social-icons.html  # Social media icons
├── _layouts/              # Page templates
│   ├── default.html       # Base layout
│   ├── page.html          # Static pages
│   ├── post.html          # Blog posts
│   └── project.html       # Project pages
├── _posts/                # Your blog posts (Markdown)
├── _projects/             # Your projects (Markdown)
├── assets/
│   ├── css/
│   │   ├── input.css      # Tailwind source (edit this)
│   │   └── main.css       # Compiled CSS (auto-generated)
│   └── images/            # Your images
├── docs/                  # Documentation
├── _config.yml            # Main configuration
├── Dockerfile             # Docker configuration
├── docker-compose.yml     # Docker Compose configuration
├── Makefile               # Convenient commands
├── Gemfile                # Ruby dependencies
├── package.json           # Node.js dependencies
└── README.md              # This file

🛠️ Development Workflow

Using Docker

# Start development
make up

# Edit files in your favorite editor
# Changes auto-reload at http://localhost:4000

# For CSS changes with live rebuild
make dev

# Build for production
make prod

Without Docker

Terminal 1 - Jekyll Server:

bundle exec jekyll serve --livereload

Terminal 2 - CSS Watcher:

npm run watch:css

Now edit files - both content and styles auto-reload!

🎨 Customization Examples

Change Colors

Edit assets/css/input.css:

:root {
  --color-primary: #3b82f6;  /* Your brand color */
  --color-bg: #0a0a0a;       /* Background */
  --color-text: #e0e0e0;     /* Text color */
}

Then rebuild: npm run build:css

Add Google Analytics

Edit _config.yml:

google_analytics: G-XXXXXXXXXX

Use Custom Domain

1. Create CNAME file with your domain:

   yourdomain.com
   

2. Configure DNS at your registrar:

   A    @    185.199.108.153
   A    @    185.199.109.153
   A    @    185.199.110.153
   A    @    185.199.111.153
   

3. Update _config.yml:

   url: "https://yourdomain.com"
   

4. Enable in GitHub: Settings → Pages → Custom domain

See DEPLOYMENT.md for details.

🙏 Acknowledgments

Powered by these amazing tools:

• Jekyll - Static site generator
• Tailwind CSS - Utility-first CSS framework
• Font Awesome - Icons
• jekyll-paginate - Pagination
• GitHub Pages - Free hosting
• Docker - Containerization platform

📖 Resources

Jekyll

• Official Documentation
• Jekyll Talk Forum
• Liquid Template Language

Tailwind CSS

• Official Documentation
• Tailwind UI
• Tailwind Components

Markdown

• Markdown Guide
• GitHub Flavored Markdown
• Markdown Cheatsheet

🤝 Contributing

Contributions are welcome! See CONTRIBUTING.md for guidelines.

Ways to contribute:

• 🐛 Report bugs
• 💡 Suggest features
• 📝 Improve documentation
• 🔧 Submit pull requests
• ⭐ Share your blog (for inspiration)

📄 License

MIT License - See LICENSE for details.

Free to use for personal and commercial projects.

💬 Support

• 📖 Read the comprehensive documentation
• 🔍 Search existing issues
• 💭 Ask questions in GitHub Discussions
• 🐛 Report bugs by opening an issue

🌟 Show Your Support

If you find this template useful:

• ⭐ Star this repository to show your appreciation
• 🍴 Fork it to create your own blog
• 📢 Share it with others who might benefit
• 🤝 Contribute to make it even better

🎯 What's Next?

After setting up your blog:

1. ✅ Customize - Make it yours (CUSTOMIZING.md)
2. ✅ Write - Create your first post (CONTENT.md)
3. ✅ Deploy - Go live on GitHub Pages (DEPLOYMENT.md)
4. ✅ Share - Tell the world about your blog!
5. ✅ Maintain - Keep dependencies updated

🚀 Live Examples

Sites using this template:

• My Blog - Submit yours!

Using this template? Let us know and we'll feature you here!

Made with ❤️ for developers by developers

⭐ Star this repo if you find it useful!

🍴 Fork it to create your own blog!

📢 Share it with others!

🐛 Report issues or contribute!