Site Basic Information & Content Collections

site.yml — Site Identity

File: stalux/config/site.yml

1
id: site
2
lang: en # Language: "en" | "zh-CN"
3
title: Stalux Blog Theme # Site title
4
url: https://stalux.needhelp.icu # Site URL (used for canonical, RSS, OpenGraph)
5
description: "Blog theme Stalux ..." # Site description (SEO, OpenGraph)
6
accentColor: "#EAB308" # Optional shared theme and Waline accent; six-digit HEX
7
timezone: "Asia/Shanghai" # IANA timezone for date formatting
8
favicon: "/stalux.ico" # Favicon path
9
canonical: "https://stalux.needhelp.icu" # Canonical URL (optional, falls back to url)
10
# twitterSite:                        # Twitter/X site handle (optional)
11
# noindex: false                      # Global noindex (optional, default false)
12
# nofollow: false                     # Global nofollow (optional, default false)

accentColor defaults to #EAB308 and accepts #RRGGBB. Stalux derives the theme’s translucent accent tokens and Waline color from it. Choose a color with sufficient contrast against the site’s background.

This setting is optional: leave it out to keep the default, and existing site.yml files do not need to be edited. Stalux applies the default while reading site configuration as well as when generating color tokens, because Astro’s YAML content collection may omit Zod defaults from runtime data. This compatibility fix is included in Stalux v1.29.1. In v1.29.0, a consumer build with accentColor omitted could fail while rendering /404 with an undefined accent color.

author.yml — Author Information

File: stalux/config/author.yml

1
id: author
2
name: xingwangzhe # Display name
3
avatar: /avatar.png # Avatar path
4
bio: Blog Theme Stalux # Short bio
5
jobTitle: Software Engineer # Optional public role, emitted in JSON-LD Person

Rendered on: post sidebars, homepage author card, and SEO JSON-LD. jobTitle is optional and is emitted only in the JSON-LD Person entity; it does not change the visual author card.

Content Collections

Content is managed through Astro’s astro:content system under the stalux/ directory:

1
stalux/
2
├── posts/     # Blog posts (.md / .mdx)
3
├── about/     # About pages (.md / .mdx)
4
├── words/     # Quotes & snippets (.md)
5
└── config/    # Theme configuration (.yml)

Posts (stalux/posts/*.md)

Required frontmatter:

Optional frontmatter:

Example:

1
---
2
title: Sample Post
3
abbrlink: sample-post
4
date: 2025-05-10T12:00:00+08:00
5
desc: A short description for SEO and preview cards.
6
updated: 2025-05-12T09:00:00+08:00
7
tags: [Tech, Essay]
8
categories: [Frontend]
9
cc: CC-BY-NC-SA-4.0
10
draft: false
11
cover: /images/cover.jpg
12
---
13

14
Post body...

About (stalux/about/*.md)

Required: title (page title), description (page description).

Words (stalux/words/*.md)

Optional frontmatter: source, link, sourceDate, date, updated, draft.

Writing Notes

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.