ssi validate

Validate Command

Validate a site’s configuration and source files without deploying.

ssi validate [OPTIONS] <SITE_DIR>

Arguments

<SITE_DIR> — source directory containing ssi-config.toml and source files

Options

Option	Description
`--config <file>`	Use a specific configuration file instead of the default
`-f`, `--format <format>`	Output format: `human` (default) or `key-value` for automation
`--single-file <file>`	Validate only a single template file (path relative to `<SITE_DIR>`)
`--strict`	Treat warnings as fatal errors
`--pedantic`	Enable additional HTML checks (see below)
`--allow-external-paths`	Allow source paths outside the site directory

Global Options

The global options (--verbose, --quiet, --dry-run, --color) also apply — see ssi help global-options.

Exit Codes

0 — Validation passed, no issues found
50 — Config validation failed (invalid TOML, missing fields, path errors)
51 — (reserved)
52 — Content/deploy validation failed (processing errors, broken links, HTML errors)
53 — Warning escalated to error (only under --strict)

Examples

# Validate a site
                ssi validate site/
                
                # Treat warnings as errors
                ssi validate --strict site/
                
                # Machine-readable output for automation
                ssi validate --format key-value site/
                
                # Validate with a custom config file
                ssi validate --config custom-config.toml site/
                
                # Validate a single file
                ssi validate --single-file src/index.html site/

Always-on HTML Checks

The following HTML checks run unconditionally — no extra flag is needed:

Parse errors — the HTML could not be parsed; the output may be malformed
Heading level skipping — headings jump levels (e.g., <h1> directly to <h3>)
Multiple <h1> elements — more than one <h1> on a page
Div-soup — non-semantic block-level <div> nesting where HTML5 sectioning elements would be more appropriate
Duplicate IDs — more than one element shares the same id attribute value
Non-conforming elements — elements that are not valid HTML5
Missing lang on <html> — the <html> element lacks a lang attribute; required by WCAG Level A (SC 3.1.1) for screen reader compatibility
Missing alt on images — <img> elements without an alt attribute
Unlabeled inputs — <input> elements with no associated <label> or aria-label
Invalid ARIA role — role attribute value is not a recognized WAI-ARIA role
ARIA ref target missing — aria-labelledby or aria-describedby references an id that does not exist in the page
aria-hidden on interactive element — a focusable element (link, button, input) is hidden from the accessibility tree while still being keyboard-reachable

Pedantic Mode

--pedantic enables additional HTML checks that are silent by default:

Missing <h1> — pages with headings but no <h1> element (pages with zero headings are not flagged)
Inline style attributes — elements with style="..." attributes; use external stylesheets instead
Embedded <style> tags — use <link rel="stylesheet"> instead

Pedantic mode composes with --strict: --pedantic --strict enables the extra checks and escalates them to fatal errors.

# Enable pedantic checks
                ssi --pedantic validate site/
                
                # Pedantic + strict: extra checks are fatal errors
                ssi --pedantic --strict validate site/

CSS Structure Checks

The validate command also checks every source .css file for structural parse errors. These checks are always-on (no extra flag needed). CSS parse errors are warnings in normal mode and fatal under --strict. What is checked:

Brace balance — every { must be matched by a }
Stray } at the top level
Unterminated string literals (unescaped newline in a quoted string)
Malformed at-keywords (bare @ not followed by a valid identifier)

If a listed .css file cannot be read (for example, not valid UTF-8, permission denied, or other I/O errors), it is not included in the structure scan. In that case you get one summary warning with counts by failure class so that a clean result still means “no structural issues in the files that were read,” not “every .css file was checked.”

Single-File Mode

--single-file <file> scopes validation to one specific template. The full SSI pipeline still runs (include resolution, per-page tokens) — only the output and error reporting are narrowed.

<file> is the path to the template relative to <SITE_DIR>.

What runs in single-file mode:

Check	Runs?	Notes
Config validation	Yes	Needed for engine setup
Source structure	Yes	Needed for include resolution
Unicode security	Yes, filtered	Only for the target source file
Leftover token check	Yes, filtered	Only errors in the target file’s output
HTML structure	Yes, filtered	Only the target file’s processed output
Link validation	No	Cross-page links would always appear broken
CSS structure	No	Not related to the specific page
Include source checks	No	Site-wide concern
Unused key detection	No	Other pages may use those keys

# Validate one page — useful while editing it
                ssi validate --single-file pages/about.html site/
                
                # Same, with pedantic checks
                ssi --pedantic validate --single-file pages/about.html site/

Architecture Note

The validate command uses the same build pipeline as deploy and atomic, ensuring that the validated output exactly matches what a real build would produce. Validation is read-only: no temporary directories are created and no files are written.