Installation Quick Start

What You Need

Git installed on your system
Python 3.9+ with pip
mintyflask-themes (will be cloned alongside)
Basic terminal knowledge

Quick Install (5 Minutes)

Complete Setup (SSG + Themes)

# Create a workspace directory
mkdir minty-workspace
cd minty-workspace

# Clone both projects to the same parent directory
git clone https://codeberg.org/contueor/mintyflask-themes.git
git clone https://codeberg.org/contueor/mintyflask-ssg.git

# Your structure should look like:
# minty-workspace/
# ├── mintyflask-themes/    # Theme and mixin system
# └── mintyflask-ssg/       # Static site generator

# Set up the SSG
cd mintyflask-ssg

# Install Python dependencies
pip install -r requirements.txt

# Create local configuration (optional)
cp config.py config_local.py

# You're ready to go!

Why both projects? mintyflask-ssg uses mintyflask-themes for its template resolution and CSS architecture. The SSG expects to find themes as a sibling directory.

Verify Installation

Check Directory Structure

cd minty-workspace
ls -la

# You should see:
# ├── mintyflask-themes/
# │   ├── mixins/
# │   ├── themes/
# │   └── ...
# └── mintyflask-ssg/
#     ├── app/
#     ├── config.py
#     ├── requirements.txt
#     └── ...

Test Flask Application

cd mintyflask-ssg

# Run development server
python run.py

# Should show:
# 🔧 Starting Flask application with development profile
# * Running on http://0.0.0.0:5000

Visit http://localhost:5000 in your browser. You should see the default theme.

Test Static Build

# Generate static site
python freeze.py

# Should show:
# INFO Starting site freeze process
# INFO Generated X URLs
# INFO Site freeze completed in Y seconds

# Check output
ls -la build/

# Should show generated HTML files and assets

What You Get

mintyflask-ssg structure:

mintyflask-ssg/
├── app/                    # Flask application
│   ├── __init__.py        # App factory
│   ├── blog/              # Blog blueprint
│   ├── docs/              # Documentation blueprint
│   ├── home/              # Home blueprint
│   ├── extensions/        # Flask extensions
│   └── api/               # API blueprint
├── config.py              # Base configuration
├── config_local.py        # Local overrides (create this)
├── requirements.txt       # Python dependencies
├── run.py                 # Development server
├── freeze.py             # Static site generator
└── data/                  # Content and configuration
    ├── markdown/          # Markdown content
    │   ├── posts/         # Blog posts
    │   ├── pages/         # Static pages
    │   └── docs/          # Documentation
    ├── yaml/              # YAML configuration
    │   ├── site.yaml      # Site configuration
    │   └── docs_nav.yaml  # Documentation navigation
    └── photos/            # Photo library (optional)
        ├── photos_original/
        └── photos_processed/

Initial Configuration

Create Local Config

Create config_local.py to override settings without modifying config.py:

# config_local.py
from config import Config

class LocalConfig(Config):
    """Local development configuration"""

    # Site information
    SITE_DESCRIPTION = "My awesome site"

    # Theme selection
    THEME_NAME = "blog"  # or "minimal", "business", etc.

    # Path configuration (if not using auto-discovery)
    # MINTY_THEMES_BASE_DIR = "/path/to/mintyflask-themes"
    # DATA_DIR = "/path/to/data"

    # Development settings
    FLASK_DEBUG = True
    ENVIRONMENT = "development"
    SHOW_DEV_NOTES = True

Configure Data Directories

mintyflask-ssg uses auto-discovery for data directories, but you can override:

# In config_local.py
class LocalConfig(Config):
    # Explicit paths (optional)
    DATA_DIR = "/absolute/path/to/data"
    FLATPAGES_ROOT = "/absolute/path/to/data/markdown"
    PHOTOS_LIBRARY_ROOT = "/absolute/path/to/data/photos/photos_original"
    PHOTOS_OUTPUT_DIR = "/absolute/path/to/data/photos/photos_processed"

Auto-discovery search order:

Config value (if set)
./data (project root)
../data (parent directory)
../../data (grandparent directory)

Common Installation Scenarios

Scenario 1: Building a Static Blog

