Build Command

Generate your static site from content and templates.

Usage

❯ gozzi help build
Usage: gozzi build [options]

Options:
  --config string  Path to config file (default "config.toml")
  --content string Content directory (default "content")
  --clean          Clean output directory before build (removes all files)

Options

--config

Specify a custom configuration file.

Type: string
Default: config.toml

# Use production config
gozzi build --config config.prod.toml

# Use staging config
gozzi build --config config.staging.toml

--content

Specify a custom content directory.

Type: string
Default: content

# Build from custom content directory
gozzi build --content posts

# Build from nested directory
gozzi build --content src/content

--clean

Clean the output directory before building (removes ALL files).

Type: flag
Default: false

# Clean build (removes all files first)
gozzi build --clean

⚠️ Warning: This removes ALL files in the output directory, including files not created by Gozzi.

Examples

Basic Build

# Build with default configuration (incremental)
gozzi build

This performs an incremental build:

• Preserves existing files in output directory
• Only overwrites Gozzi-generated files
• Fast rebuild times

Clean Build

# Clean build (recommended for production)
gozzi build --clean

This performs a clean build:

• Removes ALL files from output directory
• Generates everything from scratch
• Ensures no stale files remain

Custom Configuration

# Build with custom config file
gozzi build --config config.prod.toml

# Build with custom content directory
gozzi build --content drafts

# Combine multiple options
gozzi build --clean --config config.prod.toml --content posts

Build Process

The build command follows these steps:

1. Load Configuration - Reads config from specified file
2. Parse Content - Parses all Markdown files from content directory
3. Create Output Directory - Creates output directory if it doesn't exist
4. Process Templates - Applies templates to content
5. Generate Files - Writes HTML, CSS, JS to output directory
6. Report Build Time - Displays total build time

❯ gozzi build
Building site...
✓ Built in 45ms

Incremental Builds

By default, Gozzi performs incremental builds that preserve existing files.

How It Works

# First build
gozzi build  # Creates all files

# Add external file (e.g., search index from Python script)
python generate-search-index.py  # Creates search_index.json

# Rebuild
gozzi build  # Preserves search_index.json!

Benefits

✅ Mix with other tools - Keep files generated by external tools
✅ Preserve user files - Don't lose custom files in output directory
✅ Faster rebuilds - No need to remove/recreate unchanged files
✅ Works with serve - Perfect for development workflow

When to Use Clean Builds

Use --clean flag when you need a fresh build:

gozzi build --clean

Use cases:

• 🚀 Production deployments
• 🧹 Removing stale content
• 🐛 Debugging build issues
• 🔄 Major content restructuring

Build Output

The build generates files in your configured output directory (default: public/):

public/
├── index.html           # Homepage
├── blog/
│   ├── index.html       # Blog section index
│   └── post-1/
│       └── index.html   # Individual post
├── css/
│   └── main.css         # Static CSS
├── js/
│   └── main.js          # Static JavaScript
├── sitemap.xml          # Generated sitemap
├── atom.xml             # Generated RSS feed
└── robots.txt           # Generated robots.txt

Build Performance

Optimization Tips

Content Organization:

content/
├── blog/           # Group related content
├── docs/           # Separate sections
└── notes/          # Clear hierarchy

Image Optimization:

• Use optimized images (WebP, compressed)
• Resize images to appropriate dimensions
• Consider lazy loading

Template Efficiency:

• Minimize complex template logic
• Cache computed values
• Use partials for reusable components

Configuration for Builds

Common config options for builds:

# config.prod.toml
base_url = "https://example.com"
output_dir = "public"
content_dir = "content"
templates_dir = "templates"
static_dir = "static"

[build]
# Build-specific settings
minify_html = true
generate_sitemap = true
generate_rss = true

CI/CD Integration

GitHub Actions

- name: Build site
  run: gozzi build --clean --config config.prod.toml

GitLab CI

build:
  script:
    - gozzi build --clean --config config.prod.toml

Netlify

[build]
  command = "gozzi build --clean"
  publish = "public"

Exit Codes

Code	Meaning
0	Success
1	Build failed (config error, template error, etc.)

Related Commands

• Serve Command - Development server with live reload
• Usage Patterns - Advanced workflows
• Troubleshooting - Common build issues

Next Steps

• Configuration Guide - Configure your builds
• Content Structure - Organize your content
• Templates - Customize output