Site Configuration

The site configuration contract defines every global setting that components, layouts, and utilities read at build time. The contract lives in two files across the core/ and site/ directories:

• src/core/config/site.schema.ts (CORE-OWNED) — TypeScript types, interfaces, and DEFAULT_SITE_CONFIG
• src/site/config/site.ts (SITE-OWNED) — the site-specific instance that overrides defaults

Some build-time settings are defined in standalone site-owned modules and then assigned into siteConfig so Astro config and validation scripts can read the same values without importing asset-heavy site.ts:

• src/site/config/platform.config.ts — platformConfig for trailing slash behavior, theme-doc route generation, article pagination, and markdown lightbox collection defaults
• src/site/config/fonts.config.ts — siteFonts
• src/site/config/site-url.ts — siteUrl

Navigation configuration (main menu and utility nav) is in a separate contract — see Menu Configuration.

For the complete field inventory with types and defaults, see src/core/config/site.schema.ts. This reference documents the system structure, customization pattern, and key design decisions.

Who this is for

• Implementors building components that consume site config
• Developers customizing a site instance
• AI agents generating or modifying config values

Customization Pattern

The site instance uses a spread-override pattern. Import the defaults and override only what differs:

// src/site/config/site.ts (SITE-OWNED)
// See site.schema.ts for all available fields, types, and defaults.
import { DEFAULT_SITE_CONFIG, type SiteConfig } from "@core/config/site.schema";

export const siteConfig: SiteConfig = {
  ...DEFAULT_SITE_CONFIG,

  // ── Site Identity ─────────────────────────────────────────────────
  siteName: "My Agency",
  siteTitle: "My Agency — Web Solutions",

  // ── Contact & Legal ───────────────────────────────────────────────
  contact: {
    ...DEFAULT_SITE_CONFIG.contact,
    legalName: "My Agency LLC",
    contactEmail: "[email protected]",
  },
};

site.schema.ts is the canonical reference for all available fields, types, and defaults. Only override fields that differ from the defaults — the spread provides everything else.

Nested objects (e.g., contact, branding, copyright) require their own spread to preserve sibling defaults.

Site Icons

The Icon component resolves icon names using a layered lookup across site/ and core/ directories. Site icons shadow core icons of the same name, following the same override model as config:

Resolution order	Directory
1 (highest)	src/site/assets/icons/utility/
2	src/site/assets/icons/social/
3	src/core/assets/icons/utility/
4 (lowest)	src/core/assets/icons/social/

To override a core icon, place an SVG with the same filename in the corresponding src/site/assets/icons/ subdirectory. To add site-specific icons, add SVGs to either utility/ or social/ under src/site/assets/icons/.

Icons are resolved at build time via Vite glob imports. A build error is thrown if the icon name cannot be found in any layer.

Styling Configuration

Typography, fluid token overrides, and the core style override system are documented in Site Styling Configuration (DOC-00089).

Feature Configuration

Theme mode, theme-docs, article listing, analytics/consent, scroll-to-top, lightbox, and environment variables are documented in Site Feature Configuration (DOC-00090).

Configuration Sections

Each section maps to a charter requirement. The SiteConfig interface groups fields into these nested objects:

Site Identity & SEO Defaults

Top-level fields on SiteConfig for brand name, default <title>, meta description, site URL, locale, and OG image. These are the most frequently referenced settings — every layout reads siteName and siteTitle.

Contact & Legal

Nested under contact: ContactConfig. Legal entity name, email, optional email label, phone, optional phone label, and multi-line address (addressLines?: [string, string?, string?]). Components use these for footer contact info and structured data.

Copyright

Nested under copyright: CopyrightConfig. Uses a template system with {year}, {holder}, and {suffix} placeholders so components can interpolate at render time:

const copyright = {
  holder: "My Agency LLC",
  year: "auto", // resolves to current year at build time
  suffix: "All Rights Reserved.",
  template: "Copyright © {year} {holder}. {suffix}",
};

Social Links

