Site Configuration (config.ts)
Relevant source files
The following files were used as context for generating this wiki page:The src/config.ts file is the central hub for customizing the Charlotte blog theme. It exports several configuration objects that control the site's metadata, appearance, navigation, author profile, and other features. By leveraging TypeScript, all configurations are strongly typed, providing excellent autocompletion and compile-time checks to prevent errors.
This system is designed for easy modification, allowing developers to personalize their blog by editing a single file. The configurations defined here are consumed throughout the application, from rendering UI components and generating RSS feeds to applying themes and ordering posts.
Configuration Architecture
The configuration is modular, with distinct objects for different aspects of the site. The primary types are defined in src/types/config.ts and implemented in src/config.ts.
The following diagram illustrates the main configuration objects and their relationships.
This class diagram shows the structure of the main configuration types defined in src/types/config.ts.
Sources: src/types/config.ts
Main Configurations
The primary configurations are exported as constants from src/config.ts.
siteConfig
This is the most extensive configuration object, controlling global site settings, metadata for SEO, and major features like the banner and pinned posts.
Sources: src/config.ts:10-70, src/types/config.ts:3-52
| Property | Type | Description |
|---|---|---|
title | string | The main title of the blog. Used in the browser tab, SEO, and RSS feeds. |
subtitle | string | A short subtitle for the blog. |
url | string | The full base URL of the blog. Essential for generating absolute links in RSS/Atom feeds. |
lang | 'en' | 'zh_CN' | 'zh_TW' | 'ja' | The primary language of the site. Used for lang attributes and i18n. |
keywords | string | Comma-separated keywords for SEO purposes. |
description | string | A brief description of the site for SEO and RSS feeds. |
themeColor | object | Configures the site's color theme. See details below. |
defaultTheme | 'light' | 'dark' | 'auto' | The default color mode for new visitors. |
banner | object | Configuration for the homepage banner. See details below. |
toc | object | Configuration for the Table of Contents on post pages. |
startDate | string | The website's start date, used to calculate runtime. Format: ISO 8601 string. |
favicon | Favicon[] | An array of favicon objects to specify different icons. |
pinnedPost | string | string[] | An array of post slugs to pin to the top of the homepage. |
performance | object | Settings related to site performance optimizations. |
themeColor Object
| Property | Type | Description |
|---|---|---|
hue | number | The default HSL hue value (0-360) for the site's primary color. |
fixed | boolean | If true, hides the theme color selector from visitors. |
| Sources: src/config.ts:19-22, src/types/config.ts:11-14 |
banner Object
| Property | Type | Description |
|---|---|---|
enable | boolean | Toggles the visibility of the homepage banner. |
src | string | Path to the banner image. Relative to /src or /public if it starts with /. |
position | 'top' | 'center' | 'bottom' | CSS object-position for the banner image. Defaults to center. |
credit | object | Displays copyright information for the banner image. Contains enable, text, and url properties. |
text | object | Configures the text overlay on the banner, including title, subtitle (typewriter effect), and color. |
| Sources: src/config.ts:24-42, src/types/config.ts:16-35 |
Pinned Posts Logic
The pinnedPost array in siteConfig is used by the getSortedPosts function to display specific posts at the top of the list, regardless of their publication date.
The following diagram shows the process of sorting posts with pinned items.
Sources: src/utils/content-utils.ts:18-56
navBarConfig
This object configures the links and appearance of the main navigation bar.
Sources: src/config.ts:72-89, src/types/config.ts:59-67
| Property | Type | Description |
|---|---|---|
links | (NavBarLink | LinkPreset)[] | An array of links. Can use LinkPreset enums (Home, Archive, About) for standard pages or a NavBarLink object for custom internal/external links. |
opacity | number | A value from 0-100 to set the navigation bar's transparency. |
hideButtonsOnPostPage | boolean | If true, hides the theme switcher and color picker buttons on post pages. |
Example of a custom link:
{
name: "书签柜",
url: "https://tabs.chuwu.top/", // External URL
external: true, // Opens in a new tab and shows an icon
}
Sources: src/config.ts:78-82
profileConfig
Defines the content of the author profile card, typically shown in the sidebar.
Sources: src/config.ts:91-115, src/types/config.ts:69-79
| Property | Type | Description |
|---|---|---|
avatar | string | Path to the avatar image. Relative to /src or /public. |
name | string | The author's name. |
bio | string | A short biography. |
links | object[] | An array of social media or contact links, each with a name, icon (from icones.js.org), and url. |
licenseConfig
Controls the display of a content license at the bottom of posts.
Sources: src/config.ts:117-121, src/types/config.ts:81-85
| Property | Type | Description |
|---|---|---|
enable | boolean | If true, displays the license information. |
name | string | The name of the license (e.g., "CC BY-NC-SA 4.0"). |
url | string | A URL to the full license text. |
expressiveCodeConfig
Configures the theme for code blocks rendered by the Astro Expressive Code integration.
Sources: src/config.ts:123-127, src/types/config.ts:98-100
| Property | Type | Description |
|---|---|---|
theme | string | The name of the theme to use for syntax highlighting. The project recommends a dark theme. |
Theme and Appearance Management
The theme settings from siteConfig are managed by utility functions in src/utils/setting-utils.ts. These functions read from and write to localStorage to persist user choices, falling back to the values in config.ts.
The following diagram shows how the application determines and applies the color mode (light/dark/auto).
This sequence shows the logic for loading the theme preference, starting from the component, checking local storage, falling back to the configuration, and finally applying the correct class to the document.
Sources: src/components/LightDarkSwitch.svelte, src/utils/setting-utils.ts:47-73
Summary
The configuration system in src/config.ts is a powerful and developer-friendly feature of the Charlotte theme. It provides a single, type-safe source of truth for customizing nearly every aspect of the blog, from metadata and branding to layout and functionality. Its modular structure and clear separation of concerns make it easy to manage and extend. The reliance on this central file simplifies personalization and ensures consistency across the entire site.