ssssg

package module
v0.0.6 Latest Latest
Warning

This package is not in the latest version of its module.

 Go to latest Published: Feb 8, 2026 License: MIT Imports: 25 Imported by: 0

README

ssssg - Super Simple Static Site Generator

go coverage go-report

Define data and URLs in YAML, write HTML with Go templates, and build to generate static HTML.

Install

go install github.com/sters/ssssg@latest

or use specific version from Releases.

Quick Start

# Initialize a new project
ssssg init mysite
cd mysite

# Build the site
ssssg build

Usage

ssssg build                       # Build with defaults (site.yaml)
ssssg build --config site.yaml    # Specify config file
ssssg build --templates templates/
ssssg build --static static/
ssssg build --output public/
ssssg build --timeout 30s

ssssg init                        # Initialize in current directory
ssssg init mysite                 # Initialize in specified directory

ssssg version                     # Show version info

Project Structure

my-site/
  site.yaml          # Site definition (data, URLs, pages)
  templates/
    _layout.html      # Shared layout (_ prefix = shared file)
    _header.html      # Partial
    _footer.html      # Partial
    index.html        # Page template
  static/             # Static files (copied to output as-is)
  public/             # Output directory (generated)

site.yaml

global:
  layout: "_layout.html"
  data:
    site_name: "My Site"
  fetch:
    reset_css: "https://cdn.example.com/reset.css"
    custom_css: "static/style.css"

pages:
  - template: "index.html"
    output: "index.html"
    data:
      title: "Home"
      greeting: "Welcome!"
    fetch:
      projects: "https://api.example.com/projects.json"

  - template: "about.html"
    output: "about/index.html"
    layout: "_other_layout.html"
    data:
      title: "About"

Templates

Templates use Go's html/template syntax. Data is accessed via .Global, .Page, and .Static:

{{ .Global.site_name }}
{{ .Page.title }}
{{ .Global.reset_css | raw }}

Use | raw for fetched HTML/CSS content that should not be escaped.

Static File Metadata

.Static provides metadata for all files in the output directory (scanned after pipeline processing). Each entry is a StaticFileInfo with these fields:

Field Type Description
Path string Forward-slash relative path (e.g. img/photo.png)
Size int64 File size in bytes
Width int Image width in px (0 if not an image)
Height int Image height in px (0 if not an image)

Supported image formats: JPEG, PNG, GIF, WebP.

{{ $img := index .Static "img/photo.png" }}
{{ if $img.Path }}
  <img src="/img/photo.png" width="{{ $img.Width }}" height="{{ $img.Height }}">
{{ end }}

Accessing a non-existent key returns a zero-value struct (no error), so you can safely check $img.Path for existence.

Static File Pipelines

By default, files in static/ are copied to the output directory as-is. You can define pipelines to process matched files with shell commands:

static:
  pipelines:
    - match: "*.jpg"
      commands:
        - "cp {{.Src}} {{.Dest}}"
        - "mogrify -resize 800x600 {{.Dest}}"
        - "jpegoptim --strip-all {{.Dest}}"
    - match: "*.png"
      commands:
        - "cp {{.Src}} {{.Dest}}"
        - "optipng -o2 {{.Dest}}"
    - match: "images/*.webp"
      commands:
        - "cwebp -q 80 {{.Src}} -o {{.Dest}}"
