<img width="100px" src="images/logo-tailbliss-round.svg" align="center" alt="TailBliss Logo" /> <h1 align="center">TailBliss</h1> 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) <a href="https://github.com/nusserstudios/tailbliss/actions/"> <img alt="Tests Passing" src="https://github.com/nusserstudios/tailbliss/actions/workflows/codeql.yml/badge.svg" /> </a> <a href="https://github.com/nusserstudios/tailbliss/contributors"> <img alt="GitHub Contributors" src="https://img.shields.io/github/contributors/nusserstudios/tailbliss?color=0088ff" /> </a> <a href="https://github.com/nusserstudios/tailbliss/issues"> <img alt="Issues" src="https://img.shields.io/github/issues/nusserstudios/tailbliss?color=fc0b03" /> </a> <a href="https://github.com/nusserstudios/tailbliss/pulls"> <img alt="GitHub pull requests" src="https://img.shields.io/github/issues-pr/nusserstudios/tailbliss?color=f97316" /> </a> <a href="https://gohugo.io/"> <img src="https://img.shields.io/badge/Hugo%20-0.148.2%20-gray.svg?colorA=c9177e&colorB=FF4088&style=for-the-badge"/> </a> <a href="https://tailwindcss.com/"> <img src="https://img.shields.io/badge/TailwindCSS%20-V4-gray.svg?colorA=0284c7&colorB=38bdf8&style=for-the-badge"/> </a> <a href="https://vitejs.dev/"> <img src="https://img.shields.io/badge/Vite%20-V7-gray.svg?colorA=646cff&colorB=747bff&style=for-the-badge"/> </a> <a href="https://alpinejs.dev/"> <img src="https://img.shields.io/badge/Alpine.js%20-V3-gray.svg?colorA=68a5af&colorB=77c1d2&style=for-the-badge"/> </a> <a href="https://tailbliss.netlify.app/">View Demo</a> · <a href="https://github.com/nusserstudios/tailbliss/issues">Report Bug</a> · <a href="https://github.com/nusserstudios/tailbliss/discussions/categories/feature-request">Request Feature</a> · <a href="https://github.com/nusserstudios/tailbliss/discussions/categories/general">Ask Question</a> <img src="https://raw.githubusercontent.com/nusserstudios/tailbliss/main/images/tailbliss-lighthouse-11-03-22.png" alt="Tailbliss Google Lighthouse Score" style="margin: 25px auto; max-width: 830px" width="100%" height="" />

📁 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

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
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/
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 in the project.)

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:

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

📦 Traditional: Manual Mode

pnpm run dev