SSG - Static Site Generator

A fast and flexible static site generator built in Go, designed for simplicity and speed.

Website | Installation | Documentation | Contributing | Security

---

🔍 Overview

SSG is a static site generator written in Go, optimized for converting WordPress exports (Markdown with YAML frontmatter) to blazing-fast static websites. With its simple architecture, multiple template engine support, and powerful asset pipelines, SSG renders a complete site in milliseconds.

What Can You Build?

SSG is perfect for creating:

• � Blogs - Personal or professional blogs migrated from WordPress
• 🏢 Corporate sites - Fast, secure company websites
• 📚 Documentation - Technical docs with clean SEO URLs
• 🎨 Portfolios - Image galleries and creative showcases
• 📄 Landing pages - Marketing and product pages
• 📝 Personal sites - Resumes, CVs, and personal branding

Key Capabilities

Feature	Description
⚡ Lightning Fast	Go-powered generation completes in milliseconds
🎭 Multiple Engines	Go templates, Pongo2 (Jinja2), Mustache, Handlebars
🌐 Hugo Themes	Download and use Hugo themes from GitHub
🖼️ Image Pipeline	WebP conversion with quality control
📦 Asset Bundling	HTML, CSS, JS minification
🔄 Live Reload	Built-in server with file watching
🐳 Docker Ready	Minimal Alpine image (~15MB)
🎬 CI/CD Native	First-class GitHub Actions support

Development Workflow

Use SSG's embedded web server during development to instantly see changes to content, structure, and presentation. The watch mode automatically rebuilds your site when files change:

# Start development server with auto-rebuild
ssg my-content krowy example.com --http --watch

Then deploy to any static hosting:

• Cloudflare Pages - Zero-config with our example workflow
• GitHub Pages - Direct push deployment
• Netlify, Vercel - Drag and drop or Git integration
• Any web server - Just copy the output folder

Asset Processing

SSG includes powerful asset processing:

• Image Processing - Convert JPG/PNG to WebP with configurable quality
• HTML Minification - Remove whitespace, comments, optimize output
• CSS Minification - Bundle and compress stylesheets
• JS Minification - Optimize JavaScript files
• SEO Automation - Sitemap, robots.txt, clean URLs, meta tags

✨ Features

Core Features

• 🚀 Fast generation - Go-powered, millisecond builds
• 📝 Markdown - Full support with YAML frontmatter
• 🎨 Built-in templates - simple (dark) and krowy (green/natural)
• 📱 Responsive - Mobile-first design
• ♿ Accessible - WCAG 2.2 compliant
• 🔍 SEO - Clean URLs, sitemap, robots.txt

Template Engines

• 🔧 Go Templates - Default, powerful templating (.Variable)
• 🐍 Pongo2 - Jinja2/Django syntax (for loops, filters)
• 👨‍🦱 Mustache - Logic-less templates (sections)
• 🔨 Handlebars - Semantic templates (each blocks)

Development

• 🌐 HTTP Server - Built-in dev server (--http)
• 👀 Watch Mode - Auto-rebuild on changes (--watch)
• 📄 Config Files - YAML, TOML, JSON support
• 🧹 Clean Builds - Fresh output (--clean)

Production

• 🖼️ WebP Conversion - Optimized images (--webp)
• 🗄️ Minification - HTML, CSS, JS (--minify-all)
• 📦 Deployment Package - Cloudflare Pages ready (--zip)
• 🐳 Docker - Multi-arch Alpine image

Integration

• 🎬 GitHub Actions - Use as CI/CD step
• 🌍 Online Themes - Download Hugo themes from URL
• 📁 WordPress - Import from WP exports

📦 Requirements

• Go 1.25 or later
• Make (optional, for Makefile)
• cwebp (optional, for WebP conversion)

🚀 Installation

Quick Install (Linux/macOS)

curl -sSL https://raw.githubusercontent.com/spagu/ssg/main/install.sh | bash

Package Managers

