add base_url support for GitHub Pages project sites

All internal links were hardcoded to the domain root (/css/...,
/lecture_notes/..., etc.), which breaks on project sites served at a
subpath like /course_materials/. Threads a --base-url CLI arg through
build.py, Jinja2 globals, and image path rewriting.

Co-Authored-By: Claude Opus 4.6 (1M context) <noreply@anthropic.com>

Author: TrevorAustin

.github/workflows/build-and-deploy.yml

@@ -23,7 +23,7 @@ jobs:
         with:
           python-version: "3.12"
       - run: pip install -r requirements.txt
-      - run: python build.py
+      - run: python build.py --base-url "/${{ github.event.repository.name }}"
       - uses: actions/upload-pages-artifact@v3
         with:
           path: _site

build.py

@@ -1,5 +1,5 @@
+import argparse
 import glob
-import os
 import re
 import shutil
 from pathlib import Path
@@ -10,8 +10,12 @@
 from preprocessor import split_slides, process_slide, rewrite_image_paths
 
 
-def build_site(output_dir: str = "_site"):
-    """Build the entire static site."""
+def build_site(output_dir: str = "_site", base_url: str = ""):
+    """Build the entire static site.
+
+    base_url: path prefix for project sites (e.g., "/course_materials").
+              Empty string for sites served at the domain root.
+    """
     root = Path(__file__).parent
     out = Path(output_dir)
 
@@ -23,6 +27,7 @@ def build_site(output_dir: str = "_site"):
     # Set up Jinja2 — autoescape=False since templates use {{ content }}
     # with pre-rendered HTML and this is a static site generator, not a web app
     env = Environment(loader=FileSystemLoader(root / "templates"), autoescape=False)
+    env.globals["base_url"] = base_url
 
     # Copy static assets
     shutil.copytree(root / "static" / "css", out / "css")
@@ -48,11 +53,11 @@ def build_site(output_dir: str = "_site"):
 
         for i, slide_md in enumerate(slide_strings, 1):
             html_content, classes = process_slide(slide_md)
-            html_content = rewrite_image_paths(html_content)
+            html_content = rewrite_image_paths(html_content, base_url)
 
