Struct SsgConfig 

pub struct SsgConfig {

    pub site_name: String,
    pub content_dir: PathBuf,
    pub output_dir: PathBuf,
    pub template_dir: PathBuf,
    pub theme: Option<String>,
    pub serve_dir: Option<PathBuf>,
    pub base_url: String,
    pub site_title: String,
    pub site_description: String,
    pub language: String,
    pub i18n: Option<I18nConfig>,
    pub listings: Vec<ListingConfig>,
    pub cdn_prefix: Option<String>,
    pub og_image: Option<String>,
    pub image: ImageConfig,
    pub edge_headers: EdgeHeadersConfig,
    pub agents: Option<AgentsConfig>,
    pub transitions: bool,
    pub no_taxonomy_pages: bool,
    pub security: SecurityConfig,
}

Core configuration for the static site generator.

Fields

site_name: String

Name of the site.

content_dir: PathBuf

Directory containing content files.

output_dir: PathBuf

Directory for generated output files.

template_dir: PathBuf

Directory containing template files.

Defaults to templates, so a config that names a theme instead does not have to repeat a path it is about to have resolved for it. apply_theme treats this default as “unset”.

theme: Option<String>

Name of a theme to take templates and assets from.

A theme is a directory holding a layout set — _layouts/ for the published SSG themes, templates/ for a project-shaped one. Setting this resolves template_dir for you, so a project using a theme does not have to hand-write a path into someone else’s tree. An explicit template_dir still wins: naming both is how you override one layout without forking the theme.

Resolution is by crate::theme::resolve, which searches the config file’s own directory first and reports every path it tried when a name does not resolve.

serve_dir: Option<PathBuf>

Optional directory for development server files.

base_url: String

Base URL of the site.

site_title: String

Title of the site.

site_description: String

Description of the site.

language: String

Language code for the site.

i18n: Option<I18nConfig>

Optional i18n configuration for multi-locale sites.

Present only with the i18n feature (on by default): the type comes from the ssg-i18n crate, which that feature pulls in.

listings: Vec<ListingConfig>

