Crate ssg

Expand description

SSG logo

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.33"

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

§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

Re-exports§

pub use staticdatagen;

Modules§

cache: Content fingerprinting for incremental builds. Content fingerprinting for incremental builds.
cmd: Command Line Interface Module
livereload: WebSocket-based live-reload script injection. Live-reload script injection plugin.
plugin: Lifecycle hook plugin system.
plugins: Built-in plugins for common tasks.
process: Command-line argument processing and site compilation.
schema: JSON Schema generation for configuration.
search: Client-side search index generator and search UI. Client-side search index generator.
seo: SEO plugins: meta tags, robots.txt, and canonical URLs. SEO plugins for the static site generator.
stream: High-performance streaming file processor. High-performance streaming file processor.
watch: File-watching for live rebuild. File-watching module for the static site generator.

Structs§

Paths: Represents the necessary directory paths for the site generator.
PathsBuilder: Builder for creating Paths configurations

Constants§

MAX_DIR_DEPTH: Maximum directory nesting depth for all traversal operations. Prevents stack overflow from pathological or circular directory trees. 128 levels accommodates any realistic project structure.

Functions§

collect_files_recursive: Recursively collects all file paths within a directory.
compile_site: Compiles the static site from source directories.
copy_dir_all: Recursively copies a directory whilst maintaining structure and attributes.
copy_dir_all_async: Asynchronously copies an entire directory structure, preserving file attributes and handling nested directories.
copy_dir_with_progress: Copies directories with a progress bar for feedback.
create_directories: Creates and verifies required directories for site generation.
create_log_file: Creates and initialises a log file for the static site generator.
handle_server: Configures and launches the development server.
is_safe_path: Checks if a given path is safe to use.
log_arguments: Logs processed command-line arguments for debugging and auditing.
log_initialization: Records system initialisation in the logging system.
prepare_serve_dir: Prepares the serve directory by creating it and copying site files.
run: Executes the static site generation process.
serve_site: Converts a site directory path to a string and starts an HTTP server.
verify_and_copy_files: Validates and copies files from source to destination.
verify_and_copy_files_async: Asynchronously validates and copies files between directories.
verify_file_safety: Verifies the safety of a file for processing.

Crate ssg

Crate ssg Copy item path

Static Site Generator (SSG)

§Install

§Overview

§Architecture

§Features

§The CLI

§First 5 Minutes

§Library Usage

§Benchmarks

§Development

§What’s Included

§License

Re-exports§

Modules§

Structs§

Constants§

Functions§

Crate ssg