Installation Quick Start

What You Need

Git installed on your system
Python 3.9+ (if running the Flask application)
A GitHub or Codeberg account (for cloning)
Basic terminal knowledge

Quick Install (2 Minutes)

mintyflask-themes Only

# Clone the repository
git clone https://codeberg.org/contueor/mintyflask-themes.git
cd mintyflask-themes

# You're ready to go!

That's it. The project is ready to use. The templates, CSS, and configuration files are all included.

With mintyflask-ssg (Static Site Generator)

If you're planning to use the static site generator, clone both projects to the same parent directory:

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

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

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

Why the same directory? mintyflask-ssg expects to find mintyflask-themes as a sibling directory for template and asset resolution.

Verify Installation

Check that the essential directories exist:

cd mintyflask-themes
ls -la

# You should see:
# ├── mixins/          # Blog, photos, etc.
# ├── themes/          # _core, blog, etc.
# ├── README.md
# └── (other files)

What You Get

Core directories:

mixins/ - Reusable features (blog, photos, forms, etc.)
themes/ - Complete themes using mixins
themes/_core/ - Foundation CSS and base templates

Key mixin:

mixins/blog/ - Complete blog system with posts, categories, tags, archives

Key theme:

themes/blog/ - Blog theme demonstrating mixin usage

Quick Decision Guide

What should I do next?

Do you want to build a static site?
├─ YES → Install mintyflask-ssg (see above)
│        Then: Read the SSG Quick Start Guide
└─ NO  → Are you building a Flask application?
    ├─ YES → Read the Flask Integration Guide
    └─ NO  → Are you just exploring/customising themes?
             └─ YES → Read the Theme Customisation Guide

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

# Create content directory
mkdir content
cd content

# Start writing!

Scenario 2: Adding to Existing Flask Project

# In your existing Flask project
cd my-flask-project

# Clone as a subdirectory
git clone https://codeberg.org/contueor/mintyflask-themes.git themes

# Update your Flask config to point to ./themes

Scenario 3: Creating a Custom Theme

# Clone the project
git clone https://codeberg.org/contueor/mintyflask-themes.git
cd mintyflask-themes

# Create your theme directory
mkdir -p themes/my-custom-theme

# Copy a starter theme
cp -r themes/blog/* themes/my-custom-theme/

# Start customising!

Directory Structure Explained

mintyflask-themes/
│
├── mixins/                   # Reusable feature modules
│   ├── blog/                 # Blog mixin
│   │   ├── static/           # CSS and JS
│   │   │   └── css/
│   │   │       └── blog.css  # Blog component styles
│   │   └── templates/        # Blog templates
│   │       ├── components/   # Reusable components
│   │       ├── layouts/      # Page layouts
│   │       └── partials/     # Template fragments
│   │
│   └── photos/               # Photo gallery mixin (example)
│       └── (similar structure)
│
├── themes/                   # Complete themes
│   ├── _core/                # Foundation (required)
│   │   ├── static/
│   │   │   └── css/
│   │   │       ├── foundations/  # Design tokens, typography
│   │   │       ├── components/   # Core components
│   │   │       ├── themes/       # Theme layer
│   │   │       └── utilities/    # Utility classes
│   │   └── templates/        # Base templates
│   │
│   └── blog/                 # Blog theme
│       ├── config/
│       │   └── theme.yaml    # Theme configuration
│       ├── static/
│       │   └── css/
│       │       └── src/
│       │           └── input.css  # Main CSS entry point
│       └── templates/        # Theme templates
│
└── README.md                 # Project documentation

Alternate Installation Methods

Download as ZIP (Not Recommended)

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

# Rename to remove -main suffix
cd ..
mv mintyflask-themes-main MintyFlaskThemes

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

As a Git Submodule (Advanced)

# In your existing Git repository
git submodule add https://codeberg.org/contueor/mintyflask-themes.git themes

# Initialize and update
git submodule init
git submodule update

Use case: When integrating mintyflask-themes into a larger project with version control.

Updating Your Installation

Pull Latest Changes

cd mintyflask-themes
git pull origin main

Update Both Projects (SSG Setup)

# From workspace directory
cd minty-workspace

# Update themes
cd mintyflask-themes
git pull origin main

# Update SSG
cd ../mintyflask-ssg
git pull origin main

Check for Breaking Changes

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

# View file changes
git diff HEAD~10..HEAD

Common Issues

Issue: "Command not found: git"

Solution: Install Git:

# Ubuntu/Debian
sudo apt-get install git

# macOS (using Homebrew)
brew install git

# Windows
# Download from https://git-scm.com/download/win

Issue: mintyflask-ssg can't find templates

Problem: Projects not in the same parent directory.

Solution:

# Check your directory structure
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: Permission denied

Solution:

# Check permissions
ls -la

# Fix if needed
chmod -R 755 mintyflask-themes

What's Next?

After installation:

Explore the blog theme - See how mixins and themes work together
Read the CSS Architecture Guide - Understand the five-layer system
Try customising - Modify colours, fonts, or layouts
Build something - Create your first blog or portfolio

Development Installation

For contributors and developers:

# Clone with full history
git clone https://codeberg.org/contueor/mintyflask-themes.git
cd mintyflask-themes

# Create a development branch
git checkout -b feature/my-feature

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

# Make changes and test

# 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)?

Files are missing after clone

Check:

# Verify clone completed
git status

# Should show: "On branch main, nothing to commit, working tree clean"

# Check file count
find . -type f | wc -l

# Should show 100+ files

Need to start fresh

# Remove the directory
rm -rf mintyflask-themes

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

Summary

Installation checklist:

Key points:

Simple clone - Just git clone and you're ready
SSG needs sibling - mintyflask-ssg expects mintyflask-themes in the same parent directory
Core required - themes/_core/ must exist for all themes
Git recommended - Easier to update and track changes

You're now ready to start working with mintyflask-themes!