I can’t believe it. Claude Code was able to update my Jekyll-based site bitdribble.github.io to use Tailwind pretty much with no intervention. The transformation from the old, less flexible Minima theme to a modern Tailwind-powered setup was vibe coded with a few light touches.
The Challenge with Minima
For years, I’ve been running my personal knowledge repository on Jekyll with the default Minima theme. While Minima served its purpose, it had several limitations. The look and feel was outdated, and layouts were especially rigid.
Enter Tailwind CSS
Tailwind CSS has become the go-to utility-first CSS framework for modern web development, and for good reason:
- It is much simpler than CSS
- It is responsove out of the box, built with mobile-first principles
- AI editors like Claude Code and Cursor are very fluent with Tailwind.
The Migration Process
What surprised me most was how seamless the migration turned out to be.
Development Environment Setup
The migration was performed on Fedora Linux using a simple but effective workflow:
- Repository Setup: Checked out the Git repository from the command line:
git clone https://github.com/bitdribble/bitdribble.github.io.git cd bitdribble.github.io -
IDE Integration: Loaded the project in Cursor (this works equally well in VSCode):
- Claude Code Extension: Enabled the Claude Code add-in, which, like Cursor, provides:
- Intelligent code suggestions and refactoring
- Context-aware assistance with Jekyll and Tailwind
- Seamless understanding of project structure and dependencies
How Claude Code Transformed the Migration
The AI assistant proved exceptionally capable at understanding both Jekyll’s architecture and Tailwind’s utility-first approach. Here’s what made it work so well:
1. Jekyll’s Markdown Flexibility
Almost all Jekyll pages can be written in pure Markdown. Take a look at my markdown example page - it’s a full demonstration of how Jekyll processes Markdown content beautifully, even with the new Tailwind styling.
- Content creators don’t need to know HTML or CSS
- Blog posts remain simple and focused on content
2. Inline HTML When Needed
When you need more sophisticated layouts or Tailwind-specific components, Jekyll’s Markdown processor allows you to embed HTML+Tailwind directly in your Markdown files. For example, I was able to create a sophisticated three-column layout for my about page by simply adding:
<div class="bg-white rounded-lg shadow-lg p-8">
<div class="grid md:grid-cols-3 gap-8 items-start">
<!-- Column content here -->
</div>
</div>
Live Example: Here’s that same three-column layout in action with actual content:
Markdown Content
Write content in simple Markdown syntax without worrying about styling complexities.
Tailwind Styling
Add sophisticated layouts with utility-first CSS classes when you need more control.
Jekyll Processing
Jekyll seamlessly processes both Markdown and HTML, giving you complete flexibility.
This flexibility gives you the best of both worlds - simple content editing in Markdown, with the power to create complex layouts when needed.
3. Enhanced Features with Jekyll
The Jekyll + Tailwind combination also preserves and enhances Jekyll’s powerful features. Take a look at the markdown example page which demonstrates:
Code Syntax Highlighting: Jekyll automatically highlights code blocks with proper syntax coloring for multiple languages:
def fibonacci(n):
if n <= 1:
return n
return fibonacci(n-1) + fibonacci(n-2)
MathJax Integration: Mathematical formulas can be enabled by adding mathjax: true to the page front matter:
---
layout: page
title: Your Page Title
mathjax: true
---
Then you can write beautiful mathematical expressions:
- Inline math: $E = mc^2$
- Display equations: \(\int_{-\infty}^{\infty} e^{-x^2} dx = \sqrt{\pi}\)
Page Headers: Jekyll’s front matter system makes it easy to configure pages with metadata, layout selection, and feature toggles like MathJax - all while maintaining the flexibility to use Tailwind styling throughout the content.
The Payoff
The transformation has been dramatic. Here’s a side-by-side comparison of the old Minima theme versus the new Tailwind-powered design:
Before: Jekyll Minima Theme
The original site using Jekyll's Minima theme with dark styling
After: Tailwind CSS Design
The modern site with Tailwind CSS featuring improved navigation and visual hierarchy
The site now boasts:
- Modern visuals: Professional and polished
- Performance: Purged CSS for leaner loads
- Flexibility: I can create any layout I can imagine without fighting the framework
Why Jekyll + Tailwind Rocks
- Content Teams: Edit in Markdown, no CSS needed.
- Developers: Modern tooling, reusable components
- Businesses: Fast, SEO-friendly, low-cost hosting (GitHub Pages, Netlify)
Technical Implementation
The migration involved several key technical steps that Claude Code helped orchestrate seamlessly:
1. Tailwind CSS Integration
Adding the Tailwind CLI:
# Downloaded the standalone Tailwind CLI binary
curl -sLO https://github.com/tailwindlabs/tailwindcss/releases/latest/download/tailwindcss-linux-x64
chmod +x tailwindcss-linux-x64
mv tailwindcss-linux-x64 tailwindcss
Created Tailwind Configuration:
// tailwind.config.js
module.exports = {
content: [
'./_includes/**/*.html',
'./_layouts/**/*.html',
'./_posts/**/*.md',
'./*.html',
'./*.md',
'./**/*.md'
],
theme: {
extend: {
// Custom colors and styling
},
},
plugins: [],
}
Build Process Integration:
Created a Makefile to streamline development with proper process management: make dev starts the web server locally, and Ctrl-C stops it:
# Development with live reload and signal handling
dev:
@echo "Starting development environment..."
@trap 'echo "Stopping all processes..."; kill 0' INT; \
./tailwindcss -o assets/css/tailwind.css --watch & \
TAILWIND_PID=$$!; \
bundle exec jekyll serve & \
JEKYLL_PID=$$!; \
echo "Development server running. Press Ctrl+C to stop both processes."; \
wait
# Production build
build:
./tailwindcss -o assets/css/tailwind.css --minify
bundle exec jekyll build
2. Replacing the Minima Theme
Removed Theme Dependency:
# _config.yml - Commented out the minima theme
# theme: minima # Removed - using Tailwind CSS instead
Layout System Redesign:
_layouts/default.html: Created a new base layout with Tailwind styling_layouts/home.html: Redesigned blog listing with card-based design_layouts/page.html: Clean page layout with proper typography_layouts/post.html: Enhanced blog post layout with better readability
3. Component Migration Strategy
Navigation System: Replaced Minima’s navigation with a modern Tailwind-based header featuring:
- Responsive dropdown menus
- Clean typography and spacing
4. Content Preservation
Front Matter Compatibility: All existing blog posts and pages continued to work without modification. Jekyll’s front matter system remained unchanged:
---
layout: post
title: "My Blog Post"
date: 2025-01-20
categories: [webdev, jekyll]
---
Conclusion
Jekyll + Tailwind is a powerhouse for blogs and company sites, blending content simplicity with design flexibility. Claude Code nailed the migration, delivering a stunning result with minimal effort. Check the source code or live site to see it in action!