Validation and Guarantees

Validation and Guarantees

SSI validates at build time. If something is wrong — a broken internal link, a missing include, a malformed configuration, an image without alt text — the build tells you before anything reaches your server. There is no runtime fallback, no partial output, and no flaky behavior that only appears in production.

Build-Time vs Runtime

Most web frameworks handle errors at runtime: a broken link returns a 404, a missing template variable renders as blank, a misconfigured asset loads from the wrong URL. These errors appear only when someone visits the affected page.

SSI’s approach is different. Every output file is verified during the build. If validation fails, the deploy does not complete. Your previous deployment stays in place, unchanged.

This means:

• A broken internal link causes a build failure, not a 404 for users
• An unresolved include token causes a build failure, not a blank section
• An inaccessible image still gets checked — via alt attribute presence, not HTTP

If an asset exists is a validation question, not a template-time branching question. You do not need conditional logic like “show this image if the file exists.” You validate that the image exists (using checksum verification or ssi validate), and then write the template unconditionally.

What ssi validate Checks

ssi validate runs the full validation pass without deploying. Use it before a deploy to catch issues early, or in CI to block merges that would break the site.

Configuration

• TOML syntax validity
• Required fields present
• Unique emoji identifiers across all steps
• Valid processing types and options

Source Structure

• Source directories exist and are readable
• Include source files have correct extensions for their type
• No filename collisions across processing steps
• Subdirectories in page sources noted (they are ignored during processing)

Content

• Include tokens resolved in output (unresolved tokens are warnings by default, errors under --strict)
• Checksum files match copy-processed assets (when checksum option is used)
• Preserve list paths are relative and contain no path traversal

HTML Structure and Accessibility

ssi validate checks every generated .html file for structure and accessibility issues:

All warnings become errors under --strict. See Errors and Warnings for the full list with explanations and fixes.

Internal Links

ssi validate checks that every href pointing to a local .html file resolves to a file that actually exists in the deploy output. Broken fragment links (#section) are not checked, but cross-page links are.

Strict Mode

--strict treats all warnings as errors (exit code 53). Use it in CI pipelines to ensure warnings are resolved before code is merged:

# Validate only
                ssi validate --strict my-site/
                
                # Validate and deploy (fails if any warnings exist)
                ssi deploy --strict my-site/ output/
                

Pedantic Mode

--pedantic enables additional checks that are off by default:

• Missing <h1> on pages that have other headings
• Inline style attributes
• Embedded <style> tags

ssi validate --pedantic my-site/
                

Validation Never Modifies Files

ssi validate is read-only. It processes your source files and examines the output in memory, but writes nothing. Running it is always safe, even on a live site directory.

Exit Codes

For a complete list of exit codes and their meanings, see Exit Codes.

CI/CD Integration

# Run before deploy — fails fast on any validation issue
                - name: Validate site
                  run: ssi validate --strict site/
                
                - name: Deploy
                  run: ssi deploy site/ output/
                

For the full message catalog, see Errors and Warnings.