mirror of
https://github.com/thiloho/thiloho.github.io.git
synced 2025-12-23 14:33:36 +01:00
Compare commits
5 Commits
822fc4d0ca
...
main
| Author | SHA1 | Date | |
|---|---|---|---|
|
bfad268f1f | ||
|
|
70a0434236 | ||
|
|
323ec46753 | ||
| f270dba48f | |||
|
|
0679f1b809 |
411
CLAUDE.md
Normal file
411
CLAUDE.md
Normal file
@@ -0,0 +1,411 @@
|
||||
# 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
|
||||
@@ -19,8 +19,8 @@ const thumbnail = `https://img.youtube.com/vi/${videoId}/maxresdefault.jpg`;
|
||||
|
||||
<a
|
||||
href={youtubeLink}
|
||||
class="relative mt-4 block p-4 duration-300 after:absolute after:inset-0 after:z-0 after:bg-[rgba(255,255,255,0.75)] after:content-[''] first:mt-0 hover:scale-105 dark:after:bg-[rgba(38,38,38,0.75)]"
|
||||
style={`word-break: break-word; background-image: url('${thumbnail}'); background-size: cover; background-position: center;`}
|
||||
class="relative mt-4 block bg-cover bg-center p-4 duration-300 after:absolute after:inset-0 after:z-0 after:bg-[rgba(255,255,255,0.75)] after:content-[''] first:mt-0 hover:scale-105 dark:after:bg-[rgba(38,38,38,0.75)]"
|
||||
style={`word-break: break-word; background-image: url('${thumbnail}')`}
|
||||
>
|
||||
<div
|
||||
class="relative z-10 flex flex-col gap-2 text-neutral-900 dark:text-white"
|
||||
|
||||
File diff suppressed because it is too large
Load Diff
@@ -7,10 +7,20 @@ const tracks = await getCollection("tracks");
|
||||
---
|
||||
|
||||
<PageLayout
|
||||
title="Tracks"
|
||||
title={`Tracks (${tracks.length})`}
|
||||
description="My entire music playlist. It contains all kinds of songs."
|
||||
>
|
||||
<div class="not-prose">
|
||||
<div id="loading-indicator" class="flex flex-col items-center gap-2">
|
||||
<div
|
||||
class="h-8 w-8 animate-spin rounded-full border-4 border-neutral-300 border-t-neutral-900 dark:border-neutral-600 dark:border-t-white"
|
||||
>
|
||||
</div>
|
||||
<span
|
||||
id="loading-percentage"
|
||||
class="text-sm text-neutral-900 dark:text-white">0%</span
|
||||
>
|
||||
</div>
|
||||
<div id="tracks-container" class="not-prose hidden">
|
||||
{
|
||||
tracks.map(({ data: { title, artist, album, youtubeLink } }, index) => (
|
||||
<Track {title} {artist} {album} {youtubeLink} index={++index} />
|
||||
@@ -18,3 +28,40 @@ const tracks = await getCollection("tracks");
|
||||
}
|
||||
</div>
|
||||
</PageLayout>
|
||||
|
||||
<script is:inline define:vars={{ tracks }}>
|
||||
const loadThumbnails = async () => {
|
||||
const thumbnailUrls = tracks.map(({ data: { youtubeLink } }) => {
|
||||
const videoId = youtubeLink.split("v=")[1];
|
||||
return `https://img.youtube.com/vi/${videoId}/maxresdefault.jpg`;
|
||||
});
|
||||
|
||||
let loadedCount = 0;
|
||||
const total = thumbnailUrls.length;
|
||||
const percentageEl = document.getElementById("loading-percentage");
|
||||
|
||||
const preloadImages = thumbnailUrls.map((url) => {
|
||||
return new Promise((resolve) => {
|
||||
const img = new Image();
|
||||
const handleComplete = () => {
|
||||
loadedCount++;
|
||||
const percentage = Math.round((loadedCount / total) * 100);
|
||||
percentageEl.textContent = `${percentage}%`;
|
||||
resolve();
|
||||
};
|
||||
|
||||
img.addEventListener("load", handleComplete, { once: true });
|
||||
img.addEventListener("error", handleComplete, { once: true });
|
||||
img.src = url;
|
||||
});
|
||||
});
|
||||
|
||||
await Promise.all(preloadImages);
|
||||
|
||||
document.getElementById("loading-indicator").classList.add("hidden");
|
||||
document.getElementById("tracks-container").classList.remove("hidden");
|
||||
};
|
||||
|
||||
loadThumbnails();
|
||||
document.addEventListener("astro:after-swap", loadThumbnails);
|
||||
</script>
|
||||
|
||||
Reference in New Issue
Block a user