From 0679f1b80984f42ce8b9b59a5d536df0827791f1 Mon Sep 17 00:00:00 2001 From: Claude Date: Sun, 7 Dec 2025 16:41:52 +0000 Subject: [PATCH] Add comprehensive CLAUDE.md documentation for AI assistants This documentation provides: - Complete project overview and tech stack details - Directory structure explanation - Development workflows and commands - Content management guidelines for blog posts - Code conventions and best practices - Deployment process documentation - NixOS server configuration guide - Troubleshooting tips and common tasks --- CLAUDE.md | 376 ++++++++++++++++++++++++++++++++++++++++++++++++++++++ 1 file changed, 376 insertions(+) create mode 100644 CLAUDE.md diff --git a/CLAUDE.md b/CLAUDE.md new file mode 100644 index 0000000..2ab2305 --- /dev/null +++ b/CLAUDE.md @@ -0,0 +1,376 @@ +# CLAUDE.md - AI Assistant Guide for thiloho.github.io + +This document provides comprehensive guidance for AI assistants working on this codebase. It covers the project structure, development workflows, and key conventions to follow. + +## Project Overview + +This is the source code for **thilohohlt.com**, a personal website built with the Astro web framework. The repository also includes Nix configuration files for self-hosted services and server deployment. + +**Live Site**: https://thilohohlt.com +**Tech Stack**: Astro 5.14.6, Tailwind CSS 4.1.14, TypeScript, Markdown +**Deployment**: GitHub Pages (automated via GitHub Actions) + +## Directory Structure + +``` +thiloho.github.io/ +├── .github/ +│ └── workflows/ +│ └── deploy.yml # GitHub Actions deployment workflow +├── public/ # Static assets (served as-is) +│ ├── fonts/ # Custom font files (Styrene, Tiempos) +│ ├── favicon.ico +│ ├── CNAME # Custom domain configuration +│ └── site.webmanifest +├── server/ # NixOS server configuration +│ ├── default.nix +│ └── hardware-configuration.nix +├── src/ +│ ├── components/ # Reusable Astro components +│ │ ├── Button.astro +│ │ ├── Date.astro +│ │ ├── Footer.astro +│ │ ├── Head.astro +│ │ ├── Header.astro +│ │ ├── Icon.astro +│ │ ├── Nav.astro +│ │ ├── TableOfContents.astro +│ │ └── Track.astro +│ ├── content/ # Content collections +│ │ ├── blog/ # Blog post markdown files +│ │ │ ├── custom-email-domain/ +│ │ │ ├── e2e-testing-spring-boot-applications/ +│ │ │ ├── nixos-with-ext4-and-luks/ +│ │ │ └── privacy-focused-operating-systems/ +│ │ └── tracks.json # Music tracks data +│ ├── layouts/ +│ │ └── PageLayout.astro # Main page layout +│ ├── pages/ # Routes (file-based routing) +│ │ ├── blog/ +│ │ │ ├── [slug].astro # Dynamic blog post pages +│ │ │ └── index.astro # Blog listing page +│ │ ├── 404.astro +│ │ ├── index.astro # Homepage +│ │ ├── legal-disclosure.astro +│ │ ├── robots.txt.ts +│ │ ├── rss.xml.ts # RSS feed +│ │ ├── services.astro +│ │ └── tracks.astro +│ ├── styles/ +│ │ └── global.css # Global styles and font definitions +│ └── content.config.ts # Content collections schema +├── astro.config.ts # Astro configuration +├── flake.nix # Nix flake configuration +├── flake.lock # Nix flake lock file +├── package.json # Node.js dependencies and scripts +├── package-lock.json +├── tsconfig.json # TypeScript configuration +└── .prettierrc # Prettier configuration +``` + +## Tech Stack Details + +### Core Framework +- **Astro 5.14.6**: Static site generator with component islands architecture +- **TypeScript**: Strict mode enabled (`extends: "astro/tsconfigs/strict"`) +- **Node.js**: ES Modules (`"type": "module"`) + +### Styling +- **Tailwind CSS 4.1.14**: Utility-first CSS framework +- **@tailwindcss/typography**: Typography plugin for prose content +- **Custom Fonts**: + - **Styrene A**: Sans-serif font for headings (weights: 100-900) + - **Styrene B**: Monospace font for code (weights: 100-900) + - **Tiempos Text**: Serif font for body text (weights: 400-700) + - **Tiempos Fine**: Serif variant (weights: 300-900) + - **Tiempos Headline**: Serif variant for headlines (weights: 300-900) + +### Markdown Processing +- **markdown-it**: Markdown parser +- **rehype-slug**: Automatically add IDs to headings +- **rehype-autolink-headings**: Make headings linkable (wrap behavior) +- **Custom rehype plugin**: `rehypeWrapTables` wraps tables in scrollable divs +- **Syntax highlighting**: GitHub Dark theme via Shiki + +### Content Management +- **Content Collections**: Defined in `src/content.config.ts` + - **blog**: Markdown files with frontmatter (title, description, pubDate, modDate) + - **tracks**: JSON file with music track data (id, title, youtubeLink, artist, album) + +### Integrations +- **@astrojs/sitemap**: Automatic sitemap generation +- **@astrojs/rss**: RSS feed support +- **sanitize-html**: HTML sanitization + +### Development Tools +- **Prettier**: Code formatting with plugins for Astro and Tailwind +- **Nix**: Development environment and server deployment + +## Development Workflows + +### Essential Commands + +```bash +# Development +npm run dev # Start Astro dev server (http://localhost:4321) +npm run build # Build for production +npm run preview # Preview production build +npm run format # Format code with Prettier + +# Nix (if using Nix) +nix develop # Enter dev shell (includes nixd, nixfmt) +nix run .#eval-server # Validate NixOS configuration +nix run .#deploy-server # Deploy to remote NixOS server +``` + +### Starting Development +1. Install dependencies: `npm install` +2. Start dev server: `npm run dev` +3. Open browser to `http://localhost:4321` + +### Building for Production +1. Run build: `npm run build` +2. Output is in `dist/` directory +3. Preview with: `npm run preview` + +## Content Management + +### Creating Blog Posts + +Blog posts are stored in `src/content/blog/` with each post in its own directory containing a `index.md` file. + +**Required frontmatter structure**: +```markdown +--- +title: "Your Post Title" +description: "A brief description of the post" +pubDate: "2025-01-04" +modDate: "2025-04-27" # Optional +--- + +## Your Content Here + +Write your blog post content using Markdown... +``` + +**Blog post conventions**: +- Each post lives in its own directory: `src/content/blog/post-slug/index.md` +- Use kebab-case for directory names (e.g., `nixos-with-ext4-and-luks`) +- Include high-quality images in the same directory as the post +- Dates in `YYYY-MM-DD` format +- `modDate` is optional (use when updating existing posts) + +### Adding Music Tracks + +Edit `src/content/tracks.json` following this schema: +```json +{ + "id": 1, + "title": "Track Title", + "youtubeLink": "https://youtube.com/...", + "artist": "Artist Name", + "album": "Album Name" +} +``` + +## Code Conventions + +### TypeScript +- Use strict TypeScript configuration +- Define types explicitly where needed +- Leverage Astro's built-in type system + +### Astro Components +- Use `.astro` file extension +- Component names should be PascalCase (e.g., `TableOfContents.astro`) +- Place reusable components in `src/components/` +- Use layouts for page templates (`src/layouts/`) + +### Styling +- Use Tailwind utility classes for styling +- Custom styles go in `src/styles/global.css` +- Follow the custom variant pattern: `@custom-variant dark (&:where(.dark, .dark *))` +- Apply responsive design with Tailwind's breakpoint prefixes + +### Formatting +- Always run `npm run format` before committing +- Prettier automatically formats: + - Astro files (via `prettier-plugin-astro`) + - Tailwind classes (via `prettier-plugin-tailwindcss`) +- Configuration is in `.prettierrc` + +### File Naming +- Components: PascalCase (e.g., `Header.astro`) +- Pages: kebab-case or descriptive names (e.g., `index.astro`, `legal-disclosure.astro`) +- Content directories: kebab-case (e.g., `nixos-with-ext4-and-luks`) +- Configuration files: standard names (e.g., `astro.config.ts`) + +## Deployment + +### GitHub Pages +- **Automatic deployment** on push to `main` branch +- Workflow file: `.github/workflows/deploy.yml` +- Uses official Astro GitHub Action (`withastro/action@v3`) +- Custom domain: thilohohlt.com (configured via `public/CNAME`) + +### Deployment Process +1. Push to `main` branch +2. GitHub Actions builds the site +3. Astro generates static files +4. Deploy to GitHub Pages +5. Site available at https://thilohohlt.com + +### Build Configuration +- Site URL: `https://thilohohlt.com` (defined in `astro.config.ts`) +- Prefetch: All links are prefetched (`prefetchAll: true`) +- Output: Static HTML/CSS/JS in `dist/` + +## NixOS Server Configuration + +This repository includes Nix configuration for self-hosted services listed at https://thilohohlt.com/services. + +### Nix Files +- `flake.nix`: Main Nix flake configuration +- `flake.lock`: Dependency lock file +- `server/default.nix`: NixOS system configuration +- `server/hardware-configuration.nix`: Hardware-specific settings + +### Nix Workflows +```bash +# Enter development shell (provides nixd, nixfmt) +nix develop + +# Validate server configuration +nix run .#eval-server + +# Deploy to remote server +nix run .#deploy-server +# This will: +# 1. Evaluate the configuration +# 2. Connect to the remote server (91.98.171.83) +# 3. Build and switch to new configuration +``` + +### IDE Support for Nix +For NixOS option completions, use the `jnoortheen.nix-ide` VSCode extension with these settings: +```json +{ + "nix.enableLanguageServer": true, + "nix.serverPath": "nil", + "nix.serverSettings": { + "nixd": { + "formatting": { + "command": ["nixfmt"] + } + } + } +} +``` + +## Key Features to Preserve + +### Custom Rehype Plugins +The `rehypeWrapTables` plugin wraps tables in scrollable divs for responsive design: +```typescript +const rehypeWrapTables = () => { + // Wraps tables in div.overflow-x-auto.max-w-full + // Ensures tables are scrollable on mobile +} +``` + +### Markdown Configuration +- Syntax highlighting: GitHub Dark theme +- Auto-generated heading IDs (via rehype-slug) +- Clickable headings that wrap content (via rehype-autolink-headings) +- Tables wrapped for horizontal scrolling + +### Font Loading +- All fonts use `font-display: swap` for performance +- Fonts are self-hosted in `/public/fonts/` +- Font families defined in `src/styles/global.css` + +## Important Notes for AI Assistants + +### When Making Changes + +1. **Always read files before editing**: Use the Read tool before making changes to understand existing code structure +2. **Preserve existing conventions**: Don't introduce new patterns unless necessary +3. **Test locally**: Encourage running `npm run dev` to test changes +4. **Format before committing**: Run `npm run format` to ensure consistent code style +5. **Respect content structure**: Blog posts must have proper frontmatter and directory structure +6. **Don't over-engineer**: Keep solutions simple and focused on the requested changes + +### Common Tasks + +**Adding a new blog post**: +1. Create directory in `src/content/blog/` with kebab-case name +2. Add `index.md` with proper frontmatter +3. Write content using Markdown +4. Test with `npm run dev` + +**Modifying a component**: +1. Read the component file first +2. Understand its usage across the site +3. Make targeted changes +4. Preserve existing styling patterns +5. Format with Prettier + +**Updating styles**: +1. Check `src/styles/global.css` for existing patterns +2. Use Tailwind utilities when possible +3. Add custom CSS only when necessary +4. Maintain dark mode support via custom variant + +**Working with NixOS configuration**: +1. Changes to server config go in `server/` directory +2. Always validate with `nix run .#eval-server` before deploying +3. Be cautious with production server changes +4. Test locally when possible + +### Things to Avoid + +- ❌ Don't create documentation files unless explicitly requested +- ❌ Don't add unnecessary comments or docstrings +- ❌ Don't refactor code that isn't related to the task +- ❌ Don't add dependencies without good reason +- ❌ Don't modify font files or licenses in `/public/fonts/` +- ❌ Don't change the deployment workflow without understanding implications +- ❌ Don't edit generated files in `.astro/` or `dist/` + +## Troubleshooting + +### Build Fails +- Check `astro.config.ts` for syntax errors +- Verify all blog posts have required frontmatter +- Ensure TypeScript types are correct +- Run `npm install` to update dependencies + +### Dev Server Issues +- Port 4321 might be in use (kill the process or use `--port` flag) +- Clear `.astro/` directory and rebuild: `rm -rf .astro && npm run dev` +- Check for TypeScript errors in components + +### Styling Problems +- Run `npm run format` to fix Tailwind class ordering +- Check global.css for font loading issues +- Verify Tailwind plugin is loaded in Vite config + +### Content Not Appearing +- Verify content collection schema in `src/content.config.ts` +- Check frontmatter matches schema requirements +- Ensure file paths are correct +- Restart dev server after adding new content files + +## Resources + +- **Astro Docs**: https://docs.astro.build/ +- **Tailwind CSS Docs**: https://tailwindcss.com/docs +- **Nix Manual**: https://nixos.org/manual/nix/stable/ +- **Site Repository**: https://github.com/thiloho/thiloho.github.io (inferred) + +## Version Info + +Last updated: 2025-12-07 +Astro version: 5.14.6 +Tailwind version: 4.1.14 +Node.js: ES Modules