Usage Patterns

Advanced workflows, best practices, and tips for using Gozzi CLI effectively.

Development Workflows

Standard Development Workflow

The most common workflow for day-to-day development:

# 1. Start development server with live reload
gozzi serve --config config.dev.toml

# 2. Edit content, templates, or config in your editor
# Changes are automatically detected and browser reloads

# 3. When ready to deploy, build for production
gozzi build --clean --config config.prod.toml

Content-First Workflow

Focus on writing content first, styling later:

# 1. Start with minimal template
gozzi serve

# 2. Write all your content (blog posts, pages, etc.)

# 3. Periodically check output
# Browser shows content structure

# 4. Refine templates based on content needs

# 5. Build when content is finalized
gozzi build --clean

Theme Development Workflow

Developing a new theme or customizing templates:

# 1. Start server with live reload
gozzi serve --port 3000

# 2. Keep browser DevTools open
# Monitor CSS, layout, JavaScript

# 3. Edit templates and styles
# See changes instantly

# 4. Test with different content
gozzi serve --content examples --port 3001

# 5. Validate across browsers

Multi-Environment Setup

Manage different environments (development, staging, production) with separate configs.

Directory Structure

my-site/
├── config/
│   ├── config.dev.toml      # Development settings
│   ├── config.staging.toml  # Staging settings
│   └── config.prod.toml     # Production settings
├── content/
├── templates/
└── static/

Environment-Specific Commands

Development:

gozzi serve --config config/config.dev.toml --port 3000

Staging:

gozzi build --clean --config config/config.staging.toml

Production:

gozzi build --clean --config config/config.prod.toml

Environment Configurations

Development (config.dev.toml):

toml

base_url = "http://localhost:3000"
output_dir = "dev-build"

[extra]
environment = "development"
enable_analytics = false
minify_html = false

Staging (config.staging.toml):

toml

base_url = "https://staging.example.com"
output_dir = "staging-build"

[extra]
environment = "staging"
enable_analytics = true
minify_html = true

Production (config.prod.toml):

toml

base_url = "https://example.com"
output_dir = "public"

[extra]
environment = "production"
enable_analytics = true
minify_html = true
enable_seo = true

Content Organization Patterns

Multiple Content Sections

Serve different content sections on different ports for parallel development:

# Terminal 1: Blog development
gozzi serve --content blog --port 1313

# Terminal 2: Documentation development
gozzi serve --content docs --port 1314

# Terminal 3: Portfolio development
gozzi serve --content portfolio --port 1315

Draft Content Workflow

Keep drafts separate from published content:

content/
├── published/       # Published content
│   ├── blog/
│   └── pages/
└── drafts/         # Draft content
    ├── blog/
    └── pages/

# Preview drafts
gozzi serve --content content/drafts

# Build only published content
gozzi build --content content/published

Content Testing

Test specific content subsets:

# Test new blog section
gozzi serve --content content/blog-new --port 8080

# Compare with current blog
gozzi serve --content content/blog --port 8081

Integration with External Tools

Search Index Generation

Generate search index after building:

# Build site (incremental - preserves existing files)
gozzi build

# Generate search index with Python
python generate-search-index.py

# Rebuild site (search_index.json preserved!)
gozzi build

Why incremental builds matter:

External tools can add files to output directory
Subsequent Gozzi builds preserve those files
Perfect for search indexes, analytics, etc.

Image Optimization

Optimize images before or after building:

# Optimize images in static directory
npm run optimize-images

# Build site with optimized images
gozzi build --clean

Asset Pipeline

Integrate with modern asset pipelines:

# Build CSS with Tailwind/PostCSS
npm run build:css

# Build JavaScript with esbuild
npm run build:js

# Build site with processed assets
gozzi build --clean

CI/CD Pipeline

Full workflow with external tools:

#!/bin/bash
# build.sh

# Install dependencies
npm install

# Build assets
npm run build:css
npm run build:js

# Optimize images
npm run optimize-images

# Build site
gozzi build --clean --config config.prod.toml

# Generate search index
python generate-search-index.py

# Deploy
./deploy.sh

Performance Optimization

Build Performance

Content Organization:

content/
├── blog/           # Group related content
│   ├── 2024/       # Year-based organization
│   ├── 2023/
│   └── 2022/
├── docs/           # Separate sections
└── pages/          # Top-level pages

Benefits:

Faster file system operations
Easier to locate content
Better cache locality

Template Optimization:

html

<!-- ❌ Slow: Complex template logic -->
{{ range .Site.AllPages }}
  {{ if and (eq .Type "blog") (gt .Date.Year 2020) }}
    <!-- ... -->
  {{ end }}
{{ end }}