Platform	Command
Homebrew (macOS/Linux)	brew install spagu/tap/ssg
Snap (Ubuntu)	snap install ssg
Debian/Ubuntu	wget https://github.com/spagu/ssg/releases/download/v1.3.0/ssg_1.3.0_amd64.deb && sudo dpkg -i ssg_1.3.0_amd64.deb
Fedora/RHEL	sudo dnf install https://github.com/spagu/ssg/releases/download/v1.3.0/ssg-1.3.0-1.x86_64.rpm
FreeBSD	pkg install ssg or from ports
OpenBSD	From ports: /usr/ports/www/ssg

Binary Downloads

Download pre-built binaries from GitHub Releases:

Platform	AMD64	ARM64
Linux	ssg-linux-amd64.tar.gz	ssg-linux-arm64.tar.gz
macOS	ssg-darwin-amd64.tar.gz	ssg-darwin-arm64.tar.gz
FreeBSD	ssg-freebsd-amd64.tar.gz	ssg-freebsd-arm64.tar.gz
Windows	ssg-windows-amd64.zip	ssg-windows-arm64.zip

From Source

git clone https://github.com/spagu/ssg.git
cd ssg
make build
sudo make install

Docker

# Pull image from GitHub Container Registry
docker pull ghcr.io/spagu/ssg:latest

# Run SSG in container
docker run --rm -v $(pwd):/site ghcr.io/spagu/ssg:latest \
    my-content krowy example.com --webp

# Or use docker-compose
docker compose run --rm ssg my-content krowy example.com

# Development server with watch mode
docker compose up dev

📖 Full installation guide: docs/INSTALL.md

💻 Usage

Syntax

ssg <source> <template> <domain> [options]

Arguments

Argument	Description
source	Source folder name (inside content-dir)
template	Template name (inside templates-dir)
domain	Target domain for the generated site

Configuration File

SSG supports configuration files in YAML, TOML, or JSON format. Auto-detects: .ssg.yaml, .ssg.toml, .ssg.json

# Use explicit config file
ssg --config .ssg.yaml

# Or just create .ssg.yaml and run ssg (auto-detected)
ssg

Example .ssg.yaml:

source: "my-content"
template: "krowy"
domain: "example.com"

http: true
watch: true
clean: true
webp: true
webp_quality: 80
minify_all: true

See .ssg.yaml.example for all options.

Options

Configuration:

Option	Description
--config=FILE	Load config from YAML/TOML/JSON file

Server & Development:

Option	Description
--http	Start built-in HTTP server (default port: 8888)
--port=PORT	HTTP server port (default: 8888)
--watch	Watch for changes and rebuild automatically
--clean	Clean output directory before build

Output Control:

Option	Description
--sitemap-off	Disable sitemap.xml generation
--robots-off	Disable robots.txt generation
--pretty-html	Prettify HTML (remove all blank lines)
--relative-links	Convert absolute URLs to relative links
--post-url-format=FMT	Post URL format: date (default: /YYYY/MM/DD/slug/) or slug (/slug/)
--minify-all	Minify HTML, CSS, and JS
--minify-html	Minify HTML output
--minify-css	Minify CSS output
--minify-js	Minify JS output
--sourcemap	Include source maps in output

Image Processing (Native Go - no external tools needed):

Option	Description
--webp	Convert images to WebP format (requires cwebp)
--webp-quality=N	WebP compression quality 1-100 (default: 60)

Deployment:

Option	Description
--zip	Create ZIP file for Cloudflare Pages

Paths:

Option	Description
--content-dir=PATH	Content directory (default: content)
--templates-dir=PATH	Templates directory (default: templates)
--output-dir=PATH	Output directory (default: output)

Template Engine:

Option	Description
--engine=ENGINE	Template engine: go (default), pongo2, mustache, handlebars
--online-theme=URL	Download theme from URL (GitHub, GitLab, or direct ZIP)

Other:

Option	Description
--quiet, -q	Suppress output (only exit codes)
--version, -v	Show version
--help, -h	Show help

