champs-libres/chill_hugoplate

Fork 0

Files

Boris Waaub cc60b64505 Converti chill-theme en dossier classique

2026-01-28 09:40:37 +01:00

14 KiB

Raw Blame History

Installation Guide

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

Prerequisites
Installation Methods
Initial Configuration
Verifying Installation
Next Steps
Updating the Theme
Troubleshooting

Prerequisites

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

Required Software

Hugo Extended (v0.80.0 or later)
- The theme requires Hugo Extended edition for Tailwind CSS processing
- Download from Hugo Releases
- Verify installation: hugo version
- Expected output should include "extended"
Git (latest version recommended)
- Required for theme installation and updates
- Download from git-scm.com
- Verify installation: git --version
Node.js and npm (v14.0.0 or later)
- Required for Tailwind CSS compilation
- Download from 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

# 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

# Initialize git repository
git init

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

Step 3: Add the Theme as a Git Submodule

# 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

Copy the example site content:

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

# 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 6: Set the theme in hugo.toml

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

# Theme Configuration
theme = "chill-theme"

Step 7: Start Development Server

# 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

# 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:

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

# 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:

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

Merge the configuration settings into your existing hugo.toml. See CONFIGURATION.md for detailed options.

Step 5: Test the Theme

# 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

# 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

# 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:

theme = "chill-theme"

Add all required configuration settings from the example site.

Step 4: Verify Installation

# 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:

# 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.

Add your navigation menu to hugo.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 for complete menu options.

Verifying Installation

Check Hugo Version

hugo version

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

Check Theme Files

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

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

Test Development Server

# Start server
npm run start

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

Verify Build Output

# 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:

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:

npm run build

This will:

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

Next Steps

After successful installation:

Customize Configuration: Review CONFIGURATION.md for all available options
Create Content: Learn about content creation in CONTENT-CREATION.md
Customize Styling: See STYLING.md for theme customization
Add Pages: Use available layouts documented in LAYOUTS.md
Use Shortcodes: Explore components in SHORTCODES.md
Deploy: Follow deployment guides in DEPLOYMENT.md

Updating the Theme

For Git Submodule Installations

# 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

# 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

Always backup before updating
Review changelog for breaking changes
Test locally before deploying updates
Check configuration for new options
Update dependencies after theme updates

Version Pinning

To pin to a specific version using Git submodule:

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:

# 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:

# 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:

# 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:

# 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:

# 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:

# 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 or visit the GitHub Issues page.

Getting Help

If you encounter issues not covered in this guide:

Check TROUBLESHOOTING.md
Review example site configuration
Search GitHub Issues
Create a new issue with:
- Hugo version (hugo version)
- Operating system
- Error messages
- Steps to reproduce

14 KiB Raw Blame History

Installation Guide

Table of Contents

Prerequisites

Required Software

System Requirements

Recommended Tools

Installation Methods

Method 1: New Site

Step 1: Create a New Hugo Site

Step 2: Initialize Git Repository

Step 3: Add the Theme as a Git Submodule

Step 4: Example Site (Optional)

Using the Example Site

Step 5: Install Dependencies

Step 6: Set the theme in hugo.toml

Step 7: Start Development Server

Method 2: Existing Site

Step 1: Add Theme as Submodule

Step 2: Update Configuration

Step 3: Install Theme Dependencies

Step 4: Configure Theme Settings

Step 5: Test the Theme

Method 3: Manual Installation

Step 1: Download Theme

Step 2: Install Dependencies

Step 3: Configure Hugo

Step 4: Verify Installation

Initial Configuration

Basic Configuration

Tailwind CSS Setup

Menu Configuration

Verifying Installation

Check Hugo Version

Check Theme Files

Test Development Server

Verify Build Output

Development Workflow

Starting the Development Server

Building for Production

Next Steps

Updating the Theme

For Git Submodule Installations

For Manual Installations

Update Best Practices

Version Pinning

Troubleshooting

Theme Not Found

Extended Version Error

CSS Not Loading

Submodule Empty

npm Dependencies Error

Port Already in Use

Getting Help

Additional Resources

14 KiB

Raw Blame History