foldsite/CLAUDE.md

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

python main.py --config config.toml

Managing Dependencies

# 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

# 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