Shortcodes

Define reusable content snippets in your config file. Each shortcode requires a template file:

shortcodes:
  - name: "thunderpick"
    template: "shortcodes/banner.html"  # Required: template in theme folder
    title: "Thunderpick"
    text: "100% up to $1000 + 5% rakeback"
    url: "https://example.com/promo"
    logo: "/assets/images/thunderpick.png"
    legal: "18+. Gamble Responsibly. T&Cs Apply."

Create the template file (e.g., templates/your-theme/shortcodes/banner.html):

<div class="promo-banner">
  <a href="{{.URL}}">
    {{if .Logo}}<img src="{{.Logo}}" alt="{{.Name}}">{{end}}
    <strong>{{.Title}}</strong>
    <span>{{.Text}}</span>
  </a>
  {{if .Legal}}<small>{{.Legal}}</small>{{end}}
</div>

Use in markdown content with {{shortcode_name}}:

Check out this amazing offer:

{{thunderpick}}

Don't miss it!

Available template variables: {{.Name}}, {{.Title}}, {{.Text}}, {{.URL}}, {{.Logo}}, {{.Legal}}, {{.Data.key}}

Examples

# Development mode: HTTP server + auto-rebuild on changes
./build/ssg my-content krowy example.com --http --watch

# HTTP server on custom port
./build/ssg my-content krowy example.com --http --port=3000

# Generate site with krowy template
./build/ssg krowy.net.2026-01-13110345 krowy krowy.net

# Generate with simple template (dark theme)
./build/ssg krowy.net.2026-01-13110345 simple krowy.net

# Generate with WebP conversion and ZIP package
./build/ssg krowy.net.2026-01-13110345 krowy krowy.net --webp --zip

# Use custom directories
./build/ssg my-content my-template example.com \
  --content-dir=/data/content \
  --templates-dir=/data/templates \
  --output-dir=/var/www/html

# Or using Makefile
make generate        # krowy template
make generate-simple # simple template
make serve           # generate and run local server
make deploy          # generate with WebP + ZIP for Cloudflare Pages

Output

Generated files will be in the output/ folder:

output/
├── index.html          # Homepage
├── css/
│   └── style.css       # Stylesheet
├── js/
│   └── main.js         # JavaScript
├── media/              # Media files
├── {slug}/             # Pages and posts (SEO URLs)
│   └── index.html
├── category/
│   └── {category-slug}/
│       └── index.html
├── sitemap.xml         # Sitemap for search engines
├── robots.txt          # Robots file
├── _headers            # Cloudflare Pages headers
└── _redirects          # Cloudflare Pages redirects

🔧 Template Engines

SSG supports multiple template engines. By default, Go templates are used, but you can switch to other engines:

Available Engines

Engine	Flag	Syntax Style
Go (default)	--engine=go	.Variable, range .Items
Pongo2	--engine=pongo2	Jinja2/Django: for item in items
Mustache	--engine=mustache	variable, #items
Handlebars	--engine=handlebars	variable, #each items

Usage Examples

# Use Pongo2 (Jinja2/Django syntax)
ssg my-content mytheme example.com --engine=pongo2

# Use Mustache
ssg my-content mytheme example.com --engine=mustache

# Use Handlebars
ssg my-content mytheme example.com --engine=handlebars

Online Themes

Download themes directly from GitHub, GitLab, or any ZIP URL:

# Download Hugo theme from GitHub
ssg my-content bearblog example.com --online-theme=https://github.com/janraasch/hugo-bearblog

# Download from any URL
ssg my-content mytheme example.com --online-theme=https://example.com/theme.zip

The theme will be downloaded and extracted to templates/{template-name}/.

Template Syntax Comparison

Go Templates:

{% raw %}

{{ range .Posts }}
  <h2>{{ .Title }}</h2>
  <p>{{ .Content }}</p>
{{ end }}

{% endraw %}

Pongo2 (Jinja2):

{% raw %}

