Stalux Theme Configuration Overview

🕒 Reading time: 2 min📝 Words: 567👀 Views: Loading...
View Markdown source

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:

Terminal window
stalux/config/
├── site.yml          # Site identity: title, url, description, lang, timezone, canonical, favicon
├── author.yml        # Author info: name, avatar, bio, optional jobTitle
├── head.yml          # Analytics & custom <head>: Google Analytics, Bing Clarity, Umami, anyhead
├── navs.yml          # Navigation bar items
├── typetexts.yml     # Homepage typing animation texts
├── media-links.yml   # Social media links (rendered with simple-icons SVGs)
├── links.yml         # Friend links: title, description, sites list
├── footer.yml        # Footer: buildtime, copyright, theme, beian, badges, custom HTML
├── comment.yml       # Comment system (Waline): enabled toggle + waline config
├── promote.yml       # LLM promote hidden text + export_md toggle
└── 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:

Plugin Default behavior Disable / customize
@astrojs/sitemap Bundled; .md source endpoints filtered out by default sitemap: false, or pass options (a custom filter stacks with the default .md filter)
Expressive Code Bundled, line numbers enabled expressiveCode: false, or pass options (themes, frames, styles)
Math (Temml → MathML) features.math enabled on the default satteri() processor Set markdown.processor: satteri({ features: { math: false } }) in astro.config.mjs
GFM / frontmatter / smart punctuation Enabled by default on the satteri() processor Explicit false for the same feature key opts out
Mermaid MDAST detection + HAST/SVG rendering n/a — always injected
PhotoSwipe Image lightbox (HAST plugin) n/a — always injected

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:

Article Covers
_config_basic.md site.yml, author.yml, content collections
_config_header_and_head.md head.yml, navs.yml
_config_text_media.md typetexts.yml, media-links.yml, links.yml
_config_footer.md footer.yml
_config_comment.md comment.yml
_config_llm_promote.md promote.yml, ai-discovery.yml
_config_code.md Expressive Code (bundled, zero-config)
_markdown.md Markdown rendering & Sätteri processor

Stalux Theme Configuration Overview

Author: xingwangzhe

Article link: https://stalux.needhelp.icu/posts/0b563d42/

This article is licensed under Creative Commons Attribution-NonCommercial-ShareAlike 4.0 International License.

Creative Commons