Super-Simple Includes

A fast, flexible static site generator for content inclusion and variable substitution.

Note

: This README was AI-generated and needs human review for accuracy and completeness.

Installation

From Source

cargo build --release --target x86_64-unknown-linux-musl

The binary will be at target/x86_64-unknown-linux-musl/release/ssi.

Quick Demo

# Deploy a simple site
ssi deploy examples/02-simple-page/site my-deploy
# Create a new project
ssi new my-project
# Validate configuration
ssi validate config my-site

Examples

The examples/ directory contains a progressive learning path from basics to production. See examples/README.md for the complete guide.

Quick reference:

• 01-copy-only - Absolute minimum configuration
• 02-simple-page - First template processing
• 03-markdown-content - Markdown conversion
• 04-page-with-assets - Multiple processing steps
• 05-type-auto - Auto-detect content types
• 06-html-blocks - Reusable HTML components
• 07-toml-data - Structured data
• 08-inline-content - Inline vs block includes
• 09-page-specific - Per-page content resolution
• 11-builtin-sources - System integration (datetime, git, env)
• 12-css-js-templates - Process CSS/JS as templates
• 13-preserve - Incremental builds
• 20-full-site - Complete production example

Documentation

See the docs/ directory for detailed documentation:

• Configuration Guide
• Include Syntax
• CLI Reference
• Architecture

Performance & Architecture

No Regex Ever 🚫

Super-Simple Includes is 100% regex-free by design. We use simple string operations instead of regular expressions for several important reasons:

Why No Regex?

1. 🚀 Performance: No regex compilation overhead - simple string operations are faster
2. 🔒 Security: Eliminates regex injection vulnerabilities and ReDoS attacks
3. 🧹 Simplicity: Clear, readable code that's easy to understand and maintain
4. 🌍 Unicode: Proper Unicode segmentation handles complex emojis correctly

What We Use Instead

• String Operations: find(), starts_with(), ends_with(), character iteration
• Unicode Segmentation: Proper grapheme cluster handling for emojis like 👨‍👩‍👧‍👦
• Character Validation: Simple character-by-character checks for patterns
• Fast Search: Daachorse multi-pattern matching for token finding

Benefits for Users

• Faster Builds: No regex compilation means faster site generation
• Better Security: No risk of regex-based denial-of-service attacks
• Reliable Unicode: Complex emojis and international text work correctly
• Predictable Performance: String operations have consistent, linear performance

💡 For Developers: See our standards check at tests/standards/no-regex-ever.sh that enforces this policy across the entire codebase.

Unified Key-Based Discovery

SSI uses a single unified pattern for discovering both templates and includes. Instead of separate code paths, everything works through the same key-based abstraction:

The Pattern

• One Discovery Method: list_keys() finds available content by abstract keys
• One Resolution Method: resolve_key() maps keys to files with extensions
• Works Everywhere: Templates, includes, and any content source

Why It Matters

1. 🎯 Simplicity: One pattern instead of multiple special cases
2. ⚡ Performance: Single filesystem scan, O(1) lookups
3. 🔧 Type Auto-Detection: Extensions returned with paths enable type = "auto"
4. 🔄 Consistency: Templates and includes work identically

Key Abstraction: Filename stems for directories ("header" from "header.html"), literal keys for TOML sources.

For technical details, see ARCHITECTURE-draft.md.

Security

SSI implements comprehensive security protections:

Unicode Security

• Bidirectional Text Injection Protection: Blocks all 9 dangerous bidi control characters
• Zero-Width Attack Prevention: Rejects invisible characters used for content hiding
• Control Character Validation: Blocks C0/C1 ranges that can cause injection attacks

Multi-Layer Defense: Validation at config parsing, file reading, and output writing ensures attacks are caught even through complex token substitution.

International Text Support: Full support for Arabic, Hebrew, emoji, and all legitimate Unicode without needing control characters.

See docs/SECURITY.md for details.

Path Security

• Write Protection: Prevents writes to system directories (/etc, /bin, etc.)
• Source Path Validation: Blocks absolute paths and parent directory references in config
• Symlink Security: Validates symlinks stay within site directory

Testing

# Run all tests
python scripts/run-all-tests.py
# Run specific category
python scripts/run-all-tests.py functional

Test Documentation

• Test README - Test organization and structure
• Testing Guide: Load ssi-testing skill for complete testing documentation

Test Quality

All tests are verified by automated meta-testing to ensure:

• No test bypasses or skips
• Proper test categorization
• CLI interface compliance (except unit tests)
• Test execution in all output modes

For AI Agents

This project uses OpenSkills for modular agent instructions:

• Core rules: AGENTS.md - Branch workflow, testing, communication standards
• Specialized workflows: Read .agents/skills/<skill-name>/SKILL.md
• Project skills: .agents/skills/ssi-*/ (SSI-specific knowledge)
• Global skills: ~/.agents/skills/ (skill-creator, xlsx, pdf)

Install OpenSkills: npm install -g openskills

Available skills: Run openskills list to see all available skills.

See CONTRIBUTING.md for complete AI agent setup.

License

See LICENSE.md for details.