{% for post in Posts %}
  <h2>{{ post.Title }}</h2>
  <p>{{ post.Content }}</p>
{% endfor %}

{% endraw %}

Mustache:

{% raw %}

{{#Posts}}
  <h2>{{Title}}</h2>
  <p>{{Content}}</p>
{{/Posts}}

{% endraw %}

Handlebars:

{% raw %}

{{#each Posts}}
  <h2>{{Title}}</h2>
  <p>{{Content}}</p>
{{/each}}

{% endraw %}

🎬 GitHub Actions

Use SSG as a GitHub Action in your CI/CD pipeline:

Versioning

Reference	Description
spagu/ssg@main	Latest from main branch (development)
spagu/ssg@v1	Latest stable v1.x release
spagu/ssg@v1.3.0	Specific version

Note: Use @main until a stable release is published.

Basic Usage

- name: Generate static site
  uses: spagu/ssg@main  # or @v1 after release
  with:
    source: 'my-content'
    template: 'krowy'
    domain: 'example.com'

Full Configuration

{% raw %}

- name: Generate static site
  id: ssg
  uses: spagu/ssg@v1
  with:
    source: 'my-content'           # Content folder (inside content/)
    template: 'krowy'              # Template: 'simple' or 'krowy'
    domain: 'example.com'          # Target domain
    version: 'latest'              # Optional: SSG version (default: latest)
    content-dir: 'content'         # Optional: content directory path
    templates-dir: 'templates'     # Optional: templates directory path
    output-dir: 'output'           # Optional: output directory path
    webp: 'true'                   # Optional: convert images to WebP
    webp-quality: '80'             # Optional: WebP quality 1-100 (default: 60)
    zip: 'true'                    # Optional: create ZIP for deployment
    minify: 'true'                 # Optional: minify HTML/CSS/JS
    clean: 'true'                  # Optional: clean output before build

- name: Show outputs
  run: |
    echo "Output path: ${{ steps.ssg.outputs.output-path }}"
    echo "ZIP file: ${{ steps.ssg.outputs.zip-file }}"
    echo "ZIP size: ${{ steps.ssg.outputs.zip-size }} bytes"

{% endraw %}

Action Inputs

Input	Description	Required	Default
source	Content source folder name	✅	-
template	Template name	✅	simple
domain	Target domain	✅	-
version	SSG version to download	❌	latest
content-dir	Path to content directory	❌	content
templates-dir	Path to templates directory	❌	templates
output-dir	Path to output directory	❌	output
webp	Convert images to WebP	❌	false
webp-quality	WebP compression quality 1-100	❌	60
zip	Create ZIP file	❌	false
minify	Minify HTML, CSS, and JS	❌	false
clean	Clean output directory before build	❌	false

Action Outputs

Output	Description
output-path	Path to generated site directory
zip-file	Path to ZIP file (if --zip used)
zip-size	Size of ZIP file in bytes

Deploy to Cloudflare Pages

{% raw %}

name: Deploy

on:
  push:
    branches: [main]

jobs:
  deploy:
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v6

      - name: Generate site
        id: ssg
        uses: spagu/ssg@v1
        with:
          source: 'my-content'
          template: 'krowy'
          domain: 'example.com'
          webp: 'true'

      - name: Deploy to Cloudflare
        uses: cloudflare/pages-action@v1
        with:
          apiToken: ${{ secrets.CLOUDFLARE_API_TOKEN }}
          accountId: ${{ secrets.CLOUDFLARE_ACCOUNT_ID }}
          projectName: 'my-site'
          directory: ${{ steps.ssg.outputs.output-path }}

{% endraw %}

📁 Complete workflow examples are available in examples/workflows/.

📁 Project Structure

ssg/
├── cmd/
│   └── ssg/
│       └── main.go           # CLI entry point
├── internal/
│   ├── generator/
│   │   ├── generator.go      # Generator logic
│   │   ├── generator_test.go # Generator tests
│   │   └── templates.go      # Default HTML templates
│   ├── models/
│   │   └── content.go        # Data models
│   └── parser/
│       ├── markdown.go       # Markdown parser
│       └── markdown_test.go  # Parser tests
├── content/                  # Source data
│   └── {source}/
│       ├── metadata.json
│       ├── media/
│       ├── pages/
│       └── posts/
├── templates/                # Templates
│   ├── simple/
│   │   ├── css/
│   │   └── js/
│   └── krowy/
│       ├── css/
│       └── js/
├── output/                   # Generated site (gitignored)
├── go.mod
├── go.sum
├── Makefile
├── README.md
├── CHANGELOG.md
├── .gitignore
└── .dockerignore

🎨 Templates

simple - Modern Dark Theme

Elegant dark theme with glassmorphism and gradients:

• Dark background: #0f0f0f
• Cards: #222222
• Accent: purple gradient #6366f1 → #a855f7
• Hover animations and micro-interactions

krowy - Green Farm Theme

Natural light theme inspired by krowy.net:

• Light background: #f8faf5
• Cards: #ffffff
• Accent: green #2d7d32
• Cow icon 🐄 in logo
• Nature and ecology focus

🎨 Styles/Colors

Color Guidelines (WCAG 2.2 Compliant)

Simple Template (Dark)

/* Background */
--color-bg-primary: #0f0f0f;
--color-bg-secondary: #1a1a1a;
--color-bg-card: #222222;

/* Text (minimum contrast 4.5:1) */
--color-text-primary: #ffffff;
--color-text-secondary: #b3b3b3;
--color-text-muted: #808080;

/* Accent */
--color-accent: #6366f1;
--gradient-primary: linear-gradient(135deg, #6366f1 0%, #8b5cf6 50%, #a855f7 100%);

Krowy Template (Light)

/* Background */
--color-bg-primary: #f8faf5;
--color-bg-secondary: #ffffff;
--color-bg-card: #ffffff;

/* Text (minimum contrast 4.5:1) */
--color-text-primary: #1a2e1a;
--color-text-secondary: #3d5a3d;
--color-text-muted: #6b8a6b;

/* Accent */
--color-accent: #2d7d32;
--gradient-primary: linear-gradient(135deg, #2d7d32 0%, #43a047 50%, #66bb6a 100%);

Detailed style documentation: docs/STYLES.md

🏗️ Architecture

flowchart TB
    subgraph Input["📥 Input"]
        A[content/source] --> B[metadata.json]
        A --> C[pages/*.md]
        A --> D[posts/**/*.md]
        A --> E[media/*]
    end

    subgraph Processing["⚙️ Processing"]
        F[Parser] --> G[Models]
        G --> H[Generator]
        T[Templates] --> H
    end

    subgraph Output["📤 Output"]
        H --> I[output/]
        I --> J[index.html]
        I --> K[pages/]
        I --> L[posts/]
        I --> M[category/]
        I --> N[css/]
        I --> O[js/]
        I --> P[media/]
    end

    B --> F
    C --> F
    D --> F
    E --> P

Loading

🧪 Testing

# Run all tests
make test

# Tests with coverage
make test-coverage

# Open coverage report
open coverage.html

🛠️ Development

Available Make Commands

make help           # Show all commands
make all            # deps + lint + test + build
make build          # Build binary
make test           # Run tests
make lint           # Check code
make run            # Build and run
make generate       # Generate site (krowy template)
make generate-simple # Generate site (simple template)
make serve          # Generate and serve locally
make deploy         # Generate with WebP + ZIP for Cloudflare Pages
make clean          # Clean artifacts
make install        # Install binary to /usr/local/bin

Creating Your Own Template

1. Create a folder in templates/your-template-name/
2. Add files:
   • css/style.css
   • js/main.js (optional)
   • index.html, page.html, post.html, category.html (optional)
3. HTML templates are generated automatically if missing

📄 License

BSD 3-Clause License - see LICENSE

👥 Authors

• spagu - GitHub