Flatten hugo-site directory structure to repository root

[tmr08c]

Background

After completing the Gatsby to Hugo migration cleanup in #485, we still have the Hugo site nested in a hugo-site/ directory. Since Gatsby is completely removed, we can flatten this structure to follow standard Hugo conventions where the site lives at the repository root.

Prerequisites

• Merge Complete Gatsby to Hugo migration cleanup #485 first - this issue depends on the Gatsby cleanup being complete

Benefits of Flattening

• Cleaner structure - No nested directory for the only remaining site
• Simpler commands - No need to cd hugo-site for development
• Standard Hugo layout - Most Hugo sites live at the repository root
• Easier CI/deployment - Workflows won't need to specify hugo-site/ paths

Implementation Plan

Phase 1: Preparation (5 minutes)

1. Create a new branch from main (after Complete Gatsby to Hugo migration cleanup #485 is merged)
2. Create backup: git branch backup-before-flatten

Phase 2: File Movement (10 minutes)

1. Move Hugo core files to root:

   mv hugo-site/hugo.toml .
   mv hugo-site/content .
   mv hugo-site/layouts .
   mv hugo-site/assets .
   mv hugo-site/static .
   mv hugo-site/themes .
   mv hugo-site/archetypes .

2. Move development files to root:

   mv hugo-site/bin .
   mv hugo-site/Brewfile .
   mv hugo-site/postcss.config.js .
   mv hugo-site/package.json .
   mv hugo-site/package-lock.json .
   mv hugo-site/cypress .
   mv hugo-site/cypress.config.js .

3. Handle file conflicts:

   • Merge hugo-site/.tool-versions with root .tool-versions (keep both Node.js and Hugo versions)
   • Choose between root README.md vs hugo-site/README.md (or merge them)
   • Remove now-empty hugo-site/ directory

Phase 3: Git Submodule Update (5 minutes)

1. Update .gitmodules:

   [submodule "hugo-site/themes/hugo-texify3"]
   -    path = hugo-site/themes/hugo-texify3
   +    path = themes/hugo-texify3
        url = https://github.com/michaelneuper/hugo-texify3.git

2. Sync submodule:

   git submodule sync
   git add .gitmodules

Phase 4: Update GitHub Actions (10 minutes)

1. Update .github/workflows/ci.yml:

   - cache-dependency-path: hugo-site/package-lock.json
   + cache-dependency-path: package-lock.json
   
   - working-directory: hugo-site
   # Remove this line entirely
   
   - run: |
   -   cd hugo-site
   -   npm ci
   + run: npm ci

2. Update .github/workflows/deploy.yml:

   - HUGO_VERSION=$(grep hugo hugo-site/.tool-versions | awk '{print $2}')
   + HUGO_VERSION=$(grep hugo .tool-versions | awk '{print $2}')
   
   - run: |
   -   cd hugo-site
   -   [[ -f package-lock.json || -f npm-shrinkwrap.json ]] && npm ci || true
   + run: [[ -f package-lock.json || -f npm-shrinkwrap.json ]] && npm ci || true
   
   - run: |
   -   cd hugo-site
   -   hugo \
   + run: |
   +   hugo \
   
   - path: ./hugo-site/public
   + path: ./public

3. Update .github/workflows/link-check.yml:

   - folder-path: 'hugo-site/content'
   + folder-path: 'content'

Phase 5: Update Scripts and Documentation (10 minutes)

1. Update fix_hugo_links.sh:

   - cd hugo-site
   # Remove this line

2. Update .github/dependabot.yml:

   - directory: "/hugo-site"
   + directory: "/"

3. Update .gitignore:

   # Remove hugo-site specific patterns, add root patterns:
   - hugo-site/public/
   - hugo-site/resources/
   + public/
   + resources/

4. Update documentation in CLAUDE.md and README.md:

   • Remove all cd hugo-site commands
   • Update file paths to reflect root structure
   • Update architecture descriptions

Phase 6: Testing (15 minutes)

1. Test local development:

   ./bin/dev  # Should start Hugo server

2. Test build process:

   ./bin/build  # Should build successfully

3. Test E2E tests:

   npm install
   npm run test:e2e:ci

4. Verify GitHub Actions workflows by pushing to test branch

Phase 7: Final Verification (5 minutes)

1. Check for any remaining references:

   grep -r "hugo-site" . --exclude-dir=.git

2. Verify submodule is working:

   git submodule status

3. Test that Hugo can find theme:

   hugo version
   hugo list all

Success Criteria

• Hugo site builds and runs from repository root
• All GitHub Actions workflows pass
• E2E tests pass
• No references to hugo-site/ remain in codebase
• Git submodule works correctly
• Development scripts work from root

Risk Mitigation

• Low risk - Primarily moving files and updating paths
• Backup branch created before starting
• Reversible - All changes are tracked in git
• Incremental testing at each phase

Estimated Time: 1 hour

Most of the work is mechanical file movement and path updates. The git submodule update is the most complex part but is well-documented above.