Matching rules
  • Pattern without /: matches against the basename (e.g. *.jpg matches images/photo.jpg)
  • Pattern with /: matches against the relative path from static directory (e.g. images/*.webp)
  • First matching pipeline wins
  • Unmatched files are copied as-is
Template variables

Commands are processed with Go text/template. Available variables:

Variable Description Example
{{.Src}} Source absolute path /path/to/static/photo.jpg
{{.Dest}} Destination absolute path /path/to/public/photo.jpg
{{.Dir}} Destination directory /path/to/public
{{.Name}} File name photo.jpg
{{.Ext}} Extension .jpg
{{.Base}} Name without extension photo

Documentation

Index

Constants

This section is empty.

Variables

This section is empty.

Functions

func Build 

func Build(ctx context.Context, opts BuildOptions) error

func CopyStatic 

func CopyStatic(staticDir, outputDir string) error

func Init 

func Init(dir string) error

func ProcessStatic added in v0.0.3 

func ProcessStatic(ctx context.Context, staticDir, outputDir string, pipelines []PipelineConfig, parallelism int) error

ProcessStatic walks the static directory and processes each file. Files matching a pipeline have their commands executed in order. Unmatched files are copied using copyFile.

func RenderPage 

func RenderPage(templateDir string, page PageConfig, globalLayout string, data TemplateData, outputDir string) error

func ScanStaticFiles added in v0.0.4 

func ScanStaticFiles(dir string, parallelism int) (map[string]StaticFileInfo, error)

ScanStaticFiles walks dir and returns metadata for every file found. Image files (.jpg, .jpeg, .png, .gif, .webp) have Width/Height populated via image.DecodeConfig (header-only, fast). Errors on individual files are silently ignored so that a broken image never stops the build.

Types

type BuildOptions 

type BuildOptions struct {
	ConfigPath  string
	TemplateDir string
	StaticDir   string
	OutputDir   string
	Timeout     time.Duration
	Clean       bool
	Log         io.Writer
	Parallelism int
}

type Config 

type Config struct {
	Global GlobalConfig `yaml:"global"`
	Pages  []PageConfig `yaml:"pages"`
	Static StaticConfig `yaml:"static"`
}

func LoadConfig 

func LoadConfig(path string) (*Config, error)

type Fetcher 

type Fetcher struct {
	// contains filtered or unexported fields
}

func NewFetcher 

func NewFetcher(baseDir string, client *http.Client) *Fetcher

func (*Fetcher) Fetch 

func (f *Fetcher) Fetch(ctx context.Context, source string) (string, error)

func (*Fetcher) ResolveFetchMap 

func (f *Fetcher) ResolveFetchMap(ctx context.Context, fetchMap map[string]string) (map[string]string, error)

type GlobalConfig 

type GlobalConfig struct {
	Layout string            `yaml:"layout"`
	Data   map[string]any    `yaml:"data"`
	Fetch  map[string]string `yaml:"fetch"`
}

type PageConfig 

type PageConfig struct {
	Template string            `yaml:"template"`
	Output   string            `yaml:"output"`
	Layout   string            `yaml:"layout"`
	Data     map[string]any    `yaml:"data"`
	Fetch    map[string]string `yaml:"fetch"`
}

type PipelineConfig added in v0.0.3 

type PipelineConfig struct {
	Match    string   `yaml:"match"`
	Commands []string `yaml:"commands"`
}

type PipelineData added in v0.0.3 

type PipelineData struct {
	Src  string // Source file absolute path
	Dest string // Destination file absolute path
	Dir  string // Destination directory
	Name string // File name
	Ext  string // File extension
	Base string // File name without extension
}

PipelineData holds template variables available in pipeline command strings.

type StaticConfig added in v0.0.3 

type StaticConfig struct {
	Pipelines []PipelineConfig `yaml:"pipelines"`
}

type StaticFileInfo added in v0.0.4 

type StaticFileInfo struct {
	Path   string // forward-slash relative path
	Size   int64  // file size in bytes
	Width  int    // image width in px, 0 if not an image
	Height int    // image height in px, 0 if not an image
}

type TemplateData 

type TemplateData struct {
	Global map[string]any
	Page   map[string]any
	Static map[string]StaticFileInfo
}

Source Files

View all Source files

Directories

Path Synopsis
cmd
ssssg command

Jump to

Keyboard shortcuts

? : This menu
/ : Search site
f or F : Jump to
y or Y : Canonical URL
go.dev uses cookies from Google to deliver and enhance the quality of its services and to analyze traffic. Learn more.