Quick Start & Installation
Relevant source files
The following files were used as context for generating this wiki page:This guide provides instructions for setting up the development environment, installing dependencies, and running the Charlotte blog project. Charlotte is a blog theme built with the Astro framework, based on the Fuwari theme. Following these steps will allow you to run a local instance of the blog, create new content, and build the project for deployment.
This document covers environment prerequisites, installation commands, project configuration, and content creation workflows.
Sources: README.md:3, src/content/posts/2025-09-29/Unveiling.md:10
Prerequisites
Before starting, ensure your development environment meets the following requirements. The project enforces the use of pnpm as the package manager via a preinstall script in package.json.
- Node.js: Version 22 or higher.
- pnpm: Version 9 or higher.
Sources: README.md:18-19, package.json:13
The following diagram illustrates the initial environment setup check.
Sources: README.md:18-19
Installation and Core Commands
Once the prerequisites are met, you can install the project dependencies and use the provided npm scripts to run, build, and maintain the application.
Common Commands
The following table lists the most common commands for managing the project. These are defined in the scripts section of package.json.
| Command | Description |
|---|---|
pnpm install | Installs all project dependencies. |
pnpm dev | Cleans cache and starts the local development server. |
pnpm build | Cleans cache, builds the production version, and runs Pagefind for search indexing. |
pnpm preview | Previews the production build locally. |
pnpm check | Runs Astro's type checker to find errors. |
pnpm format | Formats the codebase using Biome. |
pnpm lint | Lints and automatically fixes issues in the codebase with Biome. |
pnpm new-post <filename> | Creates a new blog post markdown file with frontmatter. |
pnpm clean | Removes cache files from .astro, dist, and node_modules/.vite. |
Sources: README.md:22-32, package.json:5-14
Development Workflow
The typical workflow for local development is to install dependencies and start the development server.
Sources: package.json:5, README.md:24-25
Creating New Content
The project includes a helper script to streamline the creation of new blog posts.
new-post Script
To create a new post, run the pnpm new-post command followed by the desired filename. The .md extension is optional and will be added automatically.
pnpm new-post <filename>
Sources: README.md:35-37, package.json:10
This script performs the following actions:
- Checks if a filename argument is provided.
- Ensures the file does not already exist in
src/content/posts/. - Creates the necessary subdirectories if they don't exist.
- Generates a new markdown file at
src/content/posts/<filename>.mdwith a pre-populated frontmatter template.
The following sequence diagram shows the script's execution flow.
Sources: scripts/new-post.js:3-48
Post Frontmatter
Each new post is created with a default frontmatter block. You must fill in these fields to define the post's metadata.
---
title: ${args[0]}
published: ${getDate()}
description: ''
image: ''
tags: []
category: ''
draft: false
lang: ''
---
Sources: scripts/new-post.js:40-48
The table below describes each frontmatter field.
| Attribute | Description |
|---|---|
title | The title of the post. |
published | The publication date of the post. |
description | A brief summary of the post, displayed on the homepage. |
image | The cover image for the post. Can be a URL, a path from /public, or a relative path. |
tags | An array of tags associated with the post. |
category | The category the post belongs to. |
draft | A boolean (true/false). If true, the post will not be displayed on the homepage. |
lang | Language of the post. |
Sources: src/content/posts/2018-10-30/Charlotte-Markdown.md:19-28
Configuration
The blog's primary configuration is managed in src/config.ts. This file exports several objects that control the site's appearance, metadata, and behavior.
The configuration data structures are defined in src/types/config.ts. The diagram below shows the relationship between the main configuration types.
Sources: src/types/config.ts:3-76
Site Configuration (siteConfig)
This object contains global settings for the site.
| Property | Description | Example Value |
|---|---|---|
title | The main title of the blog. | "初五的小窝" |
subtitle | A subtitle displayed on the site. | "时间能冲淡痛苦" |
url | The base URL of the deployed site. | "https://blog.chuwu.top/" |
lang | The primary language of the site. | "zh_CN" |
keywords | SEO keywords for the site. | "Chuwu, 博客, 编程, ..." |
description | The site's meta description. | "ChuwuYo的小窝, ..." |
themeColor | Configures the default theme hue and whether users can change it. | { hue: 65, fixed: false } |
defaultTheme | The default color mode: 'light', 'dark', or 'auto'. | "dark" |
banner | Configuration for the homepage banner. | { enable: true, src: "...", ... } |
toc | Enables and configures the table of contents on post pages. | { enable: true, depth: 2 } |
startDate | The date the website was launched, used for the runtime counter. | "2025-09-29T12:30:00" |
favicon | An array of favicon objects. | [{ src: "/favicon/icon_256.webp", ... }] |
pinnedPost | An array of post slugs to be pinned to the top of the post list. | ["2025-09-29/Unveiling"] |
Sources: src/config.ts:10-63, src/types/config.ts:3-50
Navigation Bar (navBarConfig)
This object controls the links and appearance of the main navigation bar.
| Property | Description | Example Value |
|---|---|---|
links | An array of links to display. Can use LinkPreset enums or custom link objects. | [LinkPreset.Home, LinkPreset.Archive, ...] |
opacity | Transparency of the navbar (0-100). | 70 |
hideButtonsOnPostPage | If true, hides theme and color switcher buttons on post pages. | false |
Sources: src/config.ts:65-80, src/types/config.ts:58-68
Profile (profileConfig)
This object configures the author profile section displayed in the sidebar.
| Property | Description | Example Value |
|---|---|---|
avatar | Path to the avatar image. | "assets/images/avatar.webp" |
name | The author's name. | "ChuwuYo" |
bio | A short biography. | "消失了什么，我不知道" |
links | An array of social media and contact links. | [{ name: "GitHub", icon: "...", url: "..." }] |
Sources: src/config.ts:82-103, src/types/config.ts:70-79
Deployment
The project is built as a static site. The build process generates all necessary files in the dist/ directory.
The build and deployment flow is as follows:
Sources: README.md:83-84, package.json:8
After running pnpm build, the contents of the dist/ directory can be deployed to any static hosting provider such as Netlify, Vercel, or GitHub Pages.