ssg 0.0.47

Contents

• Install -- Cargo, Homebrew, apt, AUR, one-liner
• Quick Start -- scaffold a site in 30 seconds
• Overview -- what SSG does
• Architecture -- build pipeline diagram
• Benchmarks -- performance and test suite metrics
• Features -- v0.0.47 capability matrix
• The CLI -- flags and usage
• Library Usage -- plugins, schemas, AI pipeline
• Examples -- 8 branded examples
• Development -- make targets, CI workflows
• Security -- safety guarantees and compliance
• License

Install

[dependencies]
ssg = "0.0.47"

Prebuilt binaries

# macOS / Linux -- one command
curl -fsSL https://raw.githubusercontent.com/sebastienrousseau/static-site-generator/main/scripts/install.sh | sh

# Homebrew
brew install --formula https://raw.githubusercontent.com/sebastienrousseau/static-site-generator/main/packaging/homebrew/ssg.rb

# Cargo
cargo install ssg

# Debian / Ubuntu
sudo dpkg -i ssg_0.0.47_amd64.deb

# Arch Linux (AUR)
yay -S ssg

# Container
docker pull ghcr.io/sebastienrousseau/static-site-generator:latest

Build from source

git clone https://github.com/sebastienrousseau/static-site-generator.git
cd static-site-generator
make          # check + clippy + test

Requires Rust 1.88.0+. Tested on Linux, macOS, and Windows.

Quick Start

# 1 -- Install
cargo install ssg

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

# 3 -- Build
ssg -c content -o public -t templates

# 4 -- Development server with live reload
ssg -c content -o public -t templates -s public -w

# 5 -- AI-powered readability fix (requires Ollama)
ssg -c content -o public -t templates --ai-fix

Overview

SSG generates static websites from Markdown content, YAML frontmatter, and MiniJinja templates. It compiles everything into production-ready HTML with built-in SEO metadata, WCAG 2.2 AA accessibility compliance (including the new 2.5.8, 2.4.13, 3.2.6 criteria where automatable), multilingual readability scoring, and feed generation. The 33-plugin pipeline handles the rest.

• 33-plugin pipeline -- SEO, a11y, i18n, search, images, AI, CSP, JSON-LD, RSS, sitemaps
• Agentic AI pipeline -- audit, diagnose, fix, and verify content readability via local LLM
• Multilingual readability -- Flesch-Kincaid (EN), Kandel-Moles (FR), Wiener Sachtextformel (DE), Gulpease (IT), LIX (SV), Fernandez Huerta (ES)
• Incremental builds -- content fingerprinting via FNV-1a hashing and dependency graph
• Bounded-memory batch compilation -- configurable memory budgets for 100K+ page sites
• WCAG 2.2 AA -- accessibility checked on every build (non-blocking by default; reports written to accessibility-report.json + wcag-compliance.json) and gated in CI by axe-core. Build-failure on a11y violations is opt-in via the STRICT_A11Y env var (implemented in v0.0.40)
• Zero unsafe code -- #![forbid(unsafe_code)] across the entire codebase

Architecture

graph TD
    A[Content: Markdown + YAML] --> B{SSG CLI}
    B --> V[Content Schema Validation]
    V --> C[Incremental Cache + `DepGraph`]
    C --> D[Compile: staticdatagen]
    D --> E[Post-Processing Fixes]
    E --> F[Fused Transform Pipeline: 33 plugins]
    F --> G[Output: HTML + RSS + Atom + Sitemap + JSON-LD]
    B --> H[File Watcher + CSS HMR]
    H -->|changed files| C
    B -->|--serve| S[Dev Server + Live Reload + Error Overlay]
    B -->|--ai-fix| AI[Agentic LLM Pipeline]
    AI -->|audit + fix| A

Benchmarks

Build performance

Reproduce: cargo bench --bench bench -- scalability.

Features

Why SSG?

The CLI

ssg ships with both a unified subcommand surface (introduced in v0.0.43) and the legacy bare-flag pipeline (preserved with a deprecation warning, removal in 1.0).

Subcommands (recommended)

Usage: ssg <COMMAND> [OPTIONS]

Commands:
  dev        Start the development server with HMR + WebSocket reload
  build      One-shot site build (supports --incremental, --isr, --no-llm-cache)
  check      Validate content schemas without writing
  audit      Run 14 audit gates against an already-built site (--out json|junit|text)
  deploy     Generate deployment config for netlify | vercel | cloudflare | github
  help       Print this message or the help of the given subcommand(s)

