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

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

astro.config.ts

@@ -4,6 +4,54 @@ import sitemap from "@astrojs/sitemap";
 import rehypeAutolinkHeadings from "rehype-autolink-headings";
 import rehypeSlug from "rehype-slug";
 
+type RehypeNode = {
+  type: string;
+  tagName?: string;
+  children?: RehypeNode[];
+  properties?: {
+    [key: string]: unknown;
+    className?: string[];
+  };
+};
+
+type RehypeParent = RehypeNode & {
+  children: RehypeNode[];
+};
+
+type RehypeRoot = RehypeParent;
+
+const rehypeWrapTables = () => {
+  const visit = (node: RehypeNode, parent: RehypeParent | null) => {
+    if (node.type === "element" && node.tagName === "table" && parent) {
+      const wrapper: RehypeNode = {
+        type: "element",
+        tagName: "div",
+        properties: {
+          className: ["overflow-x-auto", "max-w-full"],
+        },
+        children: [node],
+      };
+
+      const index = parent.children.indexOf(node);
+      if (index !== -1) {
+        parent.children[index] = wrapper;
+      }
+
+      return;
+    }
+
+    if (Array.isArray(node.children)) {
+      for (const child of node.children) {
+        visit(child, node as RehypeParent);
+      }
+    }
+  };
+
+  return (tree: RehypeRoot) => {
+    visit(tree, null);
+  };
+};
+
 export default defineConfig({
   site: "https://thilohohlt.com",
 
@@ -27,6 +75,7 @@ export default defineConfig({
           behavior: "wrap",
         },
       ],
+      rehypeWrapTables,
     ],
   },
 

src/content/index.md

@@ -18,8 +18,11 @@ I am a software developer from Germany who is passionate about building high qua
 ## Software
 
 - [Arch Linux](https://archlinux.org)
-- [KDE Plasma](https://kde.org/plasma-desktop)
-- [Visual Studio Code](https://code.visualstudio.com)
 - [Firefox Developer Edition](https://www.mozilla.org/en-US/firefox/developer)
-- [Tuta Mail](https://tuta.com)
+- [IntelliJ](https://www.jetbrains.com/idea)
+- [KDE Plasma](https://kde.org/plasma-desktop)
+- [LocalSend](https://localsend.org)
 - [Mullvad VPN](https://mullvad.net)
+- [qBittorrent](https://www.qbittorrent.org)
+- [Tuta Mail](https://tuta.com)
+- [Visual Studio Code](https://code.visualstudio.com)

src/layouts/PageLayout.astro

@@ -22,7 +22,7 @@ const { title, description, pubDate, modDate, slug } = Astro.props;
     <Header {title} {pubDate} {modDate} {slug} />
     <main class="flex-1 bg-white dark:bg-neutral-800">
       <div
-        class={`relative prose prose-neutral dark:prose-invert mx-auto px-4 ${pubDate ? "pt-0" : "pt-8"} pb-16 ${Astro.originPathname === "/" ? "prose-headings:scroll-mt-12" : "prose-headings:scroll-mt-24 lg:prose-headings:scroll-mt-16"} prose-h1:font-bold prose-pre:!bg-neutral-700 prose-a:font-normal prose-a:not-in-prose-headings:text-blue-800 prose-a:not-in-prose-headings:dark:text-blue-300 prose-a:hover:no-underline prose-a:active:bg-neutral-200 prose-a:active:dark:bg-neutral-700 prose-a:in-prose-headings:font-bold prose-a:in-prose-headings:decoration-2 prose-a:in-prose-headings:no-underline prose-a:in-prose-headings:hover:underline`}
+        class={`relative prose prose-neutral dark:prose-invert mx-auto px-4 ${pubDate ? "pt-0" : "pt-8"} pb-16 ${Astro.originPathname === "/" ? "prose-headings:scroll-mt-12" : "prose-headings:scroll-mt-24 lg:prose-headings:scroll-mt-16"} prose-table:text-base prose-h1:font-bold prose-pre:!bg-neutral-700 prose-a:font-normal prose-a:not-in-prose-headings:text-blue-800 prose-a:not-in-prose-headings:dark:text-blue-300 prose-a:hover:no-underline prose-a:active:bg-neutral-200 prose-a:active:dark:bg-neutral-700 prose-a:in-prose-headings:font-bold prose-a:in-prose-headings:decoration-2 prose-a:in-prose-headings:no-underline prose-a:in-prose-headings:hover:underline`}
       >
         <slot />
       </div>

src/styles/global.css

@@ -27,6 +27,18 @@
   mark {
     @apply bg-neutral-200 text-current dark:bg-neutral-600;
   }
+
+  #software + ul {
+    @apply flex flex-wrap gap-4 !p-0;
+  }
+
+  #software + ul > li {
+    @apply !m-0 list-none !p-0;
+  }
+
+  #software + ul > li a {
+    @apply border border-neutral-300 px-2 py-1 dark:border-neutral-600;
+  }
 }
 
 /* Styrene A Font Family */