🔄 Templates: Migrate from Mako to Flask's native Jinja2 engine

Replace the unmaintained `flask-mako` package (last updated 2015,
incompatible with Flask 3.x) with Jinja2, Flask's built-in template
engine. This eliminates two dependencies and removes the last blocker
for running on modern Flask.

- Convert all 37 `.mak` templates to `.html` Jinja2 equivalents
- `master.html`: `<%def>` blocks → `{% block %}`, `${self.body()}` →
  `{% block body %}`
- `blogs.html`: Inline Python moved to view, `loop.index` adjusted for
  Jinja2's 1-based indexing, `${var|h}` → `{{ var|e }}`
- `syllabus.html`: block overrides, unused macro removed
- Update `site.py`, `blueprints.py`, `participants.py` to use Flask's
  native `render_template`
- Add `name=` to duplicate blueprint registrations (Flask 3.x)
- Update `freeze.py` to use `(endpoint, values)` tuples for namespaced
  blueprint endpoints
- Remove `pyproject.toml` dependencies on `Mako` and `flask-mako`
- Delete all 37 old `.mak` template files

Assisted-by: Claude Opus 4.6 (1M context)
Signed-off-by: Justin Wheeler <git@jwheel.org>

Author: justwheel

CLAUDE.md

@@ -4,7 +4,7 @@ This file provides guidance to Claude Code (claude.ai/code) when working with co
 
 ## Project Overview
 
-HFLOSSK is the Humanitarian Free/Open Source Software Course website for RIT, built with Flask and Mako templates. It serves course materials (lectures, homework, quizzes) and tracks student participation via YAML files and RSS blog feeds. There is no database — all data is file-based.
+HFLOSSK is the Humanitarian Free/Open Source Software Course website for RIT, built with Flask and Jinja2 templates. It serves course materials (lectures, homework, quizzes) and tracks student participation via YAML files and RSS blog feeds. There is no database — all data is file-based.
 
 ## Commands
 
@@ -51,8 +51,8 @@ python freeze.py
 ### Entry Point
 `app.py` imports the Flask app from `hflossk/site.py` and runs the Flask dev server in debug mode. For production, use `gunicorn hflossk.site:app`.
 
-### Template Engine: Mako (not Jinja2)
-Templates use `.mak` extension and Mako syntax (`${variable}`, `<%inherit>`, `<%def>`, `% for`). The Flask-Mako extension bridges Flask and Mako. All templates live in `hflossk/templates/`.
+### Template Engine: Jinja2 (Flask native)
+Templates use `.html` extension and Jinja2 syntax (`{{ variable }}`, `{% extends %}`, `{% block %}`, `{% for %}`). All templates live in `hflossk/templates/` and inherit from `master.html`.
 
 ### Core Modules
 - **`hflossk/site.py`** — Flask app creation, route definitions, context processor that injects `site.yaml` config into all templates. Gravatar/Libravatar helper. Routes for pages, syllabus, blog JSON endpoint, participant profiles, resources.
