Getting Started Guide

Getting Started: Examples 1–4

This walkthrough covers SSI’s core concepts using the first four examples. By the end, you’ll understand how to build a complete static site with SSI.

Example 1: The Minimum Configuration

Start with the simplest possible SSI configuration:

# ssi-config.toml
                [[step]]
                emoji = "📁"
                path = "files/"
                

Three lines. This configuration:

• Uses the default processing = "copy" behavior
• Copies all files from files/ to your deploy directory
• Does no template processing

Try it:

cd examples/01-copy-only
                ssi deploy site/ output/
                

What you learned:

• SSI configurations use [[step]] tables
• emoji and path are the only required fields
• Default behavior is simple file copying

Example 2: First Template Processing

Now let’s add template processing:

[[step]]
                emoji = "📄"
                path = "pages/"
                processing = "page"
                
                [[step]]
                emoji = "📜"
                path = "texts/"
                processing = "include"
                type = "plain"
                

This configuration:

• Processes HTML files from pages/ as templates
• Makes text files available as includes
• Replaces 📜filename tokens with content from texts/filename.txt

Template usage:

<header>📜header-text</header>
                <main>📜article-one</main>
                <footer>📜footer-text</footer>
                

Try it:

cd examples/02-simple-page
                ssi deploy site/ output/
                cat output/index.html  # See the replaced content
                

What you learned:

• processing = "page" enables template processing
• processing = "include" makes content available to templates
• Tokens are emoji + filename (without extension)

Example 3: Markdown Content

Let’s add rich content with Markdown:

[[step]]
                emoji = "📄"
                path = "pages/"
                processing = "page"
                
                [[step]]
                emoji = "📝"
                path = "markdown-texts/"
                processing = "include"
                type = "markdown"
                
                [[step]]
                emoji = "📜"
                path = "plain-texts/"
                processing = "include"
                type = "plain"
                
                [[step]]
                emoji = "🎨"
                path = "assets/"
                processing = "copy"
                

Markdown files are automatically converted to HTML during processing.

Template usage:

<section>
                    📝welcome  <!-- Converted from welcome.md -->
                </section>
                <section>
                    📝features  <!-- Converted from features.md -->
                </section>
                

Try it:

cd examples/03-markdown-content
                ssi deploy site/ output/
                

What you learned:

• type = "markdown" converts .md files to HTML
• You can have multiple include sources with different types
• Use processing = "copy" for static assets (CSS, fonts)

Example 4: Asset Checksum Verification

Add integrity checking to your static assets:

[[step]]
                emoji = "📄"
                path = "pages/"
                processing = "page"
                
                [[step]]
                emoji = "🎨"
                path = "assets/"
                processing = "copy"
                options = ["checksum"]
                
                [[step]]
                emoji = "🔒"
                path = "assets.xxh3"
                processing = "preserve"
                

The options = ["checksum"] step verifies each file against pre-computed xxHash3 checksums stored in assets.xxh3. If a file changes or a copy fails, SSI reports the mismatch.

Try it:

cd examples/04-assets-with-checksums
                ssi deploy site/ output/
                

What you learned:

• options = ["checksum"] verifies assets after copying
• Checksum files use the path + .xxh3 naming convention
• processing = "preserve" carries files forward from the previous deployment

Quick Reference

Processing Modes

• "copy" — Copy files as-is (default)
• "page" — Process as templates
• "include" — Make available to templates

Content Types

• "auto" — Detect by extension (default)
• "html" — HTML includes (no escaping)
• "markdown" — Markdown → HTML
• "plain" — Plain text (HTML-escaped)

Token Format

{emoji}{name} where:

• emoji = The emoji from the step config
• name = Filename without extension

Examples: 📜header-text, 📝welcome, 📎alert-box