Quick reference guide to running the MintyFlaskSSG application

Running the MintyFlaskSSG Application

Basic Usage

# Default development mode
python run.py

# Specific configuration profile
python run.py --config <profile>

# With Pandoc strict mode
python run.py --strict-pandoc

Configuration Profiles

Profile Purpose Environment Logging Level
development Standard development (default) development INFO
photos Debug photo processing development DEBUG (photos only)
routes Debug route handling development DEBUG (routes only)
blog Debug blog functionality development DEBUG (blog only)
quiet Minimal logging development WARNING (all)
all Full debug output development DEBUG (all subsystems)
production Production deployment production WARNING

Common Commands

# Standard development with INFO logging
python run.py

# Debug photo gallery issues
python run.py --config photos

# Debug blog routes and taxonomy
python run.py --config blog

# Debug route resolution problems
python run.py --config routes

# Full debug for complex troubleshooting
python run.py --config all

# Quiet mode for clean output
python run.py --config quiet

# Production mode (no debug, minimal logging)
python run.py --config production

# Development with strict Pandoc (no Markdown fallback)
python run.py --strict-pandoc

Configuration Profile Details

development (Default)

  • Use when: Normal development work
  • Logs: Blog, Home, Core at INFO level
  • Photos: WARNING level
  • Best for: General development, content authoring

photos

  • Use when: Debugging photo processing, galleries, EXIF
  • Logs: Photos at DEBUG level, others at default
  • Best for: Gallery issues, image processing problems

routes

  • Use when: Template resolution issues, 404s, routing problems
  • Logs: Routes at DEBUG level
  • Best for: Blueprint registration, URL generation issues

blog

  • Use when: Blog post display, taxonomy, pagination issues
  • Logs: Blog at DEBUG level
  • Best for: Post rendering, category/tag problems

all

  • Use when: Complex issues spanning multiple subsystems
  • Logs: Everything at DEBUG level
  • Best for: Initial troubleshooting, system-wide issues

quiet

  • Use when: Running alongside other tools, focusing on output
  • Logs: WARNING level only
  • Best for: Clean terminal, production-like environment

production

  • Use when: Deploying to live environment
  • Logs: WARNING level, debug disabled
  • Best for: Live deployment, static site generation

Command-Line Options

--config <profile>

Selects the configuration profile (see table above)

python run.py --config photos

--strict-pandoc

Enables strict Pandoc mode with no Markdown fallback

python run.py --strict-pandoc
python run.py --config production --strict-pandoc

Warning: Pandoc must be installed or all rendering will fail

Environment Variables Set by Profile

Profile ENVIRONMENT Variable
production production
All others development

Debug Flags Available

The application checks these config keys for debug behaviour:

  • DEBUG_PHOTOS: Enables detailed photo processing logs
  • DEBUG_BLOG: Enables detailed blog route logs
  • DEBUG_ROUTES: Enables detailed route resolution logs

Network Configuration

  • Host: 0.0.0.0 (accessible from network)
  • Port: 5000
  • Debug mode: Always enabled in run.py (auto-reload on code changes)

Quick Troubleshooting Guide

Problem Use This Profile
Photos not displaying photos
Template not found routes
Blog post 404 blog
Category/tag issues blog
Gallery index empty photos
Don't know where to start all
Need clean output quiet

Development Workflow Examples

# Morning startup - check everything works
python run.py --config all

# Working on blog post display
python run.py --config blog

# Fixing photo gallery
python run.py --config photos

# Testing production build locally
python run.py --config production

# Demos and presentations
python run.py --config quiet

Logging Output Indicators

When you start the application, you'll see:

🔧 Starting Flask application with config.DevelopmentConfig
📊 Debug logging enabled for: PHOTOS, BLOG

or

🔧 Starting Flask application with config.ProductionConfig
🔇 Normal logging mode (minimal debug output)

Static Site Generation

For building static sites, use a separate command:

# Build static site (uses production config internally)
flask freeze

# Or use dedicated script
python freeze.py

Tips

  1. Start with all config when diagnosing new issues
  2. Switch to specific profile once you identify the subsystem
  3. Use quiet mode when running other monitoring tools
  4. Never deploy with debug profiles - always use production
  5. Check logs first - debug modes show detailed information about decisions