Technology Stack

Relevant source files

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

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

The Charlotte project is a blog theme built upon a modern, performance-oriented technology stack. It leverages the Astro framework for its static-site generation capabilities, ensuring a fast user experience. The component architecture is powered by Svelte, and styling is managed through Tailwind CSS.

The project emphasizes a streamlined developer experience with integrated tooling for code formatting, linting, and type-checking. The content pipeline is robust, supporting extended Markdown features, RSS/Atom feed generation, and on-site search functionality. The overall architecture is designed to produce a highly configurable and extensible static blog.

Sources: README.md, package.json, src/content/posts/2025-09-29/Unveiling.md:9

Core Technologies

The foundation of the Charlotte blog theme is built on Astro, Svelte, and TypeScript.

This diagram provides a high-level overview of the main technologies used in the project and their relationships.

Sources: package.json:16-52, README.md:12

Frameworks

• Astro: The core of the project is the Astro framework (astro@5.16.8). It is used to build the static site, handling routing, data fetching from local Markdown files, and integrating various UI frameworks and tools.
  Sources: package.json:28, README.md:12
• Svelte: Interactive UI components, such as the ArchivePanel, are built using Svelte (svelte@5.39.7). Astro's integration (@astrojs/svelte@7.2.2) allows for seamless embedding of Svelte components within Astro pages.
  Sources: package.json:19, 50, src/components/ArchivePanel.svelte

Language

• TypeScript: The project is written in TypeScript (typescript@5.9.2) to ensure type safety and improve code quality. Configuration files, utility functions, and component logic all use TypeScript. The astro check command is configured to perform type-checking.
  Sources: package.json:17, 51, src/config.ts, src/utils/content-utils.ts

Styling

Styling is managed by Tailwind CSS, with additional customizations for Markdown content and page transitions.

• Tailwind CSS: A utility-first CSS framework (tailwindcss@3.4.17) used for the majority of the site's styling. It is integrated via @astrojs/tailwind.
  Sources: package.json:20, 50
• PostCSS: Used for processing CSS, with plugins like postcss-nesting to enable nested CSS syntax within style files.
  Sources: package.json:60
• Custom Styles:
  • src/styles/markdown.css: Provides custom styles for HTML elements generated from Markdown, such as headers, links, and code blocks. It uses @apply to leverage Tailwind's utility classes.
  • src/styles/transition.css: Defines CSS animations for page transitions managed by Swup, creating fade and slide effects.
    Sources: src/styles/markdown.css, src/styles/transition.css

Content & Markdown Processing

The project has a sophisticated pipeline for processing Markdown content, adding features like syntax highlighting, math formulas, and custom containers.

This flowchart shows how a Markdown file is processed through various Remark and Rehype plugins before being rendered as HTML.

Sources: package.json:30-47

Key Libraries

Library	Version	Description
remark-math	6.0.0	Enables parsing of math syntax (e.g., $E=mc^2$).
rehype-katex	7.0.1	Renders math syntax into HTML using the KaTeX library.
remark-directive	4.0.0	Adds support for generic directives syntax (e.g., ::note).
remark-github-admonitions-to-directives	2.0.0	Converts GitHub-style admonitions (> [!NOTE]) to directives.
astro-expressive-code	0.41.3	Provides advanced syntax highlighting for code blocks, including a toolbar with language display and a copy button.
rehype-slug	6.0.0	Adds id attributes to headings.
rehype-autolink-headings	7.1.0	Adds anchor links to headings for easy linking.

Sources: package.json:30-47, src/content/posts/2018-10-30/Charlotte-Markdown.md:88, 117

Feed Generation

The site generates both RSS and Atom XML feeds for content syndication.

• RSS Feed: src/pages/rss.xml.ts uses the @astrojs/rss package to generate an rss.xml file. It fetches sorted posts, renders the Markdown body to HTML, and sanitizes it using sanitize-html before including it in the feed.
• Atom Feed: src/pages/atom.xml.ts uses astrojs-atom to generate an atom.xml file, following a similar process of fetching posts and processing their content.

In both cases, a MarkdownIt instance is used to convert post content to HTML for the feeds.

Sources: src/pages/rss.xml.ts, src/pages/atom.xml.ts, package.json:17, 29

Tooling and Development

The project uses a set of modern tools to ensure code quality, consistency, and a smooth development workflow.

Development Scripts

The package.json file defines several scripts for common development tasks.

Command	Description
pnpm dev	Starts the Astro development server with hot-reloading.
pnpm build	Builds the site for production and runs pagefind to create a search index.
pnpm check	Runs astro check for TypeScript error checking.
pnpm format	Formats the codebase using Biome.
pnpm lint	Checks and fixes code style issues using Biome.
pnpm new-post <filename>	Executes a Node.js script (scripts/new-post.js) to create a new blog post with pre-filled frontmatter.

Sources: package.json:5-15, README.md:27-41, CONTRIBUTING.md:18-21

Code Quality

• Biome: The project uses Biome (@biomejs/biome@2.3.11) for both code formatting and linting. The configuration in biome.json specifies an indent style of tab, enables recommended linter rules, and sets overrides for .svelte and .astro files to disable certain rules that conflict with their syntax.
  Sources: biome.json, package.json:54
• pnpm: The project enforces the use of pnpm as the package manager via a preinstall script. The required version is specified as >=9 in the README.md.
  Sources: package.json:14, README.md:24
• Conventional Commits: The CONTRIBUTING.md file encourages contributors to use the Conventional Commits format for commit messages to maintain a clear and consistent project history.
  Sources: CONTRIBUTING.md:14-15

Search

Client-side search functionality is implemented using Pagefind (pagefind@1.4.0). The pnpm build script runs pagefind --site dist after the Astro build is complete, which indexes the static HTML files in the dist/ directory.
Sources: package.json:9, 39