codigo0/docs/archivo/GITHUB_PAGES_FIX.md

✅ Corrección de GitHub Pages - COMPLETADA

Fecha: 2025-12-17

---

🔍 Problemas Identificados y Corregidos

❌ Problema 1: Base Path No Configurado

Problema: vite.config.ts no tenía configurado el base path para GitHub Pages.
Solución: ✅ Agregado detección automática del base path basado en variables de entorno.

❌ Problema 2: Rutas SPA No Funcionaban

Problema: GitHub Pages devuelve 404 para rutas como /manual porque no existen físicamente.
Solución: ✅ Creado public/404.html que redirige todas las rutas al index.html para que React Router las maneje.

❌ Problema 3: Workflow Sin Environment Configurado

Problema: El workflow no tenía el environment configurado correctamente.
Solución: ✅ Agregado environment: github-pages con URL de salida.

❌ Problema 4: Variables de Entorno No Pasadas al Build

Problema: El build no recibía información sobre el repositorio para configurar el base path.
Solución: ✅ Agregado paso para extraer el nombre del repositorio y pasarlo al build.

---

📝 Cambios Realizados

1. vite.config.ts

// Agregado detección de GitHub Pages
const isGitHubPages = process.env.GITHUB_PAGES === 'true';
const repositoryName = process.env.GITHUB_REPOSITORY_NAME || 'guia-tes-digital';
const base = isGitHubPages ? `/${repositoryName}/` : '/';

export default defineConfig({
  base: base, // ✅ Configurado para GitHub Pages
  // ... resto de la configuración
});

2. .github/workflows/deploy.yml

# ✅ Agregado environment
environment:
  name: github-pages
  url: ${{ steps.deployment.outputs.page_url }}

# ✅ Agregado paso para extraer nombre del repositorio
- name: Extract repository name
  id: repo
  run: |
    REPO_NAME=$(echo "${{ github.repository }}" | cut -d'/' -f2)
    echo "repository_name=$REPO_NAME" >> $GITHUB_OUTPUT    

# ✅ Pasando variables de entorno al build
- name: Build
  env:
    GITHUB_PAGES: 'true'
    GITHUB_REPOSITORY_NAME: ${{ steps.repo.outputs.repository_name }}
  run: npm run build

3. public/404.html

✅ Creado archivo 404.html que redirige todas las rutas al index.html para que React Router maneje las rutas SPA.

4. package.json

✅ El archivo 404.html es estático en public/ y se copia automáticamente durante el build. No se requiere script generate:404.

---

🚀 Cómo Funciona Ahora

1. Build en GitHub Actions:

   • Detecta que es GitHub Pages (GITHUB_PAGES=true)
   • Extrae el nombre del repositorio (guia-tes-digital)
   • Configura base: '/guia-tes-digital/' en Vite
   • Copia 404.html desde public/ a dist/ automáticamente

2. Despliegue:

   • GitHub Pages sirve los archivos desde dist/
   • Cuando se accede a /guia-tes-digital/manual, GitHub Pages busca manual/index.html
   • Como no existe, sirve 404.html
   • 404.html redirige a /guia-tes-digital/index.html
   • React Router toma el control y muestra la ruta /manual correctamente

---

✅ Verificación

Antes de Desplegar:

# Probar build local con configuración de GitHub Pages
npm run build:github

# Verificar que dist/ tenga 404.html
ls dist/404.html

# Verificar que dist/index.html tenga el base path correcto
grep -i "base href" dist/index.html

Después de Desplegar:

1. Ir a: https://planetazuzu.github.io/guia-tes-digital/
2. Verificar que la página principal carga
3. Navegar a /manual y verificar que funciona
4. Probar rutas como /manual/parte-i-fundamentos/bloque-0-fundamentos/1.1.1
5. Verificar que todas las rutas SPA funcionan correctamente

---

📋 Checklist de Configuración en GitHub

Para que el workflow funcione correctamente, asegúrate de:

• Habilitar GitHub Pages:

  1. Ir a Settings → Pages
  2. Source: "GitHub Actions" (no "Deploy from a branch")
  3. Guardar

• Verificar Permisos:

  • El workflow ya tiene los permisos correctos (pages: write, id-token: write)

• Verificar Workflow:

  • El workflow se ejecutará automáticamente en cada push a main
  • También se puede ejecutar manualmente desde Actions → "Deploy to GitHub Pages" → "Run workflow"

---

🎯 Resultado Final

✅ Base path configurado correctamente
✅ 404.html creado para manejar rutas SPA
✅ Workflow mejorado con environment y variables
✅ Build automático con configuración correcta
✅ Rutas SPA funcionarán correctamente en GitHub Pages

---

Estado: ✅ COMPLETADO Y LISTO PARA DESPLEGAR