87 lines
3.0 KiB
Markdown
87 lines
3.0 KiB
Markdown
# 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
|