Super-Simple Includes Documentation
v0.244.0

Data Sources

Data Source Types

In addition to directory and TOML file sources, Super-Simple Includes supports specialized data sources that provide dynamic content:

Counter Data Source

Provides stateful per-page auto-incrementing integers. The main use is token concatenation — 📊image🔂num becomes 📊image1, 📊image2, etc. — enabling a single block template to render multiple items with distinct data. Counter state resets at each page boundary.

[[step]]
                emoji = "🔂"
                processing = "include"
                type = "counter"

No path field is needed.

Available Tokens

  • 🔂name — Increment counter name and return the new value (1, 2, 3, …)
  • 🔂_name — Peek at current value of counter name without incrementing

The _ prefix is a special peek syntax; it is not a leading underscore in the counter’s key name. So 🔂_count peeks at the counter named count.

For complete documentation, step-ordering requirements, and worked examples, see ssi help counter-source.

DateTime Data Source

Provides current date and time components as tokens.

[[step]]
                emoji = "🕐"
                processing = "include"
                type = "datetime"
                timezone = "UTC"  # Optional: IANA timezone (e.g., "UTC", "America/New_York")
                options = ["inline"]

Available Tokens

  • Date components: year, month, day, month_name, month_short, day_of_week, day_short, week_number
  • Time components: hour, hour12, minute, second, am_pm
  • Timezone components:
    • tz: Timezone abbreviation (e.g., “EST”, “PST”, “UTC”)
    • timezone: Timezone name (same as tz for simplicity)
    • utc_offset: UTC offset in ±HH:MM format (e.g., “-05:00”, “+02:00”)
    • utc_offset_hours: UTC offset in hours only (e.g., “-5”, “+2”)
  • Formatted strings: iso, date, time, rfc3339, build_timestamp

Timezone Configuration

The timezone field is optional and accepts IANA timezone strings:

  • If specified: Uses the specified timezone for all datetime tokens (e.g., timezone = "America/New_York")
  • If omitted: Falls back to the TZ environment variable
  • If neither: Uses system local timezone

Examples:

# Using UTC (recommended for consistent builds)
                [[step]]
                emoji = "🕒"
                type = "datetime"
                timezone = "UTC"
                options = ["inline"]
                
                # Using Eastern Time
                [[step]]
                emoji = "🕒"
                type = "datetime"
                timezone = "America/New_York"
                options = ["inline"]
                
                # Using environment variable (no timezone field)
                [[step]]
                emoji = "🕒"
                type = "datetime"
                options = ["inline"]
                # Uses TZ environment variable: TZ=Europe/London ssi deploy site/ output/

Note: Path field is optional for datetime sources (datetime doesn’t use filesystem).

Git Data Source

Provides git repository information by reading directly from the .git directory structure without requiring external git commands.

[[step]]
                emoji = "🔧"
                path = "../.git/"  # Explicit path to .git directory
                processing = "include"
                type = "git"
                options = ["inline", "allow-external-paths"]  # allow-external-paths: .git is outside site directory

Available Tokens

  • branch - Current branch name
  • commit - Latest commit hash (full)
  • commit-short - Latest commit hash (first 10 characters)
  • remote-origin - Origin remote URL (if it exists)
  • remote-[name] - Works for any remote name you have configured in git (like remote-upstream, remote-deploy, etc.)
  • description - Repository description

Path Requirements

  • Source path must explicitly end with .git/
  • Follows normal SSI safe path validation rules
  • No automatic searching - explicit configuration required
  • Use options = ["allow-external-paths"] if .git is outside site directory

Example Usage

Configuration:

[[step]]
                emoji = "🏷️"
                path = ".git/"
                processing = "include"
                type = "git"
                options = ["inline"]

Template file (markdown):

## About This Build
                
                Built from branch: 🏷️branch
                Commit: 🏷️commit-short
                Repository: 🏷️remote-origin

Final output:

<h2>About This Build</h2>
                <p>Built from branch: main<br>
                Commit: abc1234567<br>
                Repository: https://github.com/example/repo.git</p>

Security and Limitations

  • Works without git installed (reads files directly)
  • Only supports standard git repository layouts
  • Does not support bare repositories, worktrees, or submodules
  • Gracefully handles missing files (returns empty strings)

Environment Data Source

Exposes selected environment variables as tokens. For security, only variables explicitly listed in a text file are accessible.

[[step]]
                emoji = "🌍"
                path = "allowed-env-vars.txt"  # Text file listing allowed variable names
                processing = "include"
                type = "environment"
                options = ["inline"]

The source file should contain one environment variable name per line:

# Build variables
                BUILD_NUMBER
                BUILD_ID
                CI_COMMIT_SHA
                
                # Application info
                APP_VERSION
                APP_NAME
  • Variables not listed in the file cannot be accessed
  • Missing/undefined variables return empty strings
  • Comments (lines starting with #) and blank lines are ignored
  • Variable names are case-sensitive

Security Note

The environment data source is designed with security in mind:

  • Only explicitly listed variables can be accessed (allowlist approach)
  • No wildcards or patterns are supported
  • Variables containing sensitive information (API keys, passwords) should never be listed
  • The allowlist file should be carefully reviewed and kept in version control
  • Consider using a dedicated prefix for SSI-specific variables (e.g., SSI_VERSION)

Token Resolution

Include tokens consist of the emoji followed by alphanumeric characters, underscores, or hyphens. The first and last characters must be alphanumeric:

  • Valid: 📎header, 📜content_main, 💬site-title, 📎header-html, 📜content-main
  • Invalid: 📎-header (starts with hyphen), 📜content_ (ends with underscore), 📎key- (ends with hyphen)

Token Key Naming Rules

Token keys must follow these rules:

  • Start with an ASCII alphanumeric character (a–z, A–Z, 0–9)
  • End with an ASCII alphanumeric character
  • Middle characters may include _ (underscore) or - (hyphen), provided they are surrounded on both sides by alphanumeric characters or other valid separators
  • Trailing _ or - is never part of the key — the token ends at the last alphanumeric character

These rules apply to filenames in include source directories, keys in TOML files, and token keys constructed from counter concatenation.

Content is resolved by:

  1. Looking in page-specific subdirectory (e.g., blocks/about/ for about.html)
  2. Falling back to top-level directory (e.g., blocks/)
  3. For TOML sources, checking page-specific table [about] then default table [_]