Static Site Generator (SSG)

Fast, memory-safe, and extensible — built in Rust.

---

Install

cargo install ssg

Or add as a library dependency:

[dependencies]
ssg = "0.0.34"

You need Rust 1.74.0 or later. Works on macOS, Linux, and Windows.

---

Overview

SSG generates static websites from Markdown content, YAML frontmatter, and HTML templates. It compiles everything into production-ready HTML with built-in SEO metadata, accessibility compliance, and feed generation. The plugin system handles the rest.

• Zero-cost performance through Rust's ownership model and parallel file operations
• Incremental builds with content fingerprinting — only changed files are reprocessed
• File watching with automatic rebuild on content changes
• Plugin architecture with lifecycle hooks for custom processing
• WCAG 2.1 Level AA accessibility compliance in generated output

---

Architecture

graph TD
    A[Content: Markdown + YAML] --> B{SSG CLI}
    B --> C[Incremental Cache]
    C --> D[Compile: staticdatagen]
    D --> E[Plugin Pipeline]
    E --> F[Minify / Optimize / Deploy]
    D --> G[Dev Server: Warp]
    B --> H[File Watcher]
    H -->|changed files| C

Loading

---

Features

Performance	Parallel file operations with Rayon, iterative traversal with depth bounds, incremental builds
Content	Markdown, YAML frontmatter, JSON, TOML. Atom and RSS feed generation
SEO	Meta tags, Open Graph, sitemaps, structured data, canonical URLs
Accessibility	Automatic WCAG 2.1 Level AA compliance
Theming	Custom HTML templates with variable substitution
Plugins	Lifecycle hooks: before_compile, after_compile, on_serve. Built-in minify, image-opti, deploy
Watch mode	Polling-based file watcher with configurable interval
Caching	Content fingerprinting via .ssg-cache.json for fast rebuilds
Config	TOML config files with JSON Schema for IDE autocomplete (ssg.schema.json)
Security	#![forbid(unsafe_code)], path traversal prevention, symlink rejection, file size limits
CI	Multi-platform test matrix (macOS, Linux, Windows), cargo audit, cargo deny, SBOM generation

---

The CLI

Command	What it does
ssg -n mysite -c content -o build -t templates	Generate a site from source directories
ssg --config config.toml	Load configuration from a TOML file
ssg --serve public	Serve from a specific directory
ssg --watch	Watch content for changes and rebuild

Full CLI reference

Usage: ssg [OPTIONS]

Options:
  -f, --config <FILE>   Configuration file path
  -n, --new <NAME>      Create new project
  -c, --content <DIR>   Content directory
  -o, --output <DIR>    Output directory
  -t, --template <DIR>  Template directory
  -s, --serve <DIR>     Development server directory
  -w, --watch           Watch for changes
  -h, --help            Print help
  -V, --version         Print version

When no flags are provided, sensible defaults are used (content/, public/, templates/).

---

First 5 Minutes

# 1. Install
cargo install ssg

# 2. Create a site
ssg -n mysite -c content -o build -t templates

# 3. Or run the examples
git clone https://github.com/sebastienrousseau/shokunin.git
cd shokunin
cargo run --example basic
cargo run --example quickstart
cargo run --example multilingual

---

Library Usage

use staticdatagen::compiler::service::compile;
use std::path::Path;

fn main() -> anyhow::Result<()> {
    let build_dir = Path::new("build");
    let content_dir = Path::new("content");
    let site_dir = Path::new("public");
    let template_dir = Path::new("templates");

    compile(build_dir, content_dir, site_dir, template_dir)?;
    println!("Site generated successfully!");
    Ok(())
}

Plugin example

use ssg::plugin::{Plugin, PluginContext, PluginManager};
use anyhow::Result;
use std::path::Path;

#[derive(Debug)]
struct LogPlugin;

impl Plugin for LogPlugin {
    fn name(&self) -> &str { "logger" }
    fn after_compile(&self, ctx: &PluginContext) -> Result<()> {
        println!("Site compiled to {:?}", ctx.site_dir);
        Ok(())
    }
}

let mut pm = PluginManager::new();
pm.register(LogPlugin);
pm.register(ssg::plugins::MinifyPlugin);

let ctx = PluginContext::new(
    Path::new("content"),
    Path::new("build"),
    Path::new("public"),
    Path::new("templates"),
);
pm.run_after_compile(&ctx).unwrap();

Incremental build example

use ssg::cache::BuildCache;
use std::path::Path;

let cache_path = Path::new(".ssg-cache.json");
let content_dir = Path::new("content");

let mut cache = BuildCache::load(cache_path).unwrap();
let changed = cache.changed_files(content_dir).unwrap();

if changed.is_empty() {
    println!("No changes detected, skipping build.");
} else {
    println!("Rebuilding {} changed files", changed.len());
    // ... run build ...
    cache.update(content_dir).unwrap();
    cache.save().unwrap();
}

---

Benchmarks

Metric	Value
Release binary	~5 MB (stripped, LTO)
Unsafe code	0 blocks — #![forbid(unsafe_code)] enforced
Test suite	342 tests in < 2 seconds
Dependencies	19 direct, all audited
Coverage	98% library line coverage

---

Development

make build        # Build the project
make test         # Run all tests
make lint         # Lint with Clippy
make format       # Format with rustfmt
make deny         # Check licenses and advisories

See CONTRIBUTING.md for setup, signed commits, and PR guidelines.

---

What's Included

Core modules

• cmd — CLI argument parsing, configuration management, input validation
• process — Directory creation, frontmatter preprocessing, site compilation
• plugin — Trait-based plugin system with lifecycle hooks
• plugins — Built-in MinifyPlugin, ImageOptiPlugin, DeployPlugin
• cache — Content fingerprinting for incremental builds
• watch — Polling-based file watcher for live rebuild
• schema — JSON Schema generator for configuration

Security and compliance

• #![forbid(unsafe_code)] across the entire codebase
• Path traversal prevention with .. detection and symlink rejection
• File size limits (10 MB per file) and directory depth bounds (128 levels)
• cargo audit with zero warnings — all advisories tracked in .cargo/audit.toml
• cargo deny — license, advisory, ban, and source checks all pass
• SBOM generated as a release artifact
• Signed commits enforced via SSH ED25519

Test coverage

• 342 total tests (197 unit + 23 doc-tests + 36 integration + 86 serde_yml)
• 98% library line coverage measured with cargo-llvm-cov
• Multi-platform CI — macOS, Ubuntu, Windows (stable + nightly)

---

THE ARCHITECT ᛫ Sebastien Rousseau THE ENGINE ᛞ EUXIS ᛫ Enterprise Unified Execution Intelligence System

---

License

Dual-licensed under Apache 2.0 or MIT, at your option.

Back to Top