TailBliss

TailBliss is an opinionated Hugo theme with Tailwind CSS 4.x, Vite integration, and Alpine.js with light/dark modes.

Current Version: 1.1.0+ (Hugo Theme Structure)

View Demo · Report Bug · Request Feature · Ask Question

📚 Table of Contents

• 📁 Theme Structure
• 🚀 Quick Start
• ⚙️ Configuration
• 🔄 Migration Guide
• ✨ What's New in Tailwind CSS 4
• ✨ Features
• 📧 Contact Form Setup
• Credits

---

📁 Theme Structure

TailBliss follows the standard Hugo theme structure, making it easy to use in any Hugo site.

🎯 Standard Hugo Theme Structure

TailBliss is structured as a proper Hugo theme following Hugo's conventions:

• Theme files in root: All theme files (layouts/, static/, assets/, archetypes/, theme.toml) are located in the root directory
• Example content: Located in exampleSite/ directory for reference and testing
• Symlink setup: The exampleSite/themes/tailbliss symlink points to the parent directory (the theme itself)

🔧 Using TailBliss in Your Hugo Site

When you add TailBliss to your Hugo site, it goes in the themes/ directory:

# Your Hugo site structure will look like:
my-hugo-site/
├── content/
├── themes/
│   └── tailbliss/          # ← TailBliss theme here
│       ├── layouts/
│       ├── static/
│       ├── assets/
│       ├── archetypes/
│       └── theme.toml
├── hugo.yaml
└── ...

This is the standard way Hugo themes work - you reference the theme in your site's hugo.yaml with theme: tailbliss, and Hugo looks for it in the themes/tailbliss/ directory.

📦 How It Works

1. Theme Repository Structure (this repo):

   • Theme files (layouts/, static/, assets/, etc.) are in the root
   • exampleSite/ contains example content for testing
   • This follows Hugo's standard theme structure

2. Using in Your Hugo Site:

   • Clone or add as submodule to themes/tailbliss/ in your site
   • Reference it in your site's hugo.yaml with theme: tailbliss
   • Hugo automatically finds and uses the theme from themes/tailbliss/

3. Why This Structure?:

   • ✅ Standard Hugo convention - works with all Hugo tooling
   • ✅ Easy to update - just update the submodule
   • ✅ Clean separation - your content stays separate from theme files
   • ✅ Multiple themes - you can use multiple themes if needed

🔄 Migration from v0.5

If you're upgrading from v0.5, you'll need to migrate your content. See the Migration Guide below.

---

🚀 Quick Start

Option 1: Use as Hugo Theme (Recommended)

This is the standard way to use TailBliss in your Hugo site. The theme will be placed in your site's themes/ directory:

# Create a new Hugo site
hugo new site my-tailbliss-site
cd my-tailbliss-site

# Initialize git (required for submodule add)
git init

# Add TailBliss as a theme (places it in themes/tailbliss/)
git submodule add https://github.com/nusserstudios/tailbliss.git themes/tailbliss

# Copy example content (optional, excluding themes folder)
rsync -av --exclude='themes' themes/tailbliss/exampleSite/ .
# Or manually copy specific directories:
# cp -r themes/tailbliss/exampleSite/content themes/tailbliss/exampleSite/hugo.yaml themes/tailbliss/exampleSite/i18n .

# Install dependencies and build CSS (use pnpm or npm)
cd themes/tailbliss
pnpm install
# or: npm install
pnpm run build:css:dev
cp static/css/main.*.css ../../static/css/
cd ../..

# If you see "no layout file" warnings: add theme = "tailbliss" to hugo.toml,
# or remove hugo.toml so the rsync'd hugo.yaml (which has theme: tailbliss) is used.

# Start developing
hugo server

(The rsync creates static/css/ in your site; the theme uses the built file from there so Hugo does not need PostCSS configuration or processing in the project. Tailwind v4 + the Vite plugin + lightningcss handles CSS processing and autoprefixing.)

