Stalux Theme Configuration Overview

Configuration File Structure

The Stalux theme uses Astro content collections. Configuration files are stored as individual YAML files under stalux/config/, each validated by a dedicated Zod schema. site.yml accepts an optional six-digit HEX accentColor (default #EAB308) that controls the theme and Waline accent; leave it out to use the default, and choose a shade with sufficient contrast against your background. Existing config files need no migration for this option. Stalux v1.29.1 applies this default at runtime as well as in the schema, covering Astro YAML collection data that omits Zod defaults. See _config_basic.md for the v1.29.0 compatibility incident and details:

1
stalux/config/
2
├── site.yml          # Site identity: title, url, description, lang, timezone, canonical, favicon
3
├── author.yml        # Author info: name, avatar, bio, optional jobTitle
4
├── head.yml          # Analytics & custom <head>: Google Analytics, Bing Clarity, Umami, anyhead
5
├── navs.yml          # Navigation bar items
6
├── typetexts.yml     # Homepage typing animation texts
7
├── media-links.yml   # Social media links (rendered with simple-icons SVGs)
8
├── links.yml         # Friend links: title, description, sites list
9
├── footer.yml        # Footer: buildtime, copyright, theme, beian, badges, custom HTML
10
├── comment.yml       # Comment system (Waline): enabled toggle + waline config
11
├── promote.yml       # LLM promote hidden text + export_md toggle
12
└── ai-discovery.yml  # AI discovery files (llms.txt, ai.txt, etc.): conformance level & overrides

The schema definitions are in src/schemas/config.ts, using z.discriminatedUnion("id") to join them into a single config collection.

Quick Start

1. Set your site identity in site.yml
2. Add your name/bio in author.yml; optionally add the public jobTitle for JSON-LD
3. Configure navigation in navs.yml
4. Add social links in media-links.yml
5. Add analytics in head.yml when needed (bingClarityId is the Microsoft Clarity Project ID)
6. Build: bun run build

Bundled Integrations (Zero Configuration)

Since v1.24.0, the Stalux integration bundles the plugins that previously required manual setup in astro.config.mjs — integrations: [stalux()] is all you need:

If you replace the default satteri() processor with another one, Stalux logs a warning and skips the markdown plugin injection.

Validation

All config files are validated at build time against their Zod schemas. Missing required fields or invalid formats will produce clear error messages.

Detailed Guides

See the _config_*.md article series under stalux/posts/ for each config section:

Visitor weather is optional: set weather: { enabled: true } in stalux/config/site.yml to show it as plain text in the footer (with visitor IP and approximate location) and below the desktop article clock. Omitted or false disables it. It automatically requests an approximate city from IP.SB (with IPinfo as fallback) and weather from Open-Meteo, only while visible; no browser GPS permission is requested. These external services receive the visitor IP, and Open-Meteo receives rounded coordinates. A 20-minute session cache stores the city, visitor IP and weather, without coordinates. Visitors behind VPNs may see the exit city. Hidden tabs, offscreen cards and Astro navigation stop work; unavailable services show a retry action and retain previous weather. Open-Meteo’s free endpoint is for non-commercial use subject to its limits; the card links to its attribution licence. No server endpoint or extra package is needed.