@@ -66,7 +66,7 @@ Templates use `.mak` extension and Mako syntax (`${variable}`, `<%inherit>`, `<%
 3. **Blog tracking**: `/blog/<username>` endpoint parses student RSS feeds and returns JSON post count. Used via AJAX in the participants page.
 
 ### Content as Templates
-Course content (lectures, homework, quizzes) are Mako template files in `hflossk/templates/hw/`, `hflossk/templates/lectures/`, `hflossk/templates/quiz/`. They inherit from `master.mak`.
+Course content (lectures, homework, quizzes) are Jinja2 template files in `hflossk/templates/hw/`, `hflossk/templates/lectures/`, `hflossk/templates/quiz/`. They inherit from `master.html`.
 
 ### Static Assets
 `hflossk/static/` contains Bootstrap CSS/JS, course PDFs (`books/`), slide decks (`decks/`), and challenge descriptions (`challenges/`).
@@ -82,7 +82,6 @@ Course content (lectures, homework, quizzes) are Mako template files in `hflossk
 - **Static site generation**: `freeze.py` uses Frozen-Flask to crawl the app and generate static HTML. Dynamic routes like `/blog/<username>` (live RSS parsing) are excluded.
 
 ## Key Constraints
-- Flask-Mako pins the project to Mako templating; migration to Jinja2 would require rewriting 30+ template files
 - No database or ORM — all persistence is YAML files in the repo
 - Python 3.14 on Fedora 43 is the target runtime
 

freeze.py

@@ -18,69 +18,60 @@
 
 @freezer.register_generator
 def simple_page():
-    """Generate URLs for all top-level .mak templates."""
+    """Generate URLs for all top-level .html templates."""
     templates_dir = os.path.join(base_dir, 'templates')
     for fname in os.listdir(templates_dir):
-        if fname.endswith('.mak') and fname not in ('master.mak', 'ohno.mak',
-                                                     'participant.mak',
-                                                     'blogs.mak'):
-            yield {'page': fname.replace('.mak', '')}
+        if fname.endswith('.html') and fname not in ('master.html', 'ohno.html',
+                                                      'participant.html',
+                                                      'blogs.html'):
+            yield {'page': fname.replace('.html', '')}
 
 
-def _hw_pages():
-    """Generate page values for homework templates."""
+@freezer.register_generator
+def blueprint_pages():
+    """Generate URLs for all blueprint-served pages.
+
+    Yields (endpoint, values) tuples for namespaced blueprint endpoints.
+    Flask 3.x requires unique names for duplicate blueprint registrations,
+    so endpoints are namespaced as '<name>.<view_function>'.
+    """
     hw_dir = os.path.join(base_dir, 'templates', 'hw')
     if os.path.isdir(hw_dir):
-        yield {'page': 'index'}
-        for fname in os.listdir(hw_dir):
-            if fname.endswith('.mak') and fname != 'index.mak':
-                yield {'page': fname.replace('.mak', '')}
+        pages = ['index']
+        pages.extend(f.replace('.html', '') for f in os.listdir(hw_dir)
+                     if f.endswith('.html') and f != 'index.html')
+        for page in pages:
+            yield 'hw.display_homework', {'page': page}
+            yield 'assignments.display_homework', {'page': page}
 
-
-def _lecture_pages():
-    """Generate page values for lecture templates."""
     lectures_dir = os.path.join(base_dir, 'templates', 'lectures')
     if os.path.isdir(lectures_dir):
-        yield {'page': 'index'}
-        for fname in os.listdir(lectures_dir):
-            if fname.endswith('.mak') and fname != 'index.mak':
-                yield {'page': fname.replace('.mak', '')}
-
+        pages = ['index']
+        pages.extend(f.replace('.html', '') for f in os.listdir(lectures_dir)
+                     if f.endswith('.html') and f != 'index.html')
+        for page in pages:
+            yield 'lectures.display_lecture', {'page': page}
 
-def _quiz_pages():
-    """Generate quiz_num values for quiz templates."""
     quiz_dir = os.path.join(base_dir, 'templates', 'quiz')
     if os.path.isdir(quiz_dir):
         for fname in os.listdir(quiz_dir):
-            if fname.endswith('.mak'):
-                yield {'quiz_num': fname.replace('.mak', '')}
+            if fname.endswith('.html'):
+                quiz_num = fname.replace('.html', '')
+                yield 'quizzes.show_quiz', {'quiz_num': quiz_num}
+                yield 'quiz.show_quiz', {'quiz_num': quiz_num}
 
-
-def _participant_pages():
-    """Generate URLs for all participant profile pages."""
     people_dir = os.path.join('scripts', 'people')
     for dirpath, dirnames, files in os.walk(people_dir):
         for fname in files:
             if fname.endswith('.yaml'):
                 parts = dirpath.split(os.sep)
                 if len(parts) >= 4:
-                    year = parts[-2]
-                    term = parts[-1]
-                    username = fname.replace('.yaml', '')
-                    yield {'year': year, 'term': term, 'username': username}
-
-
-# Register generators for each named blueprint registration.
-# Flask 3.x requires unique names for duplicate blueprint registrations,
-# so endpoints are namespaced as '<name>.<view_function>'.
-freezer.register_generator(lambda: _hw_pages(), 'assignments.display_homework')
-freezer.register_generator(lambda: _hw_pages(), 'hw.display_homework')
-freezer.register_generator(lambda: _lecture_pages(), 'lectures.display_lecture')
-freezer.register_generator(lambda: _quiz_pages(), 'quizzes.show_quiz')
-freezer.register_generator(lambda: _quiz_pages(), 'quiz.show_quiz')
-freezer.register_generator(lambda: _participant_pages(), 'participants.participant_page')
-freezer.register_generator(lambda: _participant_pages(), 'blogs.participant_page')
-freezer.register_generator(lambda: _participant_pages(), 'checkblogs.participant_page')
+                    values = {
+                        'year': parts[-2],
+                        'term': parts[-1],
+                        'username': fname.replace('.yaml', ''),
+                    }
+                    yield 'participant_page', values
 
 
 if __name__ == '__main__':

hflossk/blueprints.py

@@ -1,7 +1,6 @@
 import os
 
-from flask import Blueprint
-from flask_mako import render_template
+from flask import Blueprint, render_template
 
 homework = Blueprint('homework', __name__, template_folder='templates')
 lectures = Blueprint('lectures', __name__, template_folder='templates')
@@ -16,11 +15,11 @@ def display_homework(page):
                                       'static', 'hw'))
         hws.extend(os.listdir(os.path.join(os.path.split(__file__)[0],
                                            'templates', 'hw')))