-            prev_url = f"/lecture_notes/week_{week_num}/{i - 1}/" if i > 1 else ""
-            next_url = f"/lecture_notes/week_{week_num}/{i + 1}/" if i < total_slides else ""
-            first_url = f"/lecture_notes/week_{week_num}/1/"
+            prev_url = f"{base_url}/lecture_notes/week_{week_num}/{i - 1}/" if i > 1 else ""
+            next_url = f"{base_url}/lecture_notes/week_{week_num}/{i + 1}/" if i < total_slides else ""
+            first_url = f"{base_url}/lecture_notes/week_{week_num}/1/"
 
             slide_html = env.get_template("slide.html").render(
                 content=html_content,
@@ -97,4 +102,11 @@ def build_site(output_dir: str = "_site"):
 
 
 if __name__ == "__main__":
-    build_site()
+    parser = argparse.ArgumentParser(description="Build the static site.")
+    parser.add_argument(
+        "--base-url",
+        default="",
+        help="URL path prefix for project sites (e.g., /course_materials)",
+    )
+    args = parser.parse_args()
+    build_site(base_url=args.base_url.rstrip("/"))

preprocessor.py

@@ -174,7 +174,7 @@ def process_slide(slide_md: str) -> tuple[str, list[str]]:
     return html, classes
 
 
-def rewrite_image_paths(html: str) -> str:
+def rewrite_image_paths(html: str, base_url: str = "") -> str:
     """Rewrite relative image src paths to absolute /lecture_notes/ paths.
     Only affects <img> tags, not <script> or other elements.
     """
@@ -183,6 +183,6 @@ def replace_img_src(match):
         src = match.group(2)
         if src.startswith(("http://", "https://", "/")):
             return match.group(0)
-        return f'<img{prefix}src="/lecture_notes/{src}"'
+        return f'<img{prefix}src="{base_url}/lecture_notes/{src}"'
 
     return re.sub(r'<img([^>]*)src="([^"]*)"', replace_img_src, html)

templates/base.html

@@ -4,15 +4,15 @@
     <meta charset="utf-8">
     <meta name="viewport" content="width=device-width, initial-scale=1">
     <title>{% block title %}Web Development{% endblock %}</title>
-    <link rel="stylesheet" href="/css/style.css">
+    <link rel="stylesheet" href="{{ base_url }}/css/style.css">
 </head>
 <body>
     <nav id="header">
         <ul>
-            <li><a href="/">Home</a></li>
-            <li><a href="/lecture_notes/">Lectures</a></li>
-            <li><a href="/syllabus/">Syllabus</a></li>
-            <li><a href="/examples/">Examples</a></li>
+            <li><a href="{{ base_url }}/">Home</a></li>
+            <li><a href="{{ base_url }}/lecture_notes/">Lectures</a></li>
+            <li><a href="{{ base_url }}/syllabus/">Syllabus</a></li>
+            <li><a href="{{ base_url }}/examples/">Examples</a></li>
         </ul>
     </nav>
     <main>

templates/index.html

@@ -7,9 +7,9 @@
     <h1>Web Development</h1>
     <h3>MPCS 52553 — Spring 2026</h3>
     <ul>
-        <li><a href="/syllabus/">Syllabus</a></li>
-        <li><a href="/lecture_notes/">Lecture Notes</a></li>
-        <li><a href="/examples/">Examples &amp; Labs</a></li>
+        <li><a href="{{ base_url }}/syllabus/">Syllabus</a></li>
+        <li><a href="{{ base_url }}/lecture_notes/">Lecture Notes</a></li>
+        <li><a href="{{ base_url }}/examples/">Examples &amp; Labs</a></li>
     </ul>
     <p>
         Course materials are on

templates/lecture_index.html

@@ -13,7 +13,7 @@ <h1>Lecture Notes</h1>
     </p>
     <ul>
         {% for week in weeks %}
-        <li><a href="/lecture_notes/week_{{ week }}/1/">Week {{ week }}</a></li>
+        <li><a href="{{ base_url }}/lecture_notes/week_{{ week }}/1/">Week {{ week }}</a></li>
         {% endfor %}
     </ul>
 </div>

templates/slide.html

@@ -34,5 +34,5 @@
 {% endblock %}
 
 {% block scripts %}
-<script src="/js/navigation.js"></script>
+<script src="{{ base_url }}/js/navigation.js"></script>
 {% endblock %}

tests/test_build.py

@@ -1,5 +1,3 @@
-import os
-import shutil
 from pathlib import Path
 from build import build_site
 
@@ -37,3 +35,24 @@ def test_build_no_week_8_old(tmp_path, monkeypatch):
     build_site(output_dir=str(tmp_path / "_site"))
 
     assert not (tmp_path / "_site" / "lecture_notes" / "week_8_old").exists()
+
+
+def test_build_base_url(tmp_path, monkeypatch):
+    """base_url is prefixed on all internal links."""
+    monkeypatch.chdir(Path(__file__).parent.parent)
+    build_site(output_dir=str(tmp_path / "_site"), base_url="/course_materials")
+    site = tmp_path / "_site"
+
+    # Homepage links use base_url
+    homepage = (site / "index.html").read_text()
+    assert 'href="/course_materials/syllabus/"' in homepage
+
+    # Slide navigation uses base_url
+    slide = (site / "lecture_notes" / "week_1" / "2" / "index.html").read_text()
+    assert 'data-prev="/course_materials/lecture_notes/week_1/1/"' in slide
+    assert "/course_materials/js/navigation.js" in slide
+    assert "/course_materials/css/style.css" in slide
+
+    # Lecture index uses base_url
+    lecture_index = (site / "lecture_notes" / "index.html").read_text()
+    assert "/course_materials/lecture_notes/week_1/1/" in lecture_index