ssi new

New Site Command

Create a new skeleton site with example content.

ssi new <project-name> [--minimal | --simple | --default | --blog]

Arguments

<project-name> — name for the new project directory (required)

Options

Option	Description
`--minimal`	Use the minimal template
`--simple`	Use the simple template
`--default`	Use the default template (same as no template flag)
`--blog`	Use the blog template
`--no-clobber`	Fail if the project directory already exists
`--atomic-symlink=<LINK>`	Create site with atomic deployment setup using the specified symlink name
`--suffix <type>`	Suffix type for atomic: `git`, `random`, `timestamp`, `blue-green` (default: `blue-green`)
`--suffix-length <value>`	Suffix length (for use with `--suffix`)

Templates

default — multi-page site demonstrating per-page content resolution; pages, per-page markdown, shared content, TOML variables with page-specific overrides (from examples/09-page-specific)
minimal — single page with plain text includes; just ssi-config.toml, pages/index.html, and texts/ (from examples/01-copy-only)
simple — page and include processing with markdown content and plain text includes (from examples/03-markdown-content)
blog — template-based blog with per-post markdown, post-metadata.toml, and blog index (from examples/18-basic-blog)

When no template flag is given, --default is used. At most one template flag may be given.

The site name is derived from the project directory name: my-site becomes “My Site”, my_project becomes “My Project”. Only ASCII letters, digits, hyphens (-), and underscores (_) in the directory name (the last path segment) are used. If the name contains any other character (for example, spaces, dots, or non-ASCII characters), the title Site Name TK is used in generated strings.toml and other templated files instead, and a warning is logged once per command (after any internal dry-run preflight, you still see a single message when a real pass runs).

Examples

# Create a default site (demonstrates per-page content)
                ssi new my-website
                cd my-website
                ssi deploy site/ output/
                
                # Preview what would be created without making changes
                ssi --dry-run new my-website
                
                # Create a minimal skeleton (flag before or after the name — both work)
                ssi new my-blog --minimal
                ssi new --minimal my-blog  # equivalent
                
                # Create a blog site
                ssi new my-blog --blog
                
                # Create with atomic deployment setup
                ssi new my-app --atomic-symlink=production
                # Creates: my-app/ (source), production.blue/ (deployed), production -> production.blue (symlink)
                # Future deploys: ssi atomic my-app production
                
                # Create with git-based suffix
                ssi new my-app --atomic-symlink=production --suffix=git

Atomic Symlink Setup

When using --atomic-symlink=<LINK>:

Creates the source site in the specified project directory
Deploys the site to <LINK>.blue (by default)
Creates a symlink <LINK> -> <LINK>.blue
Future deployments use ssi atomic <source> <LINK> for zero-downtime updates

For complete argument details: ssi new --help