thiloho.github.io/CLAUDE.md

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

# 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:

---
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:

{
  "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

# 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:

{
  "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:

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