CLAUDE.md ​

This file provides guidance to Claude Code (claude.ai/code) when working with code in this repository.

Project Overview ​

This is a personal blog/website built with VitePress and styled using Tailwind CSS v4. The project uses a custom VitePress theme with Vue 3 components.

Architecture ​

Core Structure ​

• VitePress Configuration: .vitepress/config.ts - site configuration with srcDir: "posts" pointing to content directory
• Custom Theme: .vitepress/theme/ - contains custom Vue components and theme implementation
• Content: posts/ - markdown content files that VitePress transforms into pages
• Styling: Tailwind CSS v4 integrated via Vite plugin (@tailwindcss/vite)

Theme Architecture ​

The custom theme (/.vitepress/theme/index.ts:1) follows VitePress theme structure:

• Layout.vue: Main layout component that uses a flex-based layout (sidebar + main content area)
• Sidebar.vue: Fixed sidebar component (currently placeholder)
• Profile.vue: Profile component (currently unused/placeholder)
• style.css: Global styles importing Tailwind CSS v4 via @import "tailwindcss"

Key Integration Points ​

• Tailwind Integration: Tailwind CSS v4 is integrated directly in .vitepress/config.ts via the @tailwindcss/vite plugin (no separate vite.config.ts exists)
• Theme Registration: .vitepress/theme/index.ts exports the custom Layout component and theme configuration
• Runtime API: Components use VitePress's useData() composable for accessing site data and frontmatter
• Build Output: Production builds output to .vitepress/dist/, cache files are stored in .vitepress/cache/

Development Commands ​

Start Development Server ​

npm run blog:dev

Starts VitePress dev server with hot reload.

Build for Production ​

npm run blog:build

Builds static site for production deployment.

Preview Production Build ​

npm run blog:preview

Previews the production build locally.

Technology Stack ​

• VitePress: v2.0.0-alpha.12 (Static site generator)
• Tailwind CSS: v4.1.15 (Utility-first CSS framework)
• Vue 3: Provided by VitePress for component development
• TypeScript: Used for configuration and components (.ts and .vue with <script setup lang="ts">)

Development Notes ​

Custom Theme Development ​

The project uses a fully custom VitePress theme rather than the default theme. When modifying the theme:

• Layout changes should be made in .vitepress/theme/Layout.vue
• Component structure currently uses Tailwind utility classes for styling
• Theme uses VitePress's runtime API (useData()) to access site configuration and frontmatter
• Important: The current Layout.vue contains hardcoded blog content and does NOT use VitePress's <Content /> component to render markdown. This is an intentional design choice for a fully custom layout

Tailwind CSS v4 Integration ​

Tailwind is integrated via the VitePress config (/.vitepress/config.ts:11) using the @tailwindcss/vite plugin. The theme stylesheet (/.vitepress/theme/style.css:1) imports Tailwind and explicitly sources files from the entire project directory using the @source directive to ensure all Vue components and markdown files are scanned for utility classes.

Content Management ​

• All markdown content lives in posts/ directory (configured via srcDir: "posts" in .vitepress/config.ts)
• VitePress automatically generates routes based on file structure in this directory
• Frontmatter can be used in markdown files to pass metadata to components
• Default example files: api-examples.md, markdown-examples.md, and index.md

Project Structure ​

.
├── .vitepress/
│   ├── cache/          # Build cache (git-ignored)
│   ├── dist/           # Production build output (git-ignored)
│   ├── theme/          # Custom theme components
│   │   ├── Layout.vue  # Main layout (hardcoded content)
│   │   ├── Sidebar.vue # Sidebar component
│   │   ├── Profile.vue # Profile component
│   │   ├── index.ts    # Theme entry point
│   │   └── style.css   # Tailwind imports
│   └── config.ts       # VitePress + Tailwind config
├── posts/              # Markdown content directory
└── package.json        # Dependencies and scripts