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

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

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

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)

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.

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

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

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

# 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 setup content
cd themes/tailbliss
pnpm install
cd ../..

# Start developing
hugo server

Note: Your site's hugo.yaml should reference the theme:

theme: tailbliss

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.

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

# Install dependencies (automatically runs content setup)
pnpm install

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

# 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

# Full production build
pnpm run build

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

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!

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

✅ 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

• ⚡ 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.

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

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

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

• 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

After installation, update your hugo.yaml configuration:

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

• 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/

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

• 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

• 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

• 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)

• 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

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

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

• 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

• tailwindcss: ^3.2.x → ^4.1.x
• Added: @tailwindcss/vite, @tailwindcss/postcss, vite
• Removed: @tailwindcss/typography (replaced with custom styles)

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

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

# 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

# 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

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

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

# 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

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/* .

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

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

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

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"

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.