# Set up workspace
mkdir my-blog
cd my-blog

# Clone both projects
git clone https://codeberg.org/contueor/mintyflask-themes.git
git clone https://codeberg.org/contueor/mintyflask-ssg.git

# Set up SSG
cd mintyflask-ssg
pip install -r requirements.txt

# Create content directory structure
mkdir -p data/markdown/posts
mkdir -p data/markdown/pages/en
mkdir -p data/yaml

# Create your first post
cat > data/markdown/posts/hello-world.md << 'EOF'
---
title: "Hello World"
date: 2025-11-30
status: published
category: general
tags: [first-post, introduction]
---

# Welcome to my blog!

This is my first post using mintyflask-ssg.
EOF

# Create site configuration
cat > data/yaml/site.yaml << 'EOF'
site:
  name: "My Blog"
  description: "A static blog built with mintyflask-ssg"

i18n:
  en:
    site_name: "My Blog"
    navigation:
      - nav-item:
          title: "Home"
          url: "/"
      - nav-item:
          title: "Blog"
          url: "/articles/all"
EOF

# Test in development
python run.py

# Build static site
python freeze.py

# Deploy the build/ directory

Scenario 2: Documentation Site

# Set up for documentation
cd mintyflask-ssg

# Create documentation structure
mkdir -p data/markdown/docs/my-project/getting-started
mkdir -p data/markdown/docs/my-project/user-guide

# Create index page
cat > data/markdown/docs/index.md << 'EOF'
---
title: "Documentation"
---

# Welcome to the Documentation

Browse the documentation for different projects.
EOF

# Create documentation navigation
cat > data/yaml/docs_nav.yaml << 'EOF'
projects:
  - name: "My Project"
    description: "Documentation for My Project"
    sections:
      - title: "Getting Started"
        pages:
          - title: "Introduction"
            path: "my-project/getting-started/introduction"
          - title: "Installation"
            path: "my-project/getting-started/installation"
      - title: "User Guide"
        pages:
          - title: "Basic Usage"
            path: "my-project/user-guide/basic-usage"
EOF

# Create your first doc
cat > data/markdown/docs/my-project/getting-started/introduction.md << 'EOF'
---
title: "Introduction"
---

# Introduction to My Project

Welcome to the documentation!
EOF

# Test
python run.py
# Visit http://localhost:5000/docs/

Scenario 3: Photo Gallery Site

# Set up photo directories
cd mintyflask-ssg
mkdir -p data/photos/photos_original/vacation-2024
mkdir -p data/photos/photos_processed

# Add photos to photos_original/vacation-2024/
# (Copy your JPG files here)

# Create gallery metadata
cat > data/photos/photos_original/vacation-2024/gallery.yaml << 'EOF'
title: "Summer Vacation 2024"
description: "Our amazing summer holiday"
featured: true
sort_order: 1
tags:
  - vacation
  - summer
  - 2024
author: "Your Name"
location: "Somewhere Beautiful"
EOF

# Process photos
flask photos process

# Create a page with gallery
cat > data/markdown/pages/en/galleries.md << 'EOF'
---
title: "Photo Galleries"
---

# Photo Galleries

<!--GALLERY_INDEX_PLACEHOLDER_457D19D7A476-->
EOF

# Test
python run.py

Directory Structure Explained

Application Structure

mintyflask-ssg/
│
├── app/                      # Flask application
│   ├── __init__.py          # App factory with blueprint registration
│   ├── blog/                # Blog blueprint
│   │   ├── __init__.py
│   │   ├── helpers.py       # Blog helper functions
│   │   └── routes/          # Organised route modules
│   │       ├── content.py   # Post display and listing
│   │       ├── taxonomy.py  # Categories, tags, archives
│   │       ├── admin.py     # Drafts, review
│   │       └── utils.py     # CSS, feeds
│   ├── docs/                # Documentation blueprint
│   ├── home/                # Home blueprint
│   ├── api/                 # API blueprint
│   └── extensions/          # Flask extensions
│       ├── photos/          # Photo processing
│       └── markdown/        # Markdown rendering
│
├── data/                    # Content and configuration
│   ├── markdown/           # Markdown content
│   │   ├── posts/          # Blog posts
│   │   ├── pages/          # Static pages
│   │   │   ├── en/         # English pages
│   │   │   └── fr/         # French pages (optional)
│   │   └── docs/           # Documentation
│   ├── yaml/               # YAML configuration
│   │   ├── site.yaml       # Site config and i18n
│   │   └── docs_nav.yaml   # Documentation navigation
│   └── photos/             # Photo library (optional)
│       ├── photos_original/     # Original photos
│       └── photos_processed/    # Processed outputs
│
├── config.py               # Base configuration
├── config_local.py         # Local overrides (create this)
├── requirements.txt        # Python dependencies
├── run.py                 # Development server
├── freeze.py              # Static site generator
└── build/                 # Generated static site (created by freeze.py)

