chill_hugoplate/themes/chill-theme/docs/TROUBLESHOOTING.md

# Troubleshooting Guide

Common issues and solutions when working with the Hugo Saasify Theme. Find quick fixes for installation, build, styling, content, deployment, and performance problems.

## Table of Contents

- [Installation Issues](#installation-issues)
- [Build Errors](#build-errors)
- [Styling Problems](#styling-problems)
- [Content Issues](#content-issues)
- [Deployment Problems](#deployment-problems)
- [Performance Issues](#performance-issues)
- [Browser Compatibility](#browser-compatibility)
- [Getting Help](#getting-help)

## Installation Issues

### Theme Not Found

**Problem**: Hugo can't find the theme

```
Error: unable to locate theme directory "chill-theme"
```

**Solutions**:

1. **Verify theme directory exists**:
```bash
ls themes/chill-theme
```

2. **Check theme name in config**:
```toml
# hugo.toml
theme = "chill-theme"  # Must match directory name exactly
```

3. **If using Git submodule, initialize it**:
```bash
git submodule init
git submodule update --recursive
```

4. **Check directory structure**:
```bash
# Should show theme files
ls -la themes/chill-theme/layouts/
```

### Hugo Extended Not Installed

**Problem**: Error about Hugo Extended being required

```
Error: this theme requires Hugo Extended
```

**Solutions**:

1. **Check your Hugo version**:
```bash
hugo version
```

Expected output should include "extended":
```
hugo v0.120.0+extended darwin/amd64
```

2. **Install Hugo Extended**:
   - Visit [Hugo Releases](https://github.com/gohugoio/hugo/releases)
   - Download version with "extended" in the name
   - Install and verify

3. **On macOS with Homebrew**:
```bash
brew install hugo
```

### Submodule Empty

**Problem**: Theme directory exists but is empty

**Solutions**:

1. **Update submodules**:
```bash
git submodule update --init --recursive
```

2. **If still empty, remove and re-add**:
```bash
git submodule deinit -f themes/chill-theme
rm -rf .git/modules/themes/chill-theme
git rm -f themes/chill-theme
git submodule add https://github.com/chaoming/chill-theme.git themes/chill-theme
```

### npm Dependencies Failed

**Problem**: npm install fails

```
npm ERR! code ENOENT
```

**Solutions**:

1. **Check Node.js is installed**:
```bash
node --version
npm --version
```

2. **Ensure config files are copied to site root**:
```bash
cp themes/chill-theme/package.json .
cp themes/chill-theme/postcss.config.js .
cp themes/chill-theme/tailwind.config.copy.js ./tailwind.config.js
```

3. **Clear npm cache**:
```bash
npm cache clean --force
```

4. **Delete and reinstall**:
```bash
rm -rf node_modules package-lock.json
npm install
```

5. **Use different npm registry** (if blocked):
```bash
npm config set registry https://registry.npmjs.org/
npm install
```

## Build Errors

### Tailwind CSS Not Processing

**Problem**: Site loads without styling

**Solutions**:

1. **Enable build stats** in `hugo.toml`:
```toml
[build]
  writeStats = true

[build.buildStats]
  enable = true
```

2. **Clear Hugo cache**:
```bash
hugo --gc
```

3. **Verify Tailwind config exists**:
```bash
ls themes/chill-theme/tailwind.config.js
```

4. **Rebuild from clean state**:
```bash
rm -rf public resources
hugo server -D
```

### Template Errors

**Problem**: Error in template execution

```
Error: error calling partial: template: partials/header.html...
```

**Solutions**:

1. **Check the error message** - it usually points to the specific line
2. **Common causes**:
   - Missing closing tags
   - Incorrect variable names
   - Missing required parameters
   - Syntax errors in shortcodes

3. **Validate configuration**:
```bash
hugo config
```

4. **Test with minimal config**:
   - Copy `exampleSite/hugo.toml`
   - Gradually add your customizations

### Shortcode Errors

**Problem**: Shortcode fails to render

```
Error: failed to render shortcode "pricing-table-1"
```

**Solutions**:

1. **Check JSON syntax** (for shortcodes accepting JSON):
   - Use double quotes, not single quotes
   - No trailing commas
   - Valid JSON structure
   - Use JSON validator online

2. **Verify shortcode exists**:
```bash
ls themes/chill-theme/layouts/shortcodes/pricing-table-1.html
```

3. **Check shortcode syntax**:
```markdown
# Correct
{{< shortcode-name >}}

# Incorrect
{< shortcode-name >}     # Missing one brace
{{<shortcode-name>}}     # Missing spaces
```

### Build Fails in CI/CD

**Problem**: Builds work locally but fail in CI

**Solutions**:

1. **Match Hugo versions**:
   - Check local: `hugo version`
   - Set in CI config: `HUGO_VERSION=0.120.0`

2. **Install theme dependencies**:
```yaml
# GitHub Actions example
- name: Install dependencies
  run: |
    cp themes/chill-theme/package.json .
    cp themes/chill-theme/postcss.config.js .
    cp themes/chill-theme/tailwind.config.copy.js ./tailwind.config.js
    npm install
```

3. **Check environment variables**:
   - Verify all required env vars are set
   - Check for typos in variable names

4. **Review build logs**:
   - Look for specific error messages
   - Check file paths are correct
   - Verify permissions

## Styling Problems

### Custom CSS Not Loading

**Problem**: Custom CSS changes don't appear

**Solutions**:

1. **Clear browser cache**:
   - Hard refresh: Ctrl+Shift+R (Windows/Linux) or Cmd+Shift+R (Mac)
   - Or use incognito/private mode

2. **Verify CSS file path**:
```toml
[params]
  customCSS = ["css/custom.css"]  # File must be in static/css/
```

3. **Check file exists**:
```bash
ls static/css/custom.css
```

4. **Clear Hugo cache**:
```bash
hugo --gc
rm -rf resources
hugo server -D
```

### Tailwind Classes Not Working

**Problem**: Tailwind utility classes have no effect

**Solutions**:

1. **Check class is in content paths**:
```javascript
// tailwind.config.js
content: ["./layouts/**/*.html"]
```

2. **Avoid dynamic class names**:
```html
<!-- Don't do this -->
<div class="text-{{ .Color }}-600">

<!-- Do this instead -->
<div class="{{ if eq .Color "blue" }}text-blue-600{{ end }}">
```

3. **Rebuild site**:
```bash
hugo --gc
hugo
```

4. **Check Tailwind version compatibility**:
```bash
npm list tailwindcss
```

### Colors Not Matching Design

**Problem**: Colors appear different than expected

**Solutions**:

1. **Check color values in `tailwind.config.js`**:
```javascript
colors: {
  primary: {
    600: '#425ad6',  // Your primary color
  }
}
```

2. **Verify you're using correct shade**:
```html
<div class="bg-primary-600">  <!-- Not bg-primary -->
```

3. **Check for color overrides** in custom CSS

4. **Test in different browsers** to rule out rendering differences

### Responsive Design Issues

**Problem**: Layout broken on mobile/tablet

**Solutions**:

1. **Test with DevTools**:
   - Open Chrome DevTools (F12)
   - Toggle device toolbar (Ctrl+Shift+M)
   - Test various screen sizes

2. **Check responsive classes**:
```html
<!-- Use responsive prefixes -->
<div class="text-sm md:text-base lg:text-lg">
```

3. **Verify viewport meta tag** (should be in baseof.html):
```html
<meta name="viewport" content="width=device-width, initial-scale=1.0">
```

4. **Test breakpoints**:
   - sm: 640px
   - md: 768px
   - lg: 1024px
   - xl: 1280px

## Content Issues

### Page Not Rendering

**Problem**: Page exists but shows 404

**Solutions**:

1. **Check front matter**:
```yaml
---
title: "My Page"
draft: false  # Make sure this is false
---
```

2. **Verify file location**:
```bash
ls content/my-page.md
```

3. **Check URL structure**:
   - `content/about.md` → `/about/`
   - `content/blog/post.md` → `/blog/post/`

4. **Restart server**:
```bash
hugo server -D  # -D shows drafts
```

### Images Not Displaying

**Problem**: Images don't show on page

**Solutions**:

1. **Check file path**:
```markdown
# Correct - absolute from static/
![Image](/images/photo.jpg)

# Incorrect - relative path
![Image](../images/photo.jpg)
```

2. **Verify file exists**:
```bash
ls static/images/photo.jpg
```

3. **Check file permissions**:
```bash
chmod 644 static/images/photo.jpg
```

4. **Test URL directly**:
   - Visit `http://localhost:1313/images/photo.jpg`
   - Should display the image

5. **Check file extension** matches exactly (case-sensitive on some systems)

### Shortcode Shows as Text

**Problem**: Shortcode appears as plain text instead of rendering

**Solutions**:

1. **Check syntax**:
```markdown
# Correct
{{< shortcode >}}

# Incorrect
{{ < shortcode > }}
{< shortcode >}
```

2. **Verify shortcode exists**:
```bash
ls themes/chill-theme/layouts/shortcodes/
```

3. **Check if content uses correct format**:
   - Markdown files: Use `{{< >}}`
   - HTML files: Use `{{ .Inner }}`

### Taxonomy Pages Empty

**Problem**: Category or tag pages show no posts

**Solutions**:

1. **Enable taxonomies** in `hugo.toml`:
```toml
[taxonomies]
  category = 'categories'
  tag = 'tags'
```

2. **Check front matter**:
```yaml
categories: ["Technology"]  # Use array, not string
tags: ["Hugo", "Tutorial"]
```

3. **Verify taxonomy matches config**:
```toml
# If you have:
[taxonomies]
  category = 'categories'

# Use in front matter:
categories: ["Tech"]  # Not category:
```

## Deployment Problems

### Build Fails on Platform

**Problem**: Build works locally but fails on Netlify/Vercel/etc.

**Solutions**:

1. **Set Hugo version**:

Netlify:
```toml
# netlify.toml
[build.environment]
  HUGO_VERSION = "0.120.0"
```

Vercel:
```json
// vercel.json
{
  "build": {
    "env": {
      "HUGO_VERSION": "0.120.0"
    }
  }
}
```

2. **Install theme dependencies**:

Add to build command:
```bash
cp themes/chill-theme/package.json . && cp themes/chill-theme/postcss.config.js . && cp themes/chill-theme/tailwind.config.copy.js ./tailwind.config.js && npm install && hugo --minify
```

3. **Check environment variables** are set in platform UI

### Assets Not Loading After Deploy

**Problem**: CSS/JS/images don't load on deployed site

**Solutions**:

1. **Verify baseURL** in `hugo.toml`:
```toml
baseURL = "https://yourdomain.com/"  # Must match your domain
```

2. **Use absolute paths**:
```html
<!-- Correct -->
<img src="/images/logo.svg">

<!-- Incorrect -->
<img src="images/logo.svg">
```

3. **Check CDN/cache**:
   - Clear CDN cache
   - Wait for propagation
   - Hard refresh browser

4. **Verify build output**:
```bash
# Check public/ directory
ls -la public/css/
ls -la public/images/
```

### SSL Certificate Issues

**Problem**: HTTPS not working or certificate errors

**Solutions**:

1. **Wait for provisioning** (can take 24-48 hours)

2. **Check DNS configuration**:
   - A record points to correct IP
   - CNAME points to correct host

3. **Force HTTPS** in platform settings

4. **Clear browser SSL cache**

### 404 on Deployed Site

**Problem**: Pages work locally but 404 on deployed site

**Solutions**:

1. **Check baseURL** includes trailing slash:
```toml
baseURL = "https://example.com/"  # Note the /
```

2. **Verify case sensitivity**:
   - URLs are case-sensitive on most servers
   - Use lowercase for consistency

3. **Check redirects** (if you have them):
   - Verify redirect rules are correct
   - Check for infinite redirect loops

## Performance Issues

### Slow Build Times

**Problem**: Site takes too long to build

**Solutions**:

1. **Enable caching**:
```toml
[caches]
  [caches.images]
    dir = ":resourceDir/_gen"
    maxAge = "1440h"
```

2. **Optimize images** before adding:
   - Compress images
   - Reduce dimensions
   - Use appropriate formats

3. **Limit content during development**:
```bash
hugo server -D --buildFuture=false --buildExpired=false
```

4. **Check for template loops**:
   - Review custom templates
   - Look for inefficient queries

### Site Loads Slowly

**Problem**: Pages take long time to load in browser

**Solutions**:

1. **Enable minification**:
```bash
hugo --minify
```

2. **Optimize images**:
   - Compress all images
   - Use WebP format
   - Implement lazy loading

3. **Use CDN** for static assets

4. **Enable caching** on server:
```nginx
# Nginx example
location ~* \.(jpg|jpeg|png|gif|ico|css|js)$ {
    expires 1y;
}
```

5. **Run Lighthouse audit**:
   - Open Chrome DevTools
   - Go to Lighthouse tab
   - Run performance audit
   - Follow recommendations

### Large CSS File

**Problem**: Generated CSS is too large

**Solutions**:

1. **Verify PurgeCSS is working**:
```bash
# Check file size
ls -lh public/css/*.css
```

2. **Ensure build stats enabled**:
```toml
[build]
  writeStats = true
```

3. **Check content paths** in `tailwind.config.js`:
```javascript
content: ["./layouts/**/*.html"]
```

## Browser Compatibility

### Works in Chrome, Not Safari

**Problem**: Site works in Chrome but has issues in Safari

**Solutions**:

1. **Check for unsupported CSS**:
   - Avoid bleeding-edge features
   - Test CSS properties on [Can I Use](https://caniuse.com/)

2. **Add vendor prefixes** if needed:
```css
-webkit-transition: all 0.3s;
transition: all 0.3s;
```

3. **Test in multiple browsers**:
   - Chrome
   - Firefox
   - Safari
   - Edge

### JavaScript Errors in IE11

**Problem**: Site broken in Internet Explorer

**Note**: IE11 is deprecated. Modern browsers only.

**Solutions**:

1. **Display upgrade message** for old browsers
2. **Focus on modern browsers** (Chrome, Firefox, Safari, Edge)
3. **IE11 usage is <1%** globally - consider if support is needed

## Getting Help

### Before Asking for Help

1. **Check this guide** for your issue
2. **Review documentation**:
   - [INSTALLATION.md](INSTALLATION.md)
   - [CONFIGURATION.md](CONFIGURATION.md)
   - [LAYOUTS.md](LAYOUTS.md)
   - [SHORTCODES.md](SHORTCODES.md)
3. **Search existing issues** on GitHub
4. **Try example site** to isolate problem

### Gathering Information

When reporting issues, include:

1. **Hugo version**:
```bash
hugo version
```

2. **Operating system**:
```bash
uname -a  # Linux/Mac
# or
ver  # Windows
```

3. **Error messages** (complete output)

4. **Configuration** (relevant parts of `hugo.toml`)

5. **Steps to reproduce**:
   - What you did
   - What you expected
   - What actually happened

6. **Minimal reproduction**:
   - Simplest case that shows the problem
   - Remove unrelated code/config

### Where to Get Help

1. **Documentation**: Check all docs in `/docs` directory

2. **Example Site**: Review working examples in `/exampleSite`

3. **GitHub Issues**:
   - Search: [Existing Issues](https://github.com/chaoming/chill-theme/issues)
   - Create: [New Issue](https://github.com/chaoming/chill-theme/issues/new)

4. **Hugo Community**:
   - [Hugo Discourse](https://discourse.gohugo.io/)
   - [Hugo Documentation](https://gohugo.io/documentation/)

5. **Stack Overflow**:
   - Tag: `hugo`, `hugo-theme`

### Creating a Good Issue Report

**Template**:

```markdown
## Description
Brief description of the problem

## Environment
- Hugo version: 0.120.0+extended
- OS: macOS 14.0
- Theme version: main branch

## Steps to Reproduce
1. Step one
2. Step two
3. Step three

## Expected Behavior
What should happen

## Actual Behavior
What actually happens

## Error Messages
```
Paste error messages here
```

## Configuration
```toml
Relevant parts of hugo.toml
```

## Additional Context
Any other relevant information
```

## Common Error Messages

### "Page Not Found"

**Cause**: Content file doesn't exist or is draft

**Fix**:
- Check file exists
- Verify `draft: false`
- Restart server

### "Template Not Found"

**Cause**: Missing or misnamed template file

**Fix**:
- Check template file exists
- Verify layout name in front matter
- Check template lookup order

### "Failed to Process"

**Cause**: CSS/Asset processing error

**Fix**:
- Check PostCSS configuration
- Verify Hugo Extended installed
- Review asset file syntax

### "Submodule Not Found"

**Cause**: Git submodule not initialized

**Fix**:
```bash
git submodule update --init --recursive
```

## Quick Fixes Checklist

When something isn't working:

- [ ] Restart Hugo server
- [ ] Clear browser cache (Ctrl+Shift+R)
- [ ] Clear Hugo cache (`hugo --gc`)
- [ ] Delete `public/` and `resources/` directories
- [ ] Verify Hugo version (`hugo version`)
- [ ] Check `hugo.toml` syntax
- [ ] Review error messages carefully
- [ ] Test with example site configuration
- [ ] Check file permissions
- [ ] Verify file paths are correct

## Prevention Best Practices

Avoid issues before they happen:

1. **Use Version Control**: Commit working states
2. **Test Locally**: Before deploying
3. **Keep Updated**: Update Hugo and dependencies
4. **Follow Documentation**: Don't guess
5. **Start Simple**: Add complexity gradually
6. **Backup Configuration**: Save working configs
7. **Use Example Site**: Reference working examples
8. **Read Error Messages**: They usually tell you what's wrong

## Related Documentation

- [INSTALLATION.md](INSTALLATION.md) - Installation guide
- [CONFIGURATION.md](CONFIGURATION.md) - Configuration options
- [DEPLOYMENT.md](DEPLOYMENT.md) - Deployment guides
- [Hugo Troubleshooting](https://gohugo.io/troubleshooting/)

## Still Stuck?

If you've tried everything and still have issues:

1. **Create minimal reproduction** - Simplest case showing problem
2. **Open GitHub issue** with all relevant information
3. **Be patient** - Maintainers are volunteers
4. **Be detailed** - More info = faster resolution
5. **Follow up** - Respond to questions

Remember: Most issues have been encountered before. Search first, then ask.