Named, filtered, paginated listings (#587).

Absent means none, which is the behaviour every site had before: /page/N/ over every dated page and nothing else.

cdn_prefix: Option<String>

Optional CDN prefix for markdown images.

og_image: Option<String>

Optional site-wide fallback og:image (a URL or site-relative path). Used by generated pages that have no per-page image of their own — currently the taxonomy/tag pages emitted by crate::taxonomy::TaxonomyPlugin, which bypass the SeoPlugin transform chain (#586) and so never see the front-matter-derived og:image that regular content pages get. Absent ⇒ no og:image tag on those pages.

image: ImageConfig

Optional image-pipeline tunables (issue #521).

edge_headers: EdgeHeadersConfig

Edge-runtime header emitter config (issue #550). Absent / empty targets disables the emitter.

agents: Option<AgentsConfig>

Agentic-discovery emitters: agents.txt, ai-plugin.json, and the MCP registry (issue #552). All three are opt-in per the [agents] section of ssg.toml. Absent ⇒ no files written.

transitions: bool

Opt-in View Transitions + lazy-nav client (issue #547).

When true, the build emits _transitions/ssg-transitions.js and injects a small <script> + <style> block into every page so same-origin navigations animate via the View Transitions API (Chromium/Safari) or fall back to a plain reload in non-supporting browsers (Firefox stable as of 2026-06). Persistent <header> / <footer> roots get view-transition-name so they don’t animate across boundaries. Defaults to false to keep zero-JS sites zero-JS.

no_taxonomy_pages: bool

Skip generating taxonomy (tag / category / topic) pages.

Defaults to false, so a build that does not ask for this is unchanged. Sites that curate their own taxonomy — a canonical vocabulary, a minimum-article threshold, hand-translated slugs — need to own /tags/ outright: emitting a page per raw front-matter term contradicts that curation, and on a multi-locale corpus it multiplies the URL surface with thin pages. Opting out is cheaper and more honest than deleting the output afterwards.

security: SecurityConfig

Security tunables (v0.0.47 plan §3 item 2.3): the [security] section of ssg.toml. Currently holds the SRI digest algorithm; absent ⇒ SHA-384.

Implementations

impl SsgConfig

pub fn i18n_locales(&self) -> Vec<String>

The configured locales, or empty when multi-locale support is unavailable or unconfigured.

The i18n feature is the only thing in the crate that knows where these come from. Callers ask this instead of reaching for the field, so disabling the feature does not scatter cfg branches through every plugin that cares about locales.

pub fn i18n_locale_set(&self) -> Option<Vec<String>>

Every declared locale including the default, or None when no i18n configuration is reachable at all.

The None case is load-bearing and distinct from an empty list: callers use it to choose between strict matching against a declared set and a heuristic. Collapsing the two would make an undeclared de/ directory look like a locale page.

pub fn i18n_default_locale(&self) -> Option<String>

The configured default locale, or None when multi-locale support is unavailable, unconfigured, or set to an empty string.

pub fn from_matches(matches: &ArgMatches) -> Result<Self, CliError>

Creates a configuration by merging the default values with any command-line arguments.

Arguments

• matches - Parsed command-line arguments from Clap.

Errors

Returns a CliError if:

• A path fails validation (e.g., directory traversal or symlink).
• A URL is malformed.
• The language is incorrectly formatted.

Examples

let matches = cli.build().get_matches();
let config = SsgConfig::from_matches(&matches)?;

pub fn discover_config_file() -> Option<PathBuf>

Finds a configuration file when --config was not given.

Search order, first match wins:

1. ./ssg.toml — the name the documentation and every example use
2. ./config.toml — the name issue #730 was reported against
3. $SSG_CONFIG — an explicit path, for CI and wrapper scripts

The environment variable is checked last so a file in the project cannot be silently overridden by a stale variable in the shell.

pub fn discover_config_file_in(dir: &Path) -> Option<PathBuf>

Self::discover_config_file rooted at an explicit directory.

Taking the directory as a parameter keeps this testable without set_current_dir, which is process-wide: changing it from a test leaks into every other test resolving a relative path, in parallel.

pub fn from_subcommand_matches(sub_m: &ArgMatches) -> Result<Self, CliError>

Subcommand variant: subcommand parsers re-use the same --config / --content / --output / --template / --serve flag names but omit the legacy --new (project scaffolding is its own command). The override logic is identical otherwise, so we just delegate through a thin shim that skips the missing --new lookup.

Errors

Returns CliError under the same conditions as Self::from_matches.

pub fn from_file(path: &Path) -> Result<Self, CliError>

Loads configuration from a TOML or JSON file, enforcing a maximum file size limit.

The format is chosen by file extension: .json is parsed as JSON, anything else as TOML. Parsing every file as TOML meant a .json config — the form ssg.schema.json describes, and the form --config config/ssg.json invites — failed on its opening brace with “invalid key-value pair, expected key”, which reads as a malformed file rather than an unsupported format.

Arguments

• path - The path of the config file to be read.

Errors

Returns a CliError if:

• The file cannot be read or exceeds MAX_CONFIG_SIZE.
• The file is malformed for its format.
• Any fields fail validation afterward.

Examples

let config = SsgConfig::from_file(Path::new("config.toml"))?;
let config = SsgConfig::from_file(Path::new("config/ssg.json"))?;

pub fn apply_theme(&mut self, base: &Path) -> Result<(), CliError>

Resolves theme into template_dir, relative to base.

A no-op when no theme is named. An explicitly configured template_dir wins: naming both is how a project overrides one layout without forking the theme.

base is the directory of the config file, so a themes/ beside ssg.toml resolves whatever the working directory happens to be — a build must not depend on where it was invoked from.

Errors

CliError::ValidationError when the name does not resolve, carrying every path searched and the names that do exist.

pub fn validate(&self) -> Result<(), CliError>

Validates the configuration’s URLs and paths.

Examples

use ssg::cmd::SsgConfig;

let cfg = SsgConfig::default();
assert!(cfg.validate().is_ok());

Errors

Returns CliError::ValidationError when site_name is empty, or path/URL safety checks fail.

pub fn builder() -> SsgConfigBuilder

Returns a fresh SsgConfigBuilder for fluent construction.

Examples

use ssg::cmd::SsgConfig;

let cfg = SsgConfig::builder()
    .site_name("My Site".into())
    .build()
    .expect("valid config");
assert_eq!(cfg.site_name, "My Site");

Trait Implementations

impl Clone for SsgConfig

fn clone(&self) -> SsgConfig

Returns a duplicate of the value.

fn clone_from(&mut self, source: &Self)

Performs copy-assignment from source.

impl Debug for SsgConfig

fn fmt(&self, f: &mut Formatter<'_>) -> Result

Formats the value using the given formatter.

impl Default for SsgConfig

fn default() -> Self

Returns the “default value” for a type.

impl<'de> Deserialize<'de> for SsgConfig

fn deserialize<__D>(__deserializer: __D) -> Result<Self, __D::Error>

where __D: Deserializer<'de>,

Deserialize this value from the given Serde deserializer.

impl FromStr for SsgConfig

type Err = CliError

The associated error which can be returned from parsing.

fn from_str(s: &str) -> Result<Self, Self::Err>

Parses a string s to return a value of this type.

impl Serialize for SsgConfig

fn serialize<__S>(&self, __serializer: __S) -> Result<__S::Ok, __S::Error>

where __S: Serializer,

Serialize this value into the given Serde serializer.