Content Organisation

data/markdown/
├── posts/                 # Blog posts
│   ├── 2024-11-30-hello-world.md
│   ├── 2024-12-01-second-post.md
│   └── ...
├── pages/                 # Static pages
│   ├── en/
│   │   ├── about.md
│   │   ├── contact.md
│   │   └── ...
│   └── fr/               # French translations (optional)
│       ├── about.md
│       └── ...
└── docs/                  # Documentation
    ├── index.md          # Documentation home
    ├── project-a/
    │   ├── getting-started/
    │   │   └── introduction.md
    │   └── user-guide/
    │       └── basics.md
    └── project-b/
        └── ...

Python Dependencies

Core Requirements

Flask>=3.0.2              # Web framework
Flask-FlatPages>=0.8.2    # Markdown content
Frozen-Flask              # Static site generation
Jinja2>=3.1.3            # Template engine
Werkzeug>=3.0.1          # WSGI utilities

Markdown Processing

Markdown>=3.4.0           # Markdown parser
markdown-it-py            # CommonMark renderer (optional)
Pygments                  # Syntax highlighting
pymdown-extensions        # Markdown extensions

Photo Processing (Optional)

Pillow>=9.0.0            # Image processing
piexif>=1.1.3            # EXIF metadata

Install All Dependencies

pip install -r requirements.txt

Alternate Installation Methods

Using Virtual Environment (Recommended)

# Create workspace
mkdir minty-workspace
cd minty-workspace

# Clone projects
git clone https://codeberg.org/contueor/mintyflask-themes.git
git clone https://codeberg.org/contueor/mintyflask-ssg.git

# Set up virtual environment
cd mintyflask-ssg
python -m venv venv

# Activate virtual environment
# On Linux/macOS:
source venv/bin/activate
# On Windows:
venv\Scripts\activate

# Install dependencies
pip install -r requirements.txt

Using Docker (Future)

# Docker support coming soon
# docker-compose up

Download as ZIP (Not Recommended)

# Download and extract
wget https://codeberg.org/contueor/mintyflask-ssg/archive/main.zip
wget https://codeberg.org/contueor/mintyflask-themes/archive/main.zip

unzip mintyflask-ssg-main.zip
unzip mintyflask-themes-main.zip

# Rename to remove -main suffix
mv mintyflask-ssg-main mintyflask-ssg
mv mintyflask-themes-main mintyflask-themes

# Install dependencies
cd mintyflask-ssg
pip install -r requirements.txt

Why not recommended? You lose Git history and can't easily pull updates.

Updating Your Installation

Pull Latest Changes

cd minty-workspace

# Update SSG
cd mintyflask-ssg
git pull origin main
pip install -r requirements.txt  # Update dependencies

# Update themes
cd ../mintyflask-themes
git pull origin main

Update Dependencies Only

cd mintyflask-ssg
pip install --upgrade -r requirements.txt

Check for Breaking Changes

# View changelog
git log --oneline --since="1 month ago"

# View configuration changes
git diff HEAD~10..HEAD config.py

Common Issues

Issue: "ModuleNotFoundError: No module named 'flask'"

Solution: Install Python dependencies:

cd mintyflask-ssg
pip install -r requirements.txt

Issue: mintyflask-ssg can't find themes

Problem: Projects not in the same parent directory.

Solution:

# Check your directory structure
cd minty-workspace
ls -la