<!-- ✅ Fast: Pre-filtered in Go -->
{{ range .Section.RecentPosts }}
  <!-- ... -->
{{ end }}

Development Server Performance

Selective Watching:

The server only watches relevant files:

*.md in content directory
*.html in templates directory
*.css, *.js in static directory
config.toml

Debounced Rebuilds:

Changes are debounced (500ms delay):

# Rapid saves trigger single rebuild
Save file.md (t=0ms)
Save file.md (t=100ms)
Save file.md (t=200ms)
# → Rebuild at t=700ms (once!)

Incremental Builds:

Only changed content is regenerated:

Edit single blog post → only that post rebuilds
Edit template → all pages using that template rebuild
Edit config → full site rebuild

Shell Scripts and Automation

Development Script

#!/bin/bash
# dev.sh - Start development environment

# Check if port is in use
if lsof -Pi :1313 -sTCP:LISTEN -t >/dev/null ; then
    echo "Port 1313 is in use. Stopping..."
    lsof -ti:1313 | xargs kill -9
fi

# Start development server
echo "Starting Gozzi development server..."
gozzi serve --config config.dev.toml --port 1313

Production Build Script

#!/bin/bash
# build-prod.sh - Build for production

set -e  # Exit on error

echo "Building for production..."

# Clean previous build
rm -rf public/

# Build site
gozzi build --clean --config config.prod.toml

# Verify build
if [ ! -f "public/index.html" ]; then
    echo "Error: Build failed - index.html not found"
    exit 1
fi

echo "✓ Production build complete"
echo "Output directory: public/"

Multi-Environment Script

#!/bin/bash
# build.sh - Build for specified environment

ENV=${1:-dev}

case $ENV in
  dev)
    gozzi serve --config config/config.dev.toml --port 3000
    ;;
  staging)
    gozzi build --clean --config config/config.staging.toml
    ;;
  prod)
    gozzi build --clean --config config/config.prod.toml
    ;;
  *)
    echo "Usage: $0 {dev|staging|prod}"
    exit 1
    ;;
esac

Usage:

./build.sh dev      # Start dev server
./build.sh staging  # Build for staging
./build.sh prod     # Build for production

Best Practices

During Development

Keep server running - Don't restart for most changes
Use incremental builds - Default behavior is optimal
Leverage live reload - See changes instantly
Test in multiple browsers - All reload automatically

Before Production

Use clean builds - --clean flag ensures no stale files
Verify output - Check generated HTML, links, assets
Test production config - Build with production settings locally
Optimize assets - Run image/CSS/JS optimization

Configuration Management

Separate configs per environment - Don't use a single config
Version control configs - Track all config files in git
Document config differences - Comment why settings differ
Use environment variables - For secrets and dynamic values

Content Management

Organize by type/date - Logical content structure
Use consistent front matter - Standardize metadata
Keep drafts separate - Different directory or flag
Version control content - Track changes in git

Build Command - Build command details
Serve Command - Development server features
Troubleshooting - Common issues

Next Steps

Configuration Guide - Configure environments
Content Structure - Organize content
Templates - Develop templates

Usage Patterns ​

Development Workflows ​

Standard Development Workflow ​

Content-First Workflow ​

Theme Development Workflow ​

Multi-Environment Setup ​

Directory Structure ​

Environment-Specific Commands ​

Environment Configurations ​

Content Organization Patterns ​

Multiple Content Sections ​

Draft Content Workflow ​

Content Testing ​

Integration with External Tools ​

Search Index Generation ​

Image Optimization ​

Asset Pipeline ​

CI/CD Pipeline ​

Performance Optimization ​

Build Performance ​

Development Server Performance ​

Shell Scripts and Automation ​

Development Script ​

Production Build Script ​

Multi-Environment Script ​

Best Practices ​

During Development ​

Before Production ​

Configuration Management ​

Content Management ​

Related Resources ​

Next Steps ​

Usage Patterns

Development Workflows

Standard Development Workflow

Content-First Workflow

Theme Development Workflow

Multi-Environment Setup

Directory Structure

Environment-Specific Commands

Environment Configurations

Content Organization Patterns

Multiple Content Sections

Draft Content Workflow

Content Testing

Integration with External Tools

Search Index Generation

Image Optimization

Asset Pipeline

CI/CD Pipeline

Performance Optimization

Build Performance

Development Server Performance

Shell Scripts and Automation

Development Script

Production Build Script

Multi-Environment Script

Best Practices

During Development

Before Production

Configuration Management

Content Management

Related Resources

Next Steps