oaustegard/website_reorg_dynamic_404.md

## website_reorg_dynamic_404.md

      
    Raw
  

              website_reorg_dynamic_404.md
            
          
    Repository Reorganization: When AI Collaboration Gets Things Done

I recently undertook a significant restructuring of my personal website repository at austegard.com, and the process turned into an interesting case study in AI collaboration. What started as a simple organization task ended up showcasing both the strengths and limitations of different AI assistants working together.
The Problem: Digital Hoarding Meets Poor Organization

My oaustegard.github.io repository (which powers austegard.com) had grown organically over time, accumulating an eclectic mix of tools, games, and utilities all dumped into the root directory. While functional, it was becoming increasingly difficult to navigate and maintain. The homepage was turning into a unwieldy list of random projects.
The Solution: Categorization + Smart 404 Handling

The restructuring involved three main components:
1. Categorical Organization

I moved all tools into logical directories:

ai-tools/ - LLM and AI-related utilities
fun-and-games/ - Entertainment and experimental projects
web-utilities/ - Development tools and file processors
bsky/ - Bluesky social network tools (already existed)

2. Dynamic Category Pages

Each category received an index.html page that uses a custom github-toc.js script to automatically generate listings of available tools. This means adding new tools to a category requires no manual maintenance of index pages.
3. Intelligent 404 Handling

Here's where things got interesting. Moving files breaks existing links, so I implemented a dynamic 404 page that:

Generates a sitemap.json file during deployment using a Python script
Uses JavaScript to search the sitemap when a 404 occurs
Automatically redirects users to the new location if a matching filename is found
Preserves query parameters during redirection

The 404 handler is surprisingly elegant:
// Simplified version - searches sitemap for moved files
const matches = fileList.filter(file => file.endsWith('/' + filename));
if (matches.length > 0) {
    // Redirect with 3-second delay and user notification
    window.location.href = `${newPath}${params}`;
}
The Deployment Challenge

Previously, the site was deployed using GitHub Pages' built-in Jekyll workflow, which worked perfectly for a straightforward static site. However, the new sitemap generation requirement meant I needed to run a Python script before Jekyll built the site.
This necessitated creating a custom GitHub Actions workflow to replace the automatic Pages deployment. The new workflow needed to:

Run the sitemap generation script
Set up Jekyll properly
Handle Pages deployment with correct permissions
Maintain the same deployment reliability

The AI Collaboration Story

This is where the project became unexpectedly educational. I initially worked with Google's Jules assistant to implement the changes. Jules did excellent work on the file reorganization and category structure, but hit a wall when creating the GitHub Actions workflow file.
The deployment YAML that Jules generated had syntax issues and incorrect action versions. When the workflow failed, Claude Sonnet stepped in and quickly identified the problems:

Incorrect action version references
Missing required permissions
Malformed job structure

Within minutes, Claude had produced a working workflow that properly integrated the sitemap generation into the deployment process.
Technical Implementation Details

The automated sitemap generation happens during every deployment:
- name: Generate sitemap
  run: python3 scripts/generate_sitemap.py
- name: Build with Jekyll
  uses: actions/jekyll-build-pages@v1
The Python script walks the repository structure, collects all HTML/MD files, and generates a clean JSON array of web paths. This runs before Jekyll builds the site, ensuring the sitemap is always current.
Lessons Learned


AI Strengths Vary: Jules excelled at conceptual organization and file operations, while Claude was superior at technical configuration and debugging.


Incremental Validation: The workflow failure was caught immediately, allowing for quick correction rather than debugging a complex system.


User Experience Matters: The 3-second redirect delay with visual feedback strikes a balance between automation and user awareness.


Automation Pays Off: The dynamic category pages and sitemap generation eliminate ongoing maintenance overhead.


Deployment Complexity: Moving from built-in Pages deployment to custom workflows introduces complexity but enables much more flexibility.


Results

The reorganization achieved its goals:

✅ Clean, logical directory structure
✅ Maintainable category pages
✅ Preserved backward compatibility via smart redirects
✅ Automated deployment pipeline with custom pre-build steps
✅ Better user navigation experience

The repository now scales much better, and adding new tools is as simple as dropping files into the appropriate directory. The automated 404 handling means I can reorganize freely without breaking existing bookmarks or shared links.
Sometimes the best solutions come from recognizing when different tools excel at different aspects of a problem. In this case, AI collaboration led to a more robust result than either assistant might have produced working alone.
View the complete changes at github.com/oaustegard/oaustegard.github.io or browse the reorganized tools at austegard.com/tools.
No results found