ssg 0.0.35

Contents

• Install — prerequisites, crate, library dependency
• Overview — what SSG does
• Architecture — build pipeline diagram
• Features — capability matrix
• The CLI — flags and usage
• First 5 Minutes — clone → tests passing
• Library Usage — ssg::run(), plugins, incremental builds
• Benchmarks — binary size, test suite, coverage
• Development — make targets, contributing
• What's Included — modules, security, tests
• License

Install

Prerequisites

SSG requires Rust 1.88.0 or later (pinned in rust-toolchain.toml). Verify with rustc --version.

Crate

cargo install ssg

Or add as a library dependency:

[dependencies]
ssg = "0.0.35"

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: http_handle]
    B --> H[File Watcher]
    H -->|changed files| C

Features

The CLI

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 and rebuild
      --drafts           Include draft pages in the build
      --deploy <TARGET>  Generate deployment config (netlify, vercel, cloudflare, github)
  -q, --quiet            Suppress non-error output
      --verbose          Show detailed build information
  -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                       # macOS / Linux / Windows

# 2 — Scaffold + build a brand-new site
ssg -n mysite -c content -o build -t templates

# 3 — Or build from source and run the bundled examples
git clone https://github.com/sebastienrousseau/shokunin.git
cd shokunin
cargo build                             # ~2 min cold, < 10 s incremental
cargo test --lib                        # 741 tests, ~8 s on M-series Mac
cargo run --example basic               # minimal site
cargo run --example quickstart          # opinionated defaults
cargo run --example plugins             # plugin pipeline walk-through
cargo run --example multilingual        # 28 locales + localized search

On WSL/Linux the same commands work verbatim. On native Windows, replace make targets with their cargo equivalents (see Development).

One-command bootstrap

make init       # detects platform, installs rustfmt + clippy + cargo-deny,
                # wires up the signed-commit git hook, and runs cargo build

WSL2 troubleshooting

The bundled dev server binds to 127.0.0.1:3000 (or :8000 for the CLI). On WSL2, that loopback is reachable from your Windows host as long as localhostForwarding is enabled (the default since the Microsoft Store version of WSL). If your browser can't reach the site, override the bind address with environment variables — no code changes needed:

SSG_HOST=0.0.0.0 SSG_PORT=8080 cargo run --example multilingual

The same vars work for ssg --serve. Use 0.0.0.0 for Codespaces, dev-containers, and any remote-dev setup where the listener needs to be reachable from outside its network namespace.

Library Usage

// The simplest path: delegate to ssg's own pipeline.
#[tokio::main]
async fn main() -> anyhow::Result<()> {
    ssg::run().await
}

If you only want the compile primitive (no plugin pipeline, no dev server), depend on staticdatagen directly:

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

fn main() -> anyhow::Result<()> {
    compile(
        Path::new("build"),
        Path::new("content"),
        Path::new("public"),
        Path::new("templates"),
    )?;
    Ok(())
}

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(())
    }
}

fn main() -> Result<()> {
    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)?;
    Ok(())
}

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

Development

make init         # One-command bootstrap (rustfmt + clippy + cargo-deny + hooks + build)
make build        # Build the project
make test         # Run all tests
make bench        # Run performance benchmarks (Criterion)
make lint         # Lint with Clippy
make format       # Format with rustfmt
make deny         # Check licenses and advisories
make doc          # Generate API docs and open in browser
make clean        # Remove build artifacts and stray logs
make hooks        # Install the signed-commit git hook

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

What's Included

• cmd — CLI argument parsing, SsgConfig, input validation
• process — Argument-driven site processing and directory creation
• lib — Orchestrator: run() → plugin pipeline → compile → serve
• plugin — Plugin trait with before_compile, after_compile, on_serve 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
• scaffold — Project scaffolding (ssg --new)
• frontmatter — Frontmatter extraction and .meta.json sidecar support
• tera_engine — Tera templating engine integration
• tera_plugin — Tera template rendering plugin
• seo — SeoPlugin, JsonLdPlugin, CanonicalPlugin, RobotsPlugin
• search — Client-side search index generation + localized SearchLabels
• accessibility — Automated WCAG checker and ARIA validation
• ai — AI-readiness content hooks (alt-text validation, llms.txt)
• deploy — Deployment adapters (Netlify, Vercel, Cloudflare, GitHub Pages)
• assets — Asset fingerprinting and SRI hash generation
• highlight — Syntax highlighting plugin for code blocks
• shortcodes — Shortcode expansion (youtube, gist, figure, admonitions)
• markdown_ext — GFM extensions (tables, strikethrough, task lists)
• image_plugin — Image optimization with WebP output and responsive srcset
• livereload — WebSocket live-reload injection
• pagination — Pagination plugin for listing pages
• taxonomy — Taxonomy generation (tags, categories)
• drafts — Draft content filtering plugin
• stream — High-performance streaming file processor
• walk — Shared bounded directory walkers

• #![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

• 741 lib tests plus integration + fault-injection suites
• ~98 % library line coverage measured with cargo-llvm-cov
• CI runs on the shared rust-ci.yml pipeline (stable toolchain)

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

Code of Conduct

Please read our Code of Conduct before participating in the project.

License

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

See CHANGELOG.md for release history.