-        hws = [hw for hw in sorted(hws) if not hw == "index.mak"]
+        hws = [hw for hw in sorted(hws) if not hw == "index.html"]
     else:
         hws = None
 
-    return render_template('hw/{}.mak'.format(page), name='mako', hws=hws)
+    return render_template('hw/{}.html'.format(page), hws=hws)
 
 
 @lectures.route('/', defaults={'page': 'index'})
@@ -30,14 +29,14 @@ def display_lecture(page):
         lecture_notes = os.listdir(os.path.join(os.path.split(__file__)[0],
                                                 'templates', 'lectures'))
         lecture_notes = [note for note in sorted(lecture_notes)
-                         if not note == "index.mak"]
+                         if not note == "index.html"]
     else:
         lecture_notes = None
 
-    return render_template('lectures/{}.mak'.format(page), name='mako',
+    return render_template('lectures/{}.html'.format(page),
                            lectures=lecture_notes)
 
 
 @quizzes.route('/<quiz_num>')
 def show_quiz(quiz_num):
-    return render_template('quiz/{}.mak'.format(quiz_num), name='mako')
+    return render_template('quiz/{}.html'.format(quiz_num))

hflossk/participants.py

@@ -3,8 +3,7 @@
 
 import hflossk
 import yaml
-from flask import Blueprint
-from flask_mako import render_template
+from flask import Blueprint, render_template
 
 
 participants_bp = Blueprint('participants_bp',
@@ -85,6 +84,9 @@ def participants(root_dir):
                     )
                     contents['isActive'] = (currentYear in year_term_data
                                             and currentTerm in year_term_data)
+                    # Ensure hw dict exists for template iteration
+                    if 'hw' not in contents:
+                        contents['hw'] = {}
 
                     student_data.append(contents)
 
@@ -97,10 +99,8 @@ def participants(root_dir):
                         len(assignments))
 
     return render_template(
-        'blogs.mak', name='mako',
+        'blogs.html',
         student_data=student_data,
         gravatar=hflossk.site.gravatar,
         target_number=target_number
     )
-
-#

hflossk/site.py

@@ -11,8 +11,7 @@
 from datetime import datetime
 
 import yaml
