Deployment Guide

Relevant source files

The following files were used as context for generating this wiki page:

• README.md
• package.json
• src/config.ts
• CONTRIBUTING.md
• scripts/new-post.js
• src/content/posts/2018-10-30/Charlotte-Markdown.md
• src/pages/rss.xml.ts

This guide provides instructions for building and deploying the Charlotte blog project. The project is built using the Astro framework, which generates a static site. The deployment process involves setting up the environment, configuring the site, building the static files, and hosting them on a static web host. The final output is located in the dist/ directory.

The project includes deployment status badges for Netlify and Vercel, indicating these are suitable and tested hosting platforms.

Sources: README.md:1-49, package.json:11

1. Prerequisites

Before deployment, ensure your development environment meets the following requirements.

Environment Requirements

Tool	Version
Node.js	>= 22
pnpm	>= 9

Sources: README.md:27-29

Install Dependencies

Once the environment is set up, install the project dependencies using the following command:

pnpm install

This command uses pnpm to install all the necessary packages defined in package.json.

Sources: README.md:34, package.json:51

2. Configuration

The primary configuration file for the site is src/config.ts. It is crucial to review and customize this file before building the site for production.

Site Configuration (siteConfig)

The siteConfig object contains metadata for the site, including SEO details, theme settings, and banner information.

Property	Description	Example Value
title	The main title of the blog.	"初五的小窝"
subtitle	A subtitle for the blog.	"时间能冲淡痛苦"
url	The absolute production URL of the blog. This is critical for generating correct sitemaps and RSS feeds.	"https://blog.chuwu.top/"
lang	The primary language of the site (e.g., 'en', 'zh_CN').	"zh_CN"
keywords	A string of comma-separated keywords for SEO.	"Chuwu, 博客, 编程, ..."
description	The site description for SEO and metadata.	"ChuwuYo的小窝, ..."
pinnedPost	An array of post slugs to be pinned to the top of the post list.	["2025-09-29/Unveiling"]
favicon	An array of favicon objects with paths relative to the /public directory.	[{ src: "/favicon/icon_256.webp", ... }]

Sources: src/config.ts:11-71, src/types/config.ts:3-44

Content Management

Blog posts are stored as Markdown files in the src/content/posts/ directory. Each post must include a frontmatter section with metadata.

Creating a New Post

A script is provided to simplify the creation of new posts.

pnpm new-post <filename>

This command creates a new Markdown file in src/content/posts/ with a pre-filled frontmatter template.

Sources: README.md:40-43, scripts/new-post.js:1-44, package.json:14

Post Frontmatter

The frontmatter is essential for how the post is processed and displayed.

Attribute	Description
title	The title of the post.
published	The publication date.
description	A short summary of the post, displayed on the homepage.
image	The path to the post's cover image.
tags	An array of tags associated with the post.
category	The category of the post.
draft	A boolean (true/false) indicating if the post is a draft.

Sources: src/content/posts/2018-10-30/Charlotte-Markdown.md:2-11

3. Build Process

The build process compiles the Astro project, processes Markdown files, and generates static HTML, CSS, and JavaScript files, along with other assets like RSS/Atom feeds.

Build Command

The entire build process can be triggered with a single command:

pnpm build

Sources: README.md:36, package.json:11

Build Workflow

The pnpm build script executes a sequence of three commands. This diagram illustrates the workflow.

This diagram shows the sequence of operations executed by the pnpm build command.

Sources: package.json:11,18

1. pnpm clean: This command removes previous build artifacts and caches (.astro, dist, and .vite directories) to ensure a clean build.
   Sources: package.json:18
2. astro build: This is the core Astro command that builds the static site. It transforms all source files (like .astro, .svelte, .md) into a production-ready static website.
   Sources: package.json:11
3. pagefind --site dist: After the site is built, this command runs Pagefind to create a static search index from the content in the dist/ directory. This enables client-side search functionality on the deployed site.
   Sources: package.json:11

Build Output

The output of the build process is placed in the dist/ directory. This directory contains all the static files needed to run the website and is the target for deployment.

Sources: README.md:112-113, package.json:11

4. Pre-Deployment Checks

Before committing code and deploying, it is recommended to run the provided checking and formatting scripts to maintain code quality.

Command	Description
pnpm check	Runs astro check for TypeScript errors.
pnpm format	Formats the code in the ./src directory using Biome.
pnpm lint	Checks and fixes code style issues in ./src using Biome.

Sources: README.md:32-38, CONTRIBUTING.md:15-18, package.json:10,15,16

5. Deployment

The generated dist/ directory contains a fully static website. You can deploy this directory to any static hosting service.

Common static hosting platforms include:

• Netlify
• Vercel
• GitHub Pages
• Cloudflare Pages

The README.md file includes deployment status badges for Netlify and Vercel, confirming the project's compatibility with these services.

Sources: README.md:13-15,112-113

Summary

Deploying the Charlotte blog is a straightforward process common to modern static site generators. It involves ensuring the environment is correctly set up, customizing site-specific details in src/config.ts, and running the pnpm build command. The resulting dist/ folder is a self-contained static site ready to be uploaded to any static web hosting provider.