Build flags (v0.0.45)

      --incremental        Skip recompile when DepGraph diff is empty (issue #524)
      --isr                Emit an SHA-256-keyed ISR manifest for Edge adapters (issue #549)
      --no-llm-cache       Bypass the deterministic LLM inference cache (issue #528)

Legacy flags (still supported)

  -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>        Start development server (HMR + livereload)
  -w, --watch              Watch for changes and rebuild
  -j, --jobs <N>           Rayon thread count (default: num_cpus)
      --max-memory <MB>    Peak memory budget for streaming (default: 512)
      --ai-fix             Run agentic AI pipeline to fix content readability
      --ai-fix-dry-run     Preview AI fixes without writing changes
      --validate           Validate content schemas and exit
      --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

Library Usage

fn main() -> Result<(), ssg::error::SsgError> {
    ssg::run()
}

use ssg::plugin::{Plugin, PluginContext, PluginManager};
use ssg::error::SsgError;
use std::path::Path;

#[derive(Debug)]
struct LogPlugin;

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

fn main() -> Result<(), SsgError> {
    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(())
}

Create content/content.schema.toml:

[[schemas]]
name = "post"

[[schemas.fields]]
name = "title"
type = "string"
required = true

[[schemas.fields]]
name = "date"
type = "date"
required = true

[[schemas.fields]]
name = "draft"
type = "bool"
default = "false"

Pages with schema = "post" in their frontmatter are validated at compile time. Run ssg --validate for schema-only checks.

use ssg::llm::{LlmPlugin, LlmConfig};
use std::path::Path;

let report = LlmPlugin::audit_all(Path::new("content"), 8.0).unwrap();
println!("{}/{} files pass grade 8.0", report.passing, report.total_files);

// Multilingual: French content uses Kandel-Moles automatically
// when frontmatter contains `language: fr`

use ssg::og_image::generate_og_svg;

let svg = generate_og_svg("My Page Title", "My Site", "#1a1a2e", "#ffffff");
std::fs::write("og-card.svg", svg).unwrap();
// 1200x630 SVG social card ready for og:image

use ssg_search::artifacts::{Artifacts, InputDoc};
use ssg_search::VectorEngine;

// Build side: turn a doc corpus into the 4-file artifact blob.
let docs = vec![
    InputDoc {
        url: "/post-1".into(),
        title: "Rust WebAssembly".into(),
        body: "rust compiles to wasm".into(),
        excerpt: "rust wasm".into(),
    },
    InputDoc {
        url: "/post-2".into(),
        title: "Sourdough".into(),
        body: "starter flour water salt".into(),
        excerpt: "bread".into(),
    },
];
let arts = Artifacts::from_docs(&docs);
std::fs::write("site/search/embeddings.bin", &arts.embeddings).unwrap();
std::fs::write("site/search/model.bin", &arts.model).unwrap();
std::fs::write("site/search/tokenizer.bin", &arts.tokenizer).unwrap();

// Runtime (native or WASM): load and query.
let engine = VectorEngine::new(
    &arts.model, &arts.tokenizer, &arts.embeddings, arts.count(),
).unwrap();
let top = engine.search("rust webassembly", 3);
println!("{:?}", top);

use ssg_rpc::ssg_rpc;
use schemars::JsonSchema;
use serde::{Deserialize, Serialize};

#[derive(Deserialize, JsonSchema)]
struct EchoIn { msg: String }

#[derive(Serialize, JsonSchema)]
struct EchoOut { msg: String }

#[ssg_rpc]
fn echo(input: EchoIn) -> Result<EchoOut, ssg_rpc::DispatchError> {
    Ok(EchoOut { msg: input.msg })
}

// The build emits `site/rpc.d.ts` automatically; clients call:
//   const r = await ssgRpc("echo", { msg: "hi" });

ssg audit site/ --out junit > audit.xml
# 15 gates run: WCAG 2.2 AAA, JSON-LD, hreflang, lang consistency, CSP+SRI, PQC TLS,
# HTML5, broken links, OG, markdown lint, perf budget, AI discovery,
# RSS/Atom, image opt, search index integrity.

Examples

Run any example:

cargo run --example basic
cargo run --example blog

Edge-runtime adapters (v0.0.45)

examples/edge-cloudflare/ and examples/edge-vercel/ are runnable reference implementations of the ISR + RPC pipeline for the two target edge runtimes. Each contains a wrangler.toml / vercel.json, the TypeScript glue (worker.ts, api/[...path].ts), an upload script for content provisioning (KV / Edge Config), and a smoke-test harness.

# Cloudflare Workers
cd examples/edge-cloudflare
npm install
npm run upload:kv          # uploads site/ to KV namespace
npx wrangler deploy

# Vercel Edge
cd examples/edge-vercel
npm install
npm run upload:edge-config # uploads site/ to Edge Config
vercel deploy

Development

make              # check + clippy + test
make test         # run all tests
make bench        # run Criterion benchmarks
make lint         # lint with Clippy
make format       # format with rustfmt
make deny         # supply-chain audit
make doc          # build API documentation
make a11y         # run pa11y accessibility audit
make clean        # remove build artifacts

CI

See CONTRIBUTING.md for signed commits and PR guidelines.

Security

• #![forbid(unsafe_code)] across the entire codebase
• CSP build-time extraction: all inline styles and scripts moved to external files with SRI hashes. Zero unsafe-inline
• Path traversal prevention with .. detection and symlink rejection
• File size limits and directory depth bounds
• cargo audit with zero advisories
• cargo deny -- license, advisory, ban, and source checks
• cargo vet -- per-crate audit attestation; imports Mozilla Firefox, Bytecode Alliance, and Google trust sets. See supply-chain/README.md
• CycloneDX SBOM generated as release artifact with Sigstore attestation
• SPDX license headers on all source files
• Signed commits enforced via SSH ED25519

See docs/whitepaper/csp-without-compromise.md for the full CSP security architecture.

Workspace crates

License

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

See CHANGELOG.md for release history.