Top-level socialLinks: SocialLinksConfig — an array of SocialLink objects (label, href, icon) reusable across footer, about page, contact page, and structured data:

const socialLinks = [
  {
    label: "GitHub",
    href: "https://github.com/myagency",
    icon: "fa-brands fa-github",
  },
  {
    label: "LinkedIn",
    href: "https://linkedin.com/company/myagency",
    icon: "fa-brands fa-linkedin",
  },
];

Branding & Logos

Nested under branding: BrandingConfig. Logo assets are imported directly in site.ts using Vite’s ?url suffix, which resolves them to browser-resolvable URLs at build time. The logoUsageMatrix controls which variant renders per location and theme mode.

Configure all branding fields in site.ts alongside the imports:

// src/site/config/site.ts (SITE-OWNED)
import logoMain from "@site/assets/images/logo/logo-primary.svg?url";
import logoAlt from "@site/assets/images/logo/logo-dark.svg?url";

const branding = {
  ...DEFAULT_SITE_CONFIG.branding,
  logoMain, // resolved URL — primary logo variant
  logoAlt, // resolved URL — alternate logo variant
  logoText: "My Agency", // text fallback; also base for alt text
  logoUsageMatrix: {
    header: { light: "logoMain", dark: "logoAlt" },
    footer: { light: "logoMain", dark: "logoMain" },
  },
};

• logoMain and logoAlt are optional. When absent the component renders logoText as a <span>.
• logoText is optional. When absent the component falls back to siteConfig.siteName.
• logoUsageMatrix is optional. When absent both locations use logoMain for all theme modes.
• Logo files live in src/site/assets/images/logo/. Use ?url for SVG and raster files where a plain URL is sufficient; use a standard import for ImageMetadata if Astro image optimization is needed.
• Header logo display width (--pt-size-logo-header-width) is a fluid custom token — override it in src/site/config/fluid-tokens.config.ts (see Fluid Token Overrides). Footer logo display width (--pt-size-logo-footer-width) is a static token in src/site/styles/primitives.css.

Favicons

Nested under favicons: FaviconConfig. Paths for .ico, .svg, Apple touch icon, and web manifest. All fields have sensible defaults.

Header

Nested under header: HeaderConfig. Controls the site header layout and mobile navigation behavior.

Field	Type	Default	Description
navPosition	'left' | 'center' | 'right'	'right'	Position of MainNav relative to logo and controls
stickyHeader	'none' | 'sticky' | 'scroll-up'	'scroll-up'	Header scroll behavior: 'none' = default flow; 'sticky' = position: sticky; 'scroll-up' = fixed header, hides on scroll-down, reappears on scroll-up
mobileMenuPosition	'left' | 'right' | 'full-width'	'right'	Side the mobile menu drawer slides in from
search.enabled	boolean	true	Whether the search trigger renders in the header and mobile panel
search.behavior	'modal' | 'page'	'modal'	'modal' renders a search trigger button (no-op until search modal is implemented); 'page' navigates to search.href
search.href	string	'/search/'	URL used when behavior is 'page'
cta	HeaderCtaConfig | undefined	undefined	Optional CTA button — { label, href, variant? }. Omit to suppress.

Footer

Nested under footer: FooterConfig. Controls heading visibility and heading labels for footer nav groups.

Field	Type	Default	Description
showFooterNav1Heading	boolean	true	Whether to render the footerNav1 heading visibly
footerNav1HeadingLabel	string	"Resources"	Label text for footerNav1 heading
showFooterNav2Heading	boolean	true	Whether to render the footerNav2 heading visibly
footerNav2HeadingLabel	string	"Company"	Label text for footerNav2 heading
showFooterNav3Heading	boolean	false	Whether to render the footerNav3 heading visibly
footerNav3HeadingLabel	string	"Legal"	Label text for footerNav3 navigation label

For theme mode, analytics, scroll-to-top, lightbox, theme-docs, article listing, and environment variables, see Site Feature Configuration (DOC-00090).