# Should show both directories:
# mintyflask-themes/
# mintyflask-ssg/

# If not, move them:
mv /path/to/mintyflask-themes .
mv /path/to/mintyflask-ssg .

Issue: Template not found errors

Solution: Check theme configuration:

# In config_local.py
class LocalConfig(Config):
    THEME_NAME = "blog"  # Must match a directory in themes/

    # Optional: Explicit path
    MINTY_THEMES_BASE_DIR = "/absolute/path/to/mintyflask-themes"

Issue: Static files (CSS) not loading

Problem: Theme static files not found.

Solution:

# Check theme static directory exists
ls -la ../mintyflask-themes/themes/blog/static/css/

# Rebuild CSS if needed (in theme directory)
cd ../mintyflask-themes/themes/blog
npm run build  # If using Tailwind build process

# Or check Flask is serving correctly
python run.py
# Visit http://localhost:5000/theme/blog/static/css/output.css

Issue: Photos not processing

Solution:

# Install photo dependencies
pip install Pillow piexif

# Check photo directories exist
mkdir -p data/photos/photos_original
mkdir -p data/photos/photos_processed

# Process photos manually
flask photos process

Issue: Permission denied

Solution:

# Fix permissions
chmod -R 755 mintyflask-ssg
chmod -R 755 mintyflask-themes

# If using virtual environment
chmod -R 755 venv

Configuration Profiles

Run with different logging profiles:

# Development (default)
python run.py --config development

# Photo debugging
python run.py --config photos

# Route debugging
python run.py --config routes

# Blog debugging
python run.py --config blog

# Quiet mode
python run.py --config quiet

# Production
python run.py --config production

What's Next?

After installation:

Create your first post - Add a markdown file to data/markdown/posts/
Customise configuration - Edit data/yaml/site.yaml
Choose a theme - Set THEME_NAME in config_local.py
Build static site - Run python freeze.py

Development Installation

For contributors and developers:

# Clone with development branch
git clone https://codeberg.org/contueor/mintyflask-ssg.git
cd mintyflask-ssg
git checkout -b feature/my-feature

# Set up development environment
python -m venv venv
source venv/bin/activate
pip install -r requirements.txt

# Install development tools (if exists)
pip install -r requirements-dev.txt

# Make changes and test
python run.py --config all  # Full debug logging

# Run tests (if available)
pytest

# Commit and push
git add .
git commit -m "Add feature: my-feature"
git push origin feature/my-feature

Troubleshooting

Can't clone repository

Check:

Is Git installed? Run git --version
Do you have internet connectivity?
Is the repository URL correct?
Do you have permissions (for private repos)?

Python version issues

# Check Python version
python --version  # Should be 3.9+

# Use specific version
python3.9 -m venv venv
# or
python3.11 -m venv venv

Dependencies won't install

# Upgrade pip first
pip install --upgrade pip

# Try installing one by one
pip install Flask
pip install Flask-FlatPages
pip install Frozen-Flask

# Check for system dependencies (for Pillow)
# Ubuntu/Debian:
sudo apt-get install python3-dev libjpeg-dev zlib1g-dev
# macOS:
brew install libjpeg

Need to start fresh

# Remove virtual environment
rm -rf venv

# Remove cloned directories
cd ..
rm -rf mintyflask-ssg mintyflask-themes

# Clone and reinstall
git clone https://codeberg.org/contueor/mintyflask-themes.git
git clone https://codeberg.org/contueor/mintyflask-ssg.git
cd mintyflask-ssg
python -m venv venv
source venv/bin/activate
pip install -r requirements.txt

Summary

Installation checklist:

Git installed
Python 3.9+ installed
Both repositories cloned to same parent directory
Virtual environment created (recommended)
Python dependencies installed
Local configuration created (optional)
Development server runs successfully
Static build completes successfully

Key points:

Sibling directories - mintyflask-ssg and mintyflask-themes must be in the same parent directory
Virtual environment - Recommended for dependency isolation
Auto-discovery - Paths resolve automatically in most cases
Local config - Use config_local.py for custom settings
Two modes - Development server (Flask) and static build (Frozen-Flask)

You're now ready to start building with mintyflask-ssg!