# CLAUDE.md

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

## Project Overview

Foldsite is a dynamic site generator built with Python and Flask. It serves Markdown content as HTML pages using Jinja2 templates and CSS styles. The application follows a modular architecture with clear separation of concerns.

## Development Commands

### Running the Application
```bash
python main.py --config config.toml
```

### Managing Dependencies
```bash
# Install dependencies
pip install -r requirements.txt

# Or using uv (if available)
uv pip install -r requirements.txt

# Update dependencies from pyproject.toml
uv pip compile pyproject.toml -o requirements.txt
```

### Docker Development
```bash
# Build Docker image
docker build -t foldsite .

# Run with Docker Compose
docker-compose up
```

## Architecture Overview

### Core Components

1. **Server** (`src/server/server.py`): Flask application wrapped with Gunicorn for production serving. Handles template function registration and route management.

2. **Configuration** (`src/config/`): TOML-based configuration system managing paths, server settings, and application options.

3. **Route Management** (`src/routes/routes.py`): Handles URL routing with path validation and security. Serves content, styles, and static files with thumbnail generation for images.

4. **Rendering System** (`src/rendering/`):
   - `renderer.py`: Main page rendering logic
   - `markdown.py`: Markdown to HTML conversion with frontmatter support
   - `helpers.py`: Template helper functions for content discovery
   - `image.py`: Thumbnail generation for images

5. **File Manager** (`src/server/file_manager.py`): Optional admin interface for content management (when `admin_browser` is enabled).

### Template System

The application uses Jinja2 templates with custom helper functions:
- `get_sibling_content_files(path)`: Returns list of sibling content files
- `get_text_document_preview(path)`: Generates text document previews
- `get_sibling_content_folders(path)`: Returns list of sibling folders
- `get_folder_contents(path)`: Retrieves folder contents as TemplateFile objects

### Directory Structure

- `src/`: Main application source code
  - `config/`: Configuration handling
  - `rendering/`: Content rendering and processing
  - `routes/`: URL routing and request handling
  - `server/`: Flask server and file management
- `docs/content/`: Site content (Markdown files)
- `docs/templates/`: Jinja2 HTML templates
- `docs/styles/`: CSS stylesheets
- `config.toml`: Application configuration

### Configuration

The application uses TOML configuration with sections for:
- `[paths]`: Directory paths for content, templates, and styles
- `[server]`: Server settings including address, port, debug mode, and admin options

### Security Features

- Path traversal protection in route handlers
- Hidden file/folder access restrictions
- Configurable admin interface with password protection
- Input validation and sanitization for file paths