🔧 Troubleshooting Guide

Site Build Failures

Symptom: npm run build fails with errors

Solution:

cd site
npm ci
npm run build

If issues persist, clear caches:

rm -rf site/node_modules site/package-lock.json
cd site && npm install

GitHub Pages Not Updating

Symptom: Changes pushed but site not updating

Solution:

• Check GitHub Actions workflow status
• Verify build completed successfully
• Wait 5-10 minutes for CDN cache to clear
• Clear browser cache or use incognito mode

Broken Links

Symptom: 404 errors when navigating

Solution:

• Ensure all internal links start with /
• Check that referenced pages exist in src/pages
• Rebuild the site after adding new pages
• Verify GitHub Pages is configured for the correct branch

Neo Glow FX Not Working

Symptom: Glow effects not displaying

Solution:

• Verify neo-glow-fx.css is in site/public/
• Check browser console for CSS loading errors
• Ensure classes are applied correctly (neo-card, neo-button, etc.)
• Clear browser cache

Mobile Menu Not Working

Symptom: Hamburger menu doesn't open on mobile

Solution:

• Check JavaScript console for errors
• Verify mobile-menu-toggle class exists in Layout.astro
• Test on different mobile devices/browsers
• Ensure viewport meta tag is present

TypeScript Compilation Errors

Solution:

npm run build
npm test

Check tsconfig.json for proper configuration.

Linting Failures

Solution:

npm run lint:fix
npm run format