Quick Start

Super-Simple Includes (SSI) — Quick Reference

SSI is a static site builder that assembles pages from reusable include fragments using emoji-based tokens.

ssi new my-site           # create a skeleton site
                ssi deploy site/ out/     # process and deploy
                ssi atomic site/ link     # atomic deployment (zero-downtime)
                ssi validate site/        # validate configuration and output
                ssi version               # show version

Use ssi help <topic> for detailed help on any topic. Use ssi <command> --help for full argument details.

--color=reverse improves readability in light terminals.

Getting Started

Installation

Build the binary from source:

git clone https://codeberg.org/mattdm/super-simple-includes.git
                cd super-simple-includes
                cargo build --release --target x86_64-unknown-linux-musl
                cp target/x86_64-unknown-linux-musl/release/ssi ~/.local/bin/

Requires a recent stable Rust toolchain.

Your First Site

The quickest way to start:

ssi new my-site
                cd my-site
                ssi deploy site/ output/

This creates a working demo site with example content, then builds it. Open output/index.html to see the result.

Building a Site from Scratch

1. Create the directory structure:

my-site/
                ├── ssi-config.toml
                ├── pages/
                │   └── index.html
                ├── markdown-texts/
                │   └── welcome.md
                ├── plain-texts/
                │   └── tagline.txt
                └── assets/
                    └── style.css

2. Write the config (ssi-config.toml):

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

3. Write the template (pages/index.html):

<!DOCTYPE html>
                <html lang="en">
                <head>
                  <title>📜tagline</title>
                  <link rel="stylesheet" href="style.css">
                </head>
                <body>
                  <h1>📜tagline</h1>
                  <p>📜tagline</p>
                  📝welcome
                </body>
                </html>

4. Add content:

plain-texts/tagline.txt:

A site built with Super-Simple Includes

markdown-texts/welcome.md:

## Welcome
                
                Content here is in a Markdown file. The page structure is in the HTML template.

5. Build:

ssi deploy my-site/ output/

Next Steps

ssi help config          # config file reference
                ssi help deploy          # deploy command options
                ssi help new             # creating sites from templates

For worked examples: ssi help examples