chill.social/themes/chill-theme/docs/INSTALLATION.md

# Installation Guide

Complete guide to installing and setting up the Hugo Saasify Theme for your SaaS website.

## Table of Contents

- [Prerequisites](#prerequisites)
- [Installation Methods](#installation-methods)
  - [Method 1: New Site](#method-1-new-site)
  - [Method 2: Existing Site](#method-2-existing-site)
  - [Method 3: Manual Installation](#method-3-manual-installation)
- [Initial Configuration](#initial-configuration)
- [Verifying Installation](#verifying-installation)
- [Next Steps](#next-steps)
- [Updating the Theme](#updating-the-theme)
- [Troubleshooting](#troubleshooting)

## Prerequisites

Before installing the Hugo Saasify Theme, ensure you have the following installed on your system:

### Required Software

1. **Hugo Extended** (v0.80.0 or later)
   - The theme requires Hugo Extended edition for Tailwind CSS processing
   - Download from [Hugo Releases](https://github.com/gohugoio/hugo/releases)
   - Verify installation: `hugo version`
   - Expected output should include "extended"

2. **Git** (latest version recommended)
   - Required for theme installation and updates
   - Download from [git-scm.com](https://git-scm.com/)
   - Verify installation: `git --version`

3. **Node.js and npm** (v14.0.0 or later)
   - Required for Tailwind CSS compilation
   - Download from [nodejs.org](https://nodejs.org/)
   - Verify installation: `node --version` and `npm --version`

### System Requirements

- Operating System: Windows, macOS, or Linux
- Disk Space: At least 100MB free
- Internet Connection: Required for initial setup and dependencies

### Recommended Tools

- Code editor (VS Code, Sublime Text, or similar)
- Terminal/Command line familiarity
- Basic understanding of Hugo and Markdown

## Installation Methods

Choose the installation method that best fits your use case.

### Method 1: New Site

This is the recommended method if you're starting a new project from scratch.

#### Step 1: Create a New Hugo Site

```bash
# Create a new Hugo site
hugo new site my-saas-website

# Navigate into the new site directory
cd my-saas-website
```

#### Step 2: Initialize Git Repository

```bash
# Initialize git repository
git init

# Create initial commit
git add .
git commit -m "Initial commit"
```

#### Step 3: Add the Theme as a Git Submodule

```bash
# Add theme as submodule
git submodule add https://github.com/chaoming/chill-theme.git themes/chill-theme

# Update submodule
git submodule update --init --recursive
```

#### Step 4: Example Site (Optional)

The theme comes with a fully functional example site that demonstrates its features and capabilities. You can use this as a reference when building your own site.

##### Using the Example Site

The example site provides a great starting point to understand how to:

- Structure your content
- Use different page layouts
- Configure navigation menus
- Set up site parameters
- Implement common SaaS website features

1. Copy the example site content:

```bash
cp -r themes/chill-theme/exampleSite/* .
```

The example site includes:

- Complete content structure with sample pages
- Blog posts with various layouts
- Feature pages
- Career/Jobs section
- Pricing page
- Company information page
- Properly configured hugo.toml

#### Step 5: Install Dependencies

```bash
# Copy package.json and other config files to your site root
cp themes/chill-theme/package.json .
cp themes/chill-theme/postcss.config.js .
cp themes/chill-theme/tailwind.config.copy.js ./tailwind.config.js
```

```bash
# Install dependencies
npm install
```

#### Step 6: Set the theme in hugo.toml

Open your `hugo.toml` and check that the theme is correctly set:

```toml
# Theme Configuration
theme = "chill-theme"
```

#### Step 7: Start Development Server

```bash
# Start development server (builds TailwindCSS and runs Hugo server)
npm run start

# Your site will be available at http://localhost:1313
```

### Method 2: Existing Site

If you already have a Hugo site and want to add the Saasify theme.

#### Step 1: Add Theme as Submodule

```bash
# From your site root directory
git submodule add https://github.com/chaoming/chill-theme.git themes/chill-theme

# Update submodule
git submodule update --init --recursive
```

#### Step 2: Update Configuration

Add or update the following in your `hugo.toml`:

```toml
theme = "chill-theme"

# Required Features
pygmentsCodeFences = true
pygmentsUseClasses = true
enableEmoji = true
enableGitInfo = true

# Required Module Configuration
[module]
  [module.hugoVersion]
    extended = true
    min = "0.80.0"

# Required Build Configuration
[build]
  writeStats = true

# Required Markup Configuration
[markup]
  [markup.highlight]
    noClasses = false
    lineNos = true
    codeFences = true
  [markup.goldmark.renderer]
    unsafe = true
  [markup.tableOfContents]
    endLevel = 3
    ordered = false
    startLevel = 2
```

#### Step 3: Install Theme Dependencies

```bash
# Copy package.json and other config files to your site root
cp themes/chill-theme/package.json .
cp themes/chill-theme/postcss.config.js .
cp themes/chill-theme/tailwind.config.copy.js ./tailwind.config.js

# Install dependencies
npm install
```

#### Step 4: Configure Theme Settings

Copy relevant configuration from the example site:

```bash
# View example configuration for reference
cat themes/chill-theme/exampleSite/hugo.toml
```

Merge the configuration settings into your existing `hugo.toml`. See [CONFIGURATION.md](CONFIGURATION.md) for detailed options.

#### Step 5: Test the Theme

```bash
# Start development server
npm run start
```

### Method 3: Manual Installation

For users who prefer not to use Git submodules or need more control over the installation.

#### Step 1: Download Theme

```bash
# Download and extract theme
curl -L https://github.com/chaoming/chill-theme/archive/refs/heads/main.zip -o theme.zip
unzip theme.zip
mv chill-theme-main themes/chill-theme
rm theme.zip
```

Alternatively, download the ZIP file from GitHub and extract it manually to `themes/chill-theme`.

#### Step 2: Install Dependencies

```bash
# Copy package.json and other config files to your site root
cp themes/chill-theme/package.json .
cp themes/chill-theme/postcss.config.js .
cp themes/chill-theme/tailwind.config.copy.js ./tailwind.config.js

# Install dependencies
npm install
```

#### Step 3: Configure Hugo

Update your `hugo.toml` to reference the theme:

```toml
theme = "chill-theme"
```

Add all required configuration settings from the example site.

#### Step 4: Verify Installation

```bash
# Check theme is recognized
hugo config

# Start development server
npm run start
```

## Initial Configuration

After installing the theme, configure the essential settings.

### Basic Configuration

Edit your `hugo.toml` file:

```toml
# Basic Configuration
baseURL = "/"
languageCode = "en-us"
title = "Your Site Title"
theme = "chill-theme"

# Required Features
pygmentsCodeFences = true  # Enable syntax highlighting
pygmentsUseClasses = true
enableEmoji = true        # Enable emoji support
enableGitInfo = true      # Enable Git info for lastmod

# Required Module Configuration
[module]
  [module.hugoVersion]
    extended = true
    min = "0.80.0"

# Required Build Configuration
[build]
  writeStats = true      # Required for TailwindCSS

# Required Markup Configuration
[markup]
  [markup.highlight]
    noClasses = false
    lineNos = true
    codeFences = true
  [markup.goldmark.renderer]
    unsafe = true       # Allow HTML in markdown
  [markup.tableOfContents]
    endLevel = 3
    ordered = false
    startLevel = 2

# Theme Parameters
[params]
  description = "Your site description"
  author = "Your Name"
  logo = "/images/logo.svg"
```

### Tailwind CSS Setup

The theme uses Tailwind CSS for styling. The build process is integrated into Hugo.

During installation, you should have copied the Tailwind configuration file:

- `tailwind.config.js` - Copied from `themes/chill-theme/tailwind.config.copy.js` to your site root
- `postcss.config.js` - PostCSS configuration in your site root
- Dependencies installed via `npm install`

The `npm run start` command automatically watches and compiles Tailwind CSS during development.

### Menu Configuration

Add your navigation menu to `hugo.toml`:

```toml
[menu]
  [[menu.main]]
    name = "Features"
    weight = 1
    [menu.main.params]
      has_submenu = true
      submenu = [
        { name = "Feature 1", url = "/features/feature-1/" },
        { name = "Feature 2", url = "/features/feature-2/" }
      ]

  [[menu.main]]
    name = "Pricing"
    url = "/pricing"
    weight = 2

  [[menu.main]]
    name = "Blog"
    url = "/blog"
    weight = 3
```

See [CONFIGURATION.md](CONFIGURATION.md) for complete menu options.

## Verifying Installation

### Check Hugo Version

```bash
hugo version
```

Expected output should include "extended" and version 0.80.0 or higher.

### Check Theme Files

```bash
# Verify theme directory structure
ls -la themes/chill-theme/

# Should show:
# - layouts/
# - assets/
# - static/
# - exampleSite/
# - package.json
# - tailwind.config.js
```

### Test Development Server

```bash
# Start server
npm run start

# Check for errors in terminal
# Visit http://localhost:1313 in browser
```

### Verify Build Output

```bash
# Build site
hugo

# Check public directory was created
ls public/

# Should contain:
# - index.html
# - css/
# - js/
# - images/
```

## Development Workflow

### Starting the Development Server

To start the development server with live reload and TailwindCSS compilation:

```bash
npm run start
```

This will:

- Watch for changes in your TailwindCSS styles
- Run the Hugo development server
- Automatically rebuild when changes are detected
- Serve your site at <http://localhost:1313>

### Building for Production

To build your site for production:

```bash
npm run build
```

This will:

- Build and minify your TailwindCSS styles
- Generate minified Hugo site in the `public` directory

## Next Steps

After successful installation:

1. **Customize Configuration**: Review [CONFIGURATION.md](CONFIGURATION.md) for all available options
2. **Create Content**: Learn about content creation in [CONTENT-CREATION.md](CONTENT-CREATION.md)
3. **Customize Styling**: See [STYLING.md](STYLING.md) for theme customization
4. **Add Pages**: Use available layouts documented in [LAYOUTS.md](LAYOUTS.md)
5. **Use Shortcodes**: Explore components in [SHORTCODES.md](SHORTCODES.md)
6. **Deploy**: Follow deployment guides in [DEPLOYMENT.md](DEPLOYMENT.md)

## Updating the Theme

### For Git Submodule Installations

```bash
# Update to latest version
git submodule update --remote themes/chill-theme

# If there are npm dependency updates, copy the updated files
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

# Commit the update
git add themes/chill-theme
git commit -m "Update chill-theme"
```

### For Manual Installations

```bash
# Backup your current theme (if you made custom changes)
cp -r themes/chill-theme themes/chill-theme-backup

# Download latest version
curl -L https://github.com/chaoming/chill-theme/archive/refs/heads/main.zip -o theme.zip
unzip theme.zip
rm -rf themes/chill-theme
mv chill-theme-main themes/chill-theme
rm theme.zip

# Copy updated config files and install dependencies
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
```

### Update Best Practices

1. **Always backup** before updating
2. **Review changelog** for breaking changes
3. **Test locally** before deploying updates
4. **Check configuration** for new options
5. **Update dependencies** after theme updates

### Version Pinning

To pin to a specific version using Git submodule:

```bash
cd themes/chill-theme
git checkout v1.0.0  # Replace with desired version tag
cd ../..
git add themes/chill-theme
git commit -m "Pin theme to v1.0.0"
```

## Troubleshooting

### Theme Not Found

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

**Solution**:
```bash
# Check theme directory exists
ls themes/

# Verify theme name in hugo.toml matches directory name
grep "^theme" hugo.toml

# Should output: theme = "chill-theme"
```

### Extended Version Error

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

**Solution**:
```bash
# Check Hugo version includes "extended"
hugo version

# If not extended, download extended version from:
# https://github.com/gohugoio/hugo/releases
```

### CSS Not Loading

**Problem**: Site loads without styling

**Solution**:
```bash
# Ensure build stats are enabled in hugo.toml
[build]
  writeStats = true

# Ensure theme dependencies are installed in site root
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

# Clear Hugo cache
hugo --gc

# Rebuild and start server
npm run start
```

### Submodule Empty

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

**Solution**:
```bash
# Initialize and update submodules
git submodule init
git submodule update --recursive

# If still empty, remove and re-add
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 Error

**Problem**: npm install fails

**Solution**:
```bash
# Clear npm cache
npm cache clean --force

# Delete node_modules and reinstall in site root
rm -rf node_modules package-lock.json
npm install
```

### Port Already in Use

**Problem**: Hugo server won't start due to port conflict

**Solution**:
```bash
# Use different port (modify package.json start script to add --port flag)
# Or find and kill process using port 1313
lsof -ti:1313 | xargs kill -9  # macOS/Linux
# For Windows, use: netstat -ano | findstr :1313

# Then restart
npm run start
```

For more troubleshooting help, see [TROUBLESHOOTING.md](TROUBLESHOOTING.md) or visit the [GitHub Issues](https://github.com/chaoming/chill-theme/issues) page.

## Getting Help

If you encounter issues not covered in this guide:

1. Check [TROUBLESHOOTING.md](TROUBLESHOOTING.md)
2. Review [example site configuration](../exampleSite/)
3. Search [GitHub Issues](https://github.com/chaoming/chill-theme/issues)
4. Create a new issue with:
   - Hugo version (`hugo version`)
   - Operating system
   - Error messages
   - Steps to reproduce

## Additional Resources

- [Hugo Documentation](https://gohugo.io/documentation/)
- [Tailwind CSS Documentation](https://tailwindcss.com/docs)
- [Theme Repository](https://github.com/chaoming/chill-theme)
- [Demo Site](https://saasify-demo.chaoming.li)