-from flask import Flask, jsonify
-from flask_mako import MakoTemplates, render_template
+from flask import Flask, jsonify, render_template
 from werkzeug.exceptions import NotFound
 
 from hflossk.blueprints import homework, lectures, quizzes
@@ -21,7 +20,6 @@
 
 app = Flask(__name__)
 app.template_folder = "templates"
-mako = MakoTemplates(app)
 base_dir = os.path.split(__file__)[0]
 
 
@@ -32,7 +30,6 @@ def inject_yaml():
         site_config = yaml.safe_load(site_yaml)
     return site_config
 
-app.config['MAKO_TRANSLATE_EXCEPTIONS'] = False
 config = inject_yaml()
 COURSE_START = datetime.combine(config['course']['start'], datetime.min.time())
 COURSE_END = datetime.combine(config['course']['end'], datetime.max.time())
@@ -59,13 +56,13 @@ def gravatar(email):
 @app.route('/<page>')
 def simple_page(page):
     """
-    Render a simple page. Looks for a .mak template file
+    Render a simple page. Looks for a .html template file
     with the name of the page parameter that was passed in.
     By default, this just shows the homepage.
 
     """
 
-    return render_template('{}.mak'.format(page), name='mako')
+    return render_template('{}.html'.format(page))
 
 
 @app.route('/static/manifest.webapp')
@@ -86,7 +83,7 @@ def syllabus():
 
     with open(os.path.join(base_dir, 'schedule.yaml')) as schedule_yaml:
         schedule = yaml.safe_load(schedule_yaml)
-    return render_template('syllabus.mak', schedule=schedule, name='mako')
+    return render_template('syllabus.html', schedule=schedule)
 
 
 @app.route('/blog/<username>')
@@ -125,7 +122,7 @@ def participant_page(year, term, username):
                                   year, term, username + '.yaml'))
     with open(person_yaml) as participant_file:
         return render_template(
-            'participant.mak', name='make',
+            'participant.html',
             participant_data=yaml.safe_load(participant_file),
             gravatar=gravatar
         )
@@ -142,14 +139,14 @@ def resources():
     res['Videos'] = os.listdir(os.path.join(
         base_dir, 'static', 'videos'))
 
-    return render_template('resources.mak', name='mako', resources=res)
+    return render_template('resources.html', resources=res)
 
 
-app.register_blueprint(homework, url_prefix='/assignments')
-app.register_blueprint(homework, url_prefix='/hw')
+app.register_blueprint(homework, url_prefix='/assignments', name='assignments')
+app.register_blueprint(homework, url_prefix='/hw', name='hw')
 app.register_blueprint(lectures, url_prefix='/lectures')
-app.register_blueprint(quizzes, url_prefix='/quizzes')
-app.register_blueprint(quizzes, url_prefix='/quiz')
-app.register_blueprint(participants_bp, url_prefix='/participants')
-app.register_blueprint(participants_bp, url_prefix='/blogs')
-app.register_blueprint(participants_bp, url_prefix='/checkblogs')
+app.register_blueprint(quizzes, url_prefix='/quizzes', name='quizzes')
+app.register_blueprint(quizzes, url_prefix='/quiz', name='quiz')
+app.register_blueprint(participants_bp, url_prefix='/participants', name='participants')
+app.register_blueprint(participants_bp, url_prefix='/blogs', name='blogs')
+app.register_blueprint(participants_bp, url_prefix='/checkblogs', name='checkblogs')

hflossk/templates/about.mak hflossk/templates/about.htmlhflossk/templates/about.mak renamed to hflossk/templates/about.html

@@ -1,4 +1,6 @@
-<%inherit file="master.mak"/>
+{% extends "master.html" %}
+
+{% block body %}
 
 <div class="jumbotron">
 <h1>Hello, world!</h1>
@@ -25,3 +27,4 @@ <h2>Mako</h2>
   <p><a class="btn" target="_blank" href="http://www.makotemplates.org/">View details &raquo;</a></p>
 </div><!--/span-->
 </div><!--/row-->
+{% endblock %}