Super-Simple Includes Documentation
v0.244.0

Features & Non-Features

What is Super-Simple Includes?

A straightforward static site generator that processes include tokens to build websites. Nothing more, nothing less.

Core Features

  • Simple Syntax: Use emoji tokens like 🏷️header and 📰content
  • Content Organization: Separate content from design completely
  • Fast Processing: Linear single-pass algorithm with no recursion
  • Flexible Pipelines: Configure exactly how your content flows
  • Multiple Sources: Mix TOML files, directories, and different content types
  • Fast Rust Binary: Standalone static binary with no runtime dependencies
  • Atomic Deploy: All-or-nothing deployments prevent broken intermediate states
  • Web Hosting Ready: Built for Linux, the OS the Internet is made from
  • Safe by Default: Path traversal protection and input validation

Content Sources

  • HTML Blocks: Reusable HTML fragments for headers, footers, navigation
  • Plain Text: Simple text files with automatic HTML escaping
  • Markdown: Full CommonMark support with automatic HTML conversion
  • TOML Variables: Key-value pairs for site-wide configuration
  • DateTime Sources: Current timestamps and formatted dates
  • Git Sources: Repository information like commit hashes and branch names
  • Page-Specific Content: Override defaults with page-specific versions

Processing Options

  • Copy Assets: Static files copied directly to output
  • Template Processing: HTML files processed for include tokens
  • Checksum Verification: xxHash3 integrity checking for copy operations
  • Inline vs Block: Choose whether included content flows inline or as blocks
  • Smart Indentation: Block includes preserve your HTML formatting
  • Validation: ssi validate checks your configuration and processed output before deployment — including HTML structure, heading hierarchy, accessibility (missing alt, unlabeled form inputs, missing lang), and internal links. Optional strict mode (--strict) treats warnings as errors.

User Experience

  • Clear Error Messages: Helpful feedback when things go wrong
  • Verbose Mode: See exactly what’s happening during processing
  • Simple CLI: Straightforward command-line interface
  • No Runtime Dependencies: Static musl binary runs anywhere

Non-Features

What Super-Simple Includes intentionally does NOT do:

By Design

  • No Complex Templating: No loops, conditionals, or functions
  • No Recursion: Linear single-pass processing prevents infinite loops
  • No Dynamic Content: All content is processed at build time
  • No Watch Mode: Rebuild manually when files change (use inotifywait for automation)
  • No Dev Server: Use any static file server you like
  • No Plugin System: Core functionality only (use preserve feature to mix externally-generated files with SSI, even with atomic deploy)
  • No Themes: Build your own design
  • No Image Optimization: Too complex, better handled by dedicated tools
  • No Internationalization (i18n): SSI does not have built-in locale switching, translation keys, or multi-language routing. The workaround is to run a separate build per locale — one ssi-config.toml per language, each deploying to its own output directory (e.g., output/en/, output/fr/). Templates and content can be shared across builds; only the locale-specific content directories differ.

Not Yet Implemented

  • Auto-Template Generation: Automatically create pages based on content directory structure
  • Remote Content Fetching: HTTP/HTTPS includes for external content

Possible Future Features

  • Incremental Builds: Per-file-source optimization (not timestamp-based, preserves atomic deploy)
  • JavaScript Processing: Basic minification and bundling (no external tools)
  • CSS Processing: Basic minification and bundling
  • Emoji Shortcodes: Accessibility-friendly :paperclip:header syntax alongside emoji tokens
  • SQLite Include Sources: Database-backed content with SQL query capabilities
  • Build-Mode Conditional Rendering: Include sources that render based on build mode (dev/prod/preview)

Platform Limitations

  • Linux Only: Not tested on Windows or macOS
  • UTF-8 Only: All text files must be UTF-8 encoded

Philosophy

These aren’t missing features — they’re conscious choices. By keeping the scope limited, Super-Simple Includes remains:

  • Easy to understand
  • Simple to debug
  • Fast to run
  • Predictable in behavior

If you need these features, there are many excellent static site generators that provide them. SSI focuses on doing one thing well: combining content fragments into complete HTML pages with minimal complexity.