Note: Your site config must reference the theme. If you keep the default hugo.toml from hugo new site, add theme = "tailbliss" to it. The rsync'd hugo.yaml already has theme: tailbliss; if you remove hugo.toml, that file will be used.

Option 2: Clone for Development/Contributing

If you want to develop or contribute to the theme itself, clone the repository:

# Clone the repository
git clone https://github.com/nusserstudios/tailbliss.git tailbliss-theme
cd tailbliss-theme

# Install dependencies
pnpm install

# Test the theme using exampleSite
cd exampleSite
hugo server --themesDir=..

Note: This option is for theme development. For using the theme in your own site, use Option 1.

🎯 Automatic Content Setup

TailBliss includes an intelligent installation script that automatically sets up example content for you:

# The install script runs automatically with pnpm install
# Or run it manually:
pnpm run install
# or
node install.js

What the install script does:

• ✅ Checks for existing content - Won't overwrite your existing content
• ✅ Extracts from git repository - Gets the latest example content from the repository
• ✅ Creates complete structure - Sets up content/ directory with:
  • Sample pages (about.md, contact.md, prose.md)
  • 14 example blog and news posts
  • Proper directory structure (posts/ subdirectory)
• ✅ Safe operation - Only runs if no content/ directory exists
• ✅ Clear feedback - Shows progress and next steps

First-time setup:

git clone https://github.com/nusserstudios/tailbliss.git my-site
cd my-site
pnpm install  # Automatically runs the install script
pnpm run dev  # Start developing immediately

📋 Available Commands

Setup & Installation

# Install dependencies (automatically runs content setup)
pnpm install

# Manual content setup (if needed)
pnpm run install
# or
node install.js

Development

# Start development server with auto CSS rebuilding (RECOMMENDED)
pnpm run dev:watch

# Alternative: Traditional approach
pnpm run dev

# Manual CSS rebuild (when not using dev:watch)
pnpm run rebuild

Production Build

# Full production build
pnpm run build

🔄 Development Workflow Explained

TailBliss offers two development approaches - choose the one that fits your workflow:

🚀 Recommended: Auto-Watch Mode

pnpm run dev:watch

This command:

1. Starts CSS watcher (automatically rebuilds when Tailwind classes change)
2. Starts Hugo server with caching disabled
3. Opens your site at http://localhost:1313
4. No manual rebuilding needed - changes appear instantly!

📦 Traditional: Manual Mode

pnpm run dev

This command:

1. Builds CSS once in development mode
2. Starts Hugo server with caching disabled
3. Opens your site at http://localhost:1313
4. Requires manual rebuild when changing Tailwind classes

Making Changes

✅ When changing HTML/Tailwind classes:

• Edit your .html files in layouts/
• Hugo automatically detects changes and reloads
• No rebuild needed!

🔄 When changing colors/CSS variables:

• Edit assets/css/main.css
• Run: pnpm run rebuild
• Hugo automatically detects the new CSS and reloads

What Each Command Does

Command	Purpose	When to Use
pnpm run dev:watch	Auto-watch development (RECOMMENDED)	Best for active development - auto-rebuilds CSS
pnpm run dev	Traditional development server	When you prefer manual control
pnpm run rebuild	Rebuild CSS only	After changing colors/CSS variables (manual mode)
pnpm run build	Production build	Deploying to production

Why This Approach?

• ⚡ Fast rebuilds: Timestamp-based filenames ensure instant cache busting
• 🚫 No cache issues: Every rebuild generates a unique CSS filename
• 🔄 Auto-reload: Hugo detects CSS changes instantly and reloads browser
• 🎯 Explicit control: You decide when CSS rebuilds happen
• 🧹 Auto-cleanup: Old CSS files are automatically removed

Pro tip: The rebuild command uses timestamp-based filenames in development (e.g., main.abc123def.css) which completely eliminates browser caching issues, while production builds still use content-based hashes for optimal caching.

🔧 Troubleshooting Development Issues

Error: failed to read directory "static/css": no such file or directory

Hugo's readDir only checks your site root. The theme uses the built CSS from your site's static/css/. Fix: (1) Use the latest TailBliss—exampleSite now includes static/css/, so rsync creates it. (2) After building CSS in the theme, copy it into your site: cp themes/tailbliss/static/css/main.*.css static/css/. Then run hugo server.

CSS Changes Not Showing

With the new timestamp-based approach, this should rarely happen, but if it does:

1. Run rebuild: pnpm run rebuild
2. Check the CSS file: Look in static/css/ - you should see a new main.xxxxxxxxx.css file with a unique timestamp
3. Hard refresh browser: Cmd+Shift+R (Mac) or Ctrl+Shift+R (Windows) if needed

Infinite Build Loops

This has been completely eliminated with the new approach! If you somehow encounter it:

• Stop the process: Ctrl+C
• Use the simple workflow: pnpm run dev → make changes → pnpm run rebuild

Old CSS Still Loading

This is automatically handled now:

• Old CSS files are automatically deleted when you run pnpm run rebuild
• Each rebuild generates a unique filename (e.g., main.abc123def.css)
• Browser cache is bypassed because the filename is always different

When to Use Each Command

• Starting work: pnpm run dev:watch (RECOMMENDED - auto-rebuilds everything)
• Alternative start: pnpm run dev (manual mode)
• Changed HTML/Tailwind classes: No action needed with dev:watch (auto-rebuild)
• Changed CSS colors/variables: No action needed with dev:watch (auto-rebuild)
• Manual rebuild: pnpm run rebuild (only needed in manual mode)
• Deploying: pnpm run build

---

⚙️ Configuration

Basic Setup

After installation, update your hugo.yaml configuration:

baseURL: 'https://tailbliss.netlify.app'  # Replace with your actual domain
title: Your Site Title
theme: tailbliss

Important Configuration Notes

• baseURL: Set this to your actual domain for proper canonical URLs and social sharing
• theme: Must be set to tailbliss when using as a Hugo theme
• Example: The demo site uses https://tailbliss.com/

---

🚀 What's New in Tailwind CSS 4 Migration

TailBliss has been completely upgraded from Tailwind CSS 3.2 to 4.x with significant improvements:

⚡ Vite Integration

• Cache Busting: Automatic CSS hash generation (e.g., main.abc123.css)
• Hot Reloading: Instant CSS updates during development
• Build Performance: Faster CSS processing with Vite

🎨 Modern Color System

• OKLCH Colors: All colors now use the OKLCH color space for better perceptual uniformity
• Indigo Primary: Updated from blue to indigo with proper OKLCH values
• Enhanced Contrast: Better light/dark mode color relationships

🛠️ New CSS Architecture

• CSS-First Approach: Configuration moved from tailwind.config.js into CSS using @theme directive
• Custom Variants: Dark mode uses @custom-variant instead of class-based configuration
• Custom Utilities: Built-in prose-2xl utility for wider content (80ch with 110% font-size)

📝 Improved Typography

• Custom Prose Styles: Removed @tailwindcss/typography dependency
• OKLCH Integration: All text colors use OKLCH for consistent rendering
• Enhanced Code Highlighting: Better syntax highlighting colors in light/dark modes
• Markdown Tables: Improved table styling within prose content

🏗️ Development Workflow

Available Scripts:

pnpm run dev          # Start development server
pnpm run rebuild      # Rebuild CSS after changes
pnpm run build        # Production build

Build Process:

1. Development: Vite processes assets/css/main.css and generates timestamped files like main.abc123def.css
2. Production: Vite generates content-hashed CSS files like main.xyz789.css
3. Hugo template automatically detects and references the latest CSS file
4. Cache busting handled automatically in both development and production
5. Auto-cleanup removes old CSS files during development rebuilds

🎯 Key Benefits

• Zero Cache Issues: Timestamp-based filenames eliminate all CSS caching problems
• Faster Development: Vite's lightning-fast processing with instant cache busting
• Auto-Cleanup: Old CSS files are automatically removed during rebuilds
• Modern Colors: OKLCH provides more accurate colors across devices
• Simplified Config: CSS-first configuration is more maintainable
• Enhanced Typography: Custom prose styles with better performance

📦 Dependencies Updated

• tailwindcss: ^3.2.x → ^4.1.x
• Added: @tailwindcss/vite, vite
• Removed (cleanup for #333): @tailwindcss/postcss, postcss, autoprefixer, postcss-cli (no longer required; Tailwind v4 + Vite + lightningcss is sufficient)
• Removed: @tailwindcss/typography (replaced with custom styles)

---

🔄 Migration Guide

Migrating from TailBliss v0.5 to v1.1+

If you have an existing TailBliss v0.5 site, follow these steps to migrate:

Step 1: Backup Your Content

# Create a backup of your current site
cp -r my-old-tailbliss-site my-old-tailbliss-backup

Step 2: Create New Hugo Site Structure

# Create a new Hugo site
hugo new site my-new-tailbliss-site
cd my-new-tailbliss-site

# Add TailBliss v1.1 as a theme
git submodule add https://github.com/nusserstudios/tailbliss.git themes/tailbliss

Step 3: Copy Your Content

# Copy your existing content
cp -r ../my-old-tailbliss-backup/content/* ./content/
cp -r ../my-old-tailbliss-backup/static/* ./static/
cp -r ../my-old-tailbliss-backup/assets/* ./assets/

# Copy your Hugo configuration (and merge with new theme settings)
cp ../my-old-tailbliss-backup/hugo.yaml ./hugo.yaml

Step 4: Update Configuration

Edit your hugo.yaml to include the theme and your domain:

baseURL: 'https://yourdomain.com/'
theme: tailbliss

Step 5: Install Dependencies & Setup Content

# Install dependencies and automatically setup example content
pnpm install

# Test your site
pnpm run dev

Alternative: Use the install script for fresh content If you want to start with fresh example content instead of migrating:

# Remove existing content and let install script create fresh examples
rm -rf content/
pnpm run install  # Creates fresh example content from repository

Common Migration Issues

1. Missing Theme Reference: Make sure theme: tailbliss is in your hugo.yaml
2. CSS Not Loading: Ensure you've run pnpm install in your site root
3. Images Not Displaying: Check that images are in the correct /assets or /static directories
4. Custom Layouts: If you customized layouts, copy them to your site's layouts/ directory
5. Quick Setup: You can copy the entire exampleSite content to your root directory:

   # Copy all exampleSite content to root
   cp -r exampleSite/* .

Fresh Start Option

If you prefer to start fresh:

# Clone and let the install script handle content setup automatically
git clone https://github.com/nusserstudios/tailbliss.git my-site
cd my-site
pnpm install  # Automatically runs install script and sets up content
pnpm run dev  # Start developing immediately

Manual approach (if you prefer manual control):

git clone https://github.com/nusserstudios/tailbliss.git my-site
cd my-site
cp -r exampleSite/* .  # Copy example files manually
pnpm install
pnpm run dev

---

✨ Features

Has paginated Categories and Tags. Markdown files will automatically convert images put into /assets folder to .webp images.

Image shortcodes for webp as well.

{{< imgc src="img-name.jpg" alt="Place alt text here." >}}

📧 Contact Form Setup

To use the contact form:

1. Visit FormSubmit.Co
2. Locate the contact form in content/contact.md (or exampleSite/content/contact.md if using as reference)
3. Update the form action with your email address:

   action="https://formsubmit.co/your@email.com" method="POST"

Credits

4044ever - Original Theme
https://github.com/4044ever/Hugo-Tailwind-3.0.git

Jan Heise - Alpine.js Navbar
https://github.com/jan-heise/responsive-navbar-with-dropdown

TailBliss Team - Tailwind CSS 4 Migration, Vite Integration & OKLCH Colors

Made for Hacktoberfest, with ❤️ by NusserStudios.