Project Structure
Relevant source files
The following files were used as context for generating this wiki page:
The Charlotte project is a blog theme built using the Astro framework, with Svelte for components and Tailwind CSS for styling. The project structure is organized to separate content, configuration, application logic, and static assets, facilitating easy maintenance and content creation. It is based on the Fuwari theme.
The core of the project resides in the src directory, which contains all source code, including Astro pages, Svelte components, content collections, and configuration files. The root directory contains project-level configuration, scripts, and documentation.
Sources: README.md, src/content/posts/2025-09-29/Unveiling.md:8
Directory Layout
The following diagram illustrates the high-level directory structure of the project.
This diagram shows the main directories and key files, highlighting the separation of concerns within the project.
Sources: README.md, scripts/new-post.js, src/config.ts, src/content/posts/2018-10-30/Charlotte-Markdown.md
Root Directory
The root directory contains essential configuration files and scripts for managing the project.
| File / Directory | Description | Source |
|---|---|---|
package.json | Defines project metadata, dependencies (Astro, Svelte, etc.), and npm scripts. | package.json |
biome.json | Configures the Biome toolchain for code formatting and linting. | biome.json |
frontmatter.json | Defines the schema for post frontmatter, used by the Front Matter CMS extension. | frontmatter.json |
scripts/ | Contains helper scripts, such as new-post.js for creating new blog posts. | scripts/new-post.js |
src/ | The main application source code directory. | README.md:55 |
public/ | Contains static assets like favicons and images that are copied to the build output directly. | src/content/posts/2018-10-30/Charlotte-Markdown.md:43 |
Scripts
The package.json file defines several scripts for development, building, and maintenance.
| Command | Description |
|---|---|
pnpm dev | Starts the Astro development server after cleaning caches. |
pnpm build | Builds the site for production and runs Pagefind for search indexing. |
pnpm new-post <filename> | Creates a new post markdown file with pre-filled frontmatter. |
pnpm format | Formats the code in the ./src directory using Biome. |
pnpm lint | Checks and fixes code style issues in the ./src directory using Biome. |
pnpm clean | Removes Astro, Vite, and dist caches. |
Sources: package.json:5-16, README.md:28-40
Source Directory (src/)
This is the heart of the Astro application, containing all the logic, content, and components.
Content (src/content/)
Astro's Content Collections are used to manage blog posts. All posts are stored as Markdown files within src/content/posts/. A post can be a single .md file or an index.md file within its own asset directory.
src/content/posts/
├── post-1.md
└── post-2/
├── cover.png
└── index.md
Sources: src/content/posts/2018-10-30/Charlotte-Markdown.md:38-44
Post Frontmatter
Each post begins with a YAML frontmatter block that defines its metadata. The schema is defined in frontmatter.json.
| Attribute | Type | Description |
|---|---|---|
title | string | The title of the post. |
published | datetime | The publication date. |
description | string | A short summary of the post. |
image | string | Path to the post's cover image. |
tags | string[] | A list of tags associated with the post. |
category | string | The category of the post. |
draft | boolean | If true, the post is not included in the production build. |
Sources: src/content/posts/2018-10-30/Charlotte-Markdown.md:20-29, frontmatter.json:17-68
Configuration (src/config.ts)
The central configuration file src/config.ts exports several objects to customize the site's appearance and behavior.
siteConfig: The main configuration object for site-wide settings.navBarConfig: Configures the navigation bar links and appearance.profileConfig: Defines the content of the author profile sidebar.licenseConfig: Sets the content license information.expressiveCodeConfig: Configures the theme for code blocks.
The SiteConfig type defines the shape of the main configuration object.
This diagram shows the structure of the SiteConfig type, which governs the primary settings of the blog.
Sources: src/config.ts:11-70, src/types/config.ts:3-39
Utilities (src/utils/)
This directory contains helper functions used throughout the application. A key file is content-utils.ts, which handles fetching, sorting, and processing blog posts.
Post Sorting and Pinning Logic
The getSortedPosts function retrieves all non-draft posts, sorts them by publication date (newest first), and then applies a pinning logic. Pinned posts, defined in siteConfig.pinnedPost, are moved to the top of the list while maintaining their configured order.
This flowchart illustrates the process of fetching and preparing posts for display.
Sources: src/utils/content-utils.ts:49-84
Pages (src/pages/)
This directory follows Astro's file-based routing. It contains files that generate site pages and API endpoints. For example, rss.xml.ts and atom.xml.ts generate the RSS and Atom feeds for the blog by fetching sorted posts and rendering them into XML format.
Sources: src/pages/rss.xml.ts, src/pages/atom.xml.ts
Scripts (scripts/)
The scripts/ directory holds Node.js scripts for automating tasks.
Creating a New Post
The new-post.js script, executed via pnpm new-post <filename>, automates the creation of a new blog post. It generates a Markdown file in src/content/posts/ with a pre-populated frontmatter template.
This sequence diagram shows the workflow when a user creates a new post using the provided script.
Sources: scripts/new-post.js, package.json:11
Summary
The Charlotte project is structured logically around the Astro framework's conventions. It clearly separates content from configuration and presentation, making it highly customizable and easy to manage. The use of content collections for posts, a centralized configuration file, and helper scripts for automation provides a robust foundation for a personal blog.