Super-Simple Includes Documentation
v0.244.0

Design Notes

Architecture Overview

Super-Simple Includes is built around a clear, predictable pipeline architecture. Understanding these design decisions helps you use the tool effectively and understand its limitations.

Core Design Principles

One-Pass Processing

The system makes exactly one pass through the File Sources Pipeline. For each template, it processes all Include Sources in order. This design:

  • Prevents infinite loops
  • Makes processing predictable
  • Simplifies debugging
  • Ensures consistent performance

No Recursion

Processing is strictly linear and forward-only. Each include source scans the accumulated template output from all previous sources — content inserted by an earlier source can contain tokens that a later source resolves — but no source ever re-scans its own output or any already-processed source. This design:

  • Eliminates circular reference possibilities
  • Keeps the system simple and predictable
  • Makes output deterministic
  • Prevents performance surprises

Pipeline Architecture

Two-Stage Pipeline

  1. File Sources Pipeline (Outer)

    • Processes directories of files
    • Either copies assets or processes templates
    • Runs once, in configuration order

  2. Include Sources Pipeline (Inner)

    • Processes include tokens within templates
    • Runs for each template file
    • Applies all include sources in order

Processing Flow

File Source 1 (copy) → Copy all files
                File Source 2 (page) → For each template:
                                       → Apply Include Source 1
                                       → Apply Include Source 2
                                       → ... etc ...
                                       → Validation pass
                                       → Write output
                File Source 3 (copy) → Copy all files

Key Concepts

source directory vs Deploy Directory

  • source directory: Where your source files live
  • Deploy Directory: Where built files go
  • All relative paths start from source directory

Include Tokens

An include token consists of:

  • An emoji defined in configuration
  • Followed by alphanumeric characters (plus - and _)
  • Case-sensitive
  • Terminated by any other character

Example: 📎header or 💬site_name

File Sources vs Include Sources

File Sources define what gets processed:

  • Directories only (not individual files)
  • Two processing types: copy or page
  • Templates must be top-level (no subdirectories)

Include Sources define includable content:

  • Can be directories or TOML files
  • Three content types: plain, markdown, html
  • Support page-specific overrides

Design Decisions

Why Emoji?

Emoji in include tokens serve multiple purposes:

  • Visually distinct from regular content
  • Fun and memorable
  • Impossible to confuse with HTML
  • Clear token boundaries

Why No Subdirectories for Templates?

Templates with processing="page" must be top-level because:

  • Simplifies page name matching
  • Avoids path complexity
  • Makes overrides predictable
  • Reduces configuration errors

Why One Pass Only?

Single-pass processing ensures:

  • No infinite loops possible
  • Predictable processing time
  • Clear error messages
  • Simple mental model

The Matchmaker Pattern

The Include Pipeline uses a “Matchmaker” pattern with three responsibilities:

  1. Content Location - Data Sources find content by key
  2. Content Type Mapping - Include Sources know the type
  3. Content Processing - Content Handlers render to HTML

This separation allows:

  • New data sources without changing handlers
  • New content types without changing sources
  • Clean, modular code
  • Future extensibility

Implementation Rules

File Sources

  • Process in configuration order
  • No parallel processing (deterministic output)
  • Warn on filename conflicts
  • Strict mode elevates warnings to errors

Include Sources

  • Process in configuration order
  • Support both inline and block modes
  • Handle indentation for block includes
  • Validate leftover tokens

Content Types

  • Plain: HTML-escape for safety
  • Markdown: Full CommonMark support
  • HTML: No processing or escaping

Future Considerations

Possible Extensions

While keeping the core simple, future versions might add:

  • Plugin architecture for new sources
  • Additional processing types
  • Database or API sources
  • Compression or optimization

Non-Goals

Things we intentionally don’t support:

  • Recursive includes
  • Dynamic content generation
  • Complex templating logic
  • Build-time computation

Why These Choices?

Every design decision prioritizes:

  1. Simplicity - Easy to understand and debug
  2. Safety - Impossible to create infinite loops
  3. Predictability - Same input produces same output
  4. Performance - Linear time complexity

The result is a tool that does one thing well: combining content fragments into complete HTML pages with minimal complexity.

Architecture

Architecture documentation is being updated.