# CLAUDE.md

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

## Architecture Overview

This is a Hugo static site for the Foss Cat blog (fosscat.com), using the Gokarna theme. The site
includes blog posts, TILs (Today I Learned), and project pages.

Key architectural components:

- **Hugo framework**: Static site generator with content in Markdown
- **Gokarna theme**: Git submodule theme providing the site's design
- **Content structure**: Posts in `content/posts/`, TILs in `content/tils/`, projects in `content/projects/`
- **Static assets**: Images and other assets in `static/` directory
- **Custom layouts**: Overrides in `layouts/` for TILs and other content types
- **Configuration**: Main site config in `config.toml`

## Development Commands

### Environment Setup

```bash
# Initialize git submodules (theme)
git submodule init
git submodule update

# Enter Nix development environment (if using Nix)
nix develop
```

### Building and Development

```bash
# Start development server with live reload
hugo server

# Build static site for production
hugo

# Build with drafts included
hugo --buildDrafts
```

### Linting and Quality Checks

```bash
# Lint markdown files
markdownlint content/**/*.md

# Format markdown files
prettier --write content/**/*.md

# Spell check (requires aspell with English dictionary)
aspell check --mode=markdown --lang=en --personal=./.aspell.en.pws [filename.md]
```

### Git Hooks

- Pre-commit hooks automatically installed via `scripts/install_hooks.sh`
- Hooks run markdown linting and spell checking on staged `.md` files
- Personal dictionary in `.aspell.en.pws` for spell checking

## Content Management

### Creating New Content

```bash
# Create new blog post
hugo new posts/post-title.md

# Create new TIL
hugo new tils/til-title.md

# Create new project
hugo new projects/project-name.md
```

### TILs (Today I Learned)

- Custom archetype in `archetypes/tils.md`
- Custom layouts in `layouts/tils/` for list and single views
- Accessible via `/tils/` URL path

## Site Configuration

- **Base URL**: <https://fosscat.com/>
- **Theme**: Gokarna (git submodule)
- **Syntax highlighting**: catppuccin-frappe style
- **Content language**: English (en-us)
- **Social icons**: Configured for Gitea, Twitch, RSS
- **Navigation menu**: Defined in `config.toml`

## Development Environment

This repository uses Nix flakes for reproducible development environment including:

- Hugo static site generator
- Marksman (Markdown LSP)
- Prettier (code formatter)
- markdownlint-cli
- aspell with English dictionaries

## Quality Assurance

- Markdown linting enforced via `.markdownlint.jsonc` configuration
- Spell checking with personal dictionary support
- Pre-commit hooks prevent commits with linting/spelling errors
- Use `git commit --no-verify` to bypass hooks if needed