¿Qué es GitHub Pages?: Alojar sitios estáticos gratuitamente

GitHub Pages es un servicio que permite alojar sitios web estáticos de forma gratuita directamente desde un repositorio de GitHub. Se utiliza para publicar páginas personales, documentación de proyectos o blogs sin necesidad de infraestructura adicional.

Los sitios web alojados en GitHub Pages se sirven desde una URL pública, generalmente en el formato https://<usuario>.github.io/ o https://<usuario>.github.io/<repositorio>/. Esto significa que, al actualizar el repositorio con nuevos commits, los cambios se reflejan automáticamente en el sitio web publicado.

Al ser un servicio pensado para contenido estático, GitHub Pages admite archivos HTML, CSS, JavaScript e imágenes, pero no soporta lenguajes del lado del servidor ni bases de datos. Se suele utilizar junto con generadores de sitios estáticos como Jekyll, Hugo o Gatsby para facilitar la creación y gestión del contenido.

Una de las ventajas principales es la integración con Git, lo que permite utilizar el control de versiones para el desarrollo del sitio web. Además, se facilita la colaboración entre múltiples desarrolladores, ya que se pueden gestionar pull requests y revisar cambios antes de publicarlos.

GitHub Pages es especialmente útil para desarrolladores y equipos que quieren publicar documentación o mostrar proyectos sin gastar en costes de alojamiento. También lo usan mucho estudiantes y profesionales que quieren crear un portfolio en línea.

Al utilizar GitHub Pages se asegura de que el sitio web esté disponible y sea accesible desde cualquier lugar. No se requiere configuración adicional de servidores ni preocuparse por el mantenimiento, ya que todo se gestiona a través del repositorio.

Configuración del repositorio: Ramas gh-pages o carpeta /docs

Para publicar un sitio web con GitHub Pages, es necesario configurar el repositorio adecuadamente. 

GitHub ofrece dos métodos principales para determinar qué contenido se servirá en el sitio: utilizar la rama gh-pages o emplear la carpeta /docs en la rama principal.

Uso de la rama **gh-pages**:

1. Crear la rama **gh-pages**: Si el repositorio no tiene esta rama, se puede crear ejecutando:

git checkout -b gh-pages

2. Añadir el contenido del sitio: Colocar los archivos HTML, CSS y demás recursos en la raíz de esta rama.

3. Subir la rama a GitHub: Hacer commit y push de los cambios:

git add .
git commit -m "Publicar sitio en gh-pages"
git push origin gh-pages

4. Configurar GitHub Pages: En la pestaña Settings del repositorio, ir a Pages y seleccionar gh-pages como fuente de publicación.

Uso de la carpeta /docs en la rama principal:

1. Crear la carpeta /docs: En la rama main, crear una carpeta llamada docs.

mkdir docs

2. Añadir el contenido del sitio: Colocar todos los archivos del sitio dentro de docs.

3. Hacer commit y push de los cambios:

git add docs
git commit -m "Agregar sitio en carpeta docs"
git push origin main

4. Configurar GitHub Pages: Navegar a Settings > Pages y seleccionar la rama main y la carpeta /docs como fuente.

Consideraciones adicionales:

• Archivo index.html: Es importante que el archivo principal se llame index.html, ya que será el punto de entrada del sitio.
• Tiempo de propagación: Después de configurar, puede tomar unos minutos hasta que el sitio esté disponible en la URL asignada.
• URLs de acceso: El sitio será accesible en https://<usuario>.github.io/<repositorio>/ si es un repositorio de proyecto, o en https://<usuario>.github.io/ si es un repositorio de usuario.

Verificación y solución de problemas:

• Logs de compilación: Si hay problemas, revisar los mensajes en la sección de GitHub Pages en Settings.
• Permisos del repositorio: Asegurarse de que el repositorio es público o que GitHub Pages está habilitado para repositorios privados en la cuenta.

Actualizar el sitio:

Cada vez que se realicen cambios en el contenido del sitio, simplemente hacer commit y push a la rama o carpeta configurada, y GitHub Pages actualizará el sitio automáticamente.

Despliegue automático: Opciones de build y publicación

Para aprovechar al máximo GitHub Pages, se puede configurar un despliegue automático que integre procesos de construcción y publicación. Esto es muy útil cuando se usan generadores de sitios estáticos como Jekyll, Hugo o Gatsby, que requieren una compilación previa antes de desplegar el sitio.

GitHub Pages soporta por defecto Jekyll, lo que permite que se ejecute automáticamente el proceso de build cada vez que se realizan cambios en el repositorio. Se incluyen muchas dependencias predeterminadas y se puede personalizar el sitio mediante un archivo _config.yml. Para proyectos que no utilizan Jekyll, se necesita deshabilitar esta opción añadiendo un archivo .nojekyll en la raíz del repositorio.

Si se necesita un proceso de build más personalizado o se usan otras herramientas de construcción, se puede configurar un workflow de GitHub Actions. Con GitHub Actions, se define un pipeline que construye el sitio y despliega los archivos generados a la rama o directorio configurado para GitHub Pages.

Un ejemplo común es desplegar un sitio construido con Hugo utilizando GitHub Actions. Se crea un archivo de workflow en .github/workflows/, especificando los pasos para instalar Hugo, construir el sitio y desplegarlo. Se utiliza la acción actions/checkout para obtener el código, seguida de peaceiris/actions-hugo para instalar Hugo, y finalmente peaceiris/actions-gh-pages para publicar el sitio en la rama gh-pages.

name: Build and Deploy

on:
  push:
    branches:
      - main

jobs:
  build-deploy:
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v3
      - name: Setup Hugo
        uses: peaceiris/actions-hugo@v2
        with:
          hugo-version: 'latest'
      - name: Build
        run: hugo --minify
      - name: Deploy
        uses: peaceiris/actions-gh-pages@v3
        with:
          github_token: ${{ secrets.GITHUB_TOKEN }}
          publish_dir: ./public

Con este workflow, cada vez que se hace push a la rama main, se desencadena el proceso de construcción y despliegue automático. Los archivos generados se publican en la rama gh-pages, desde donde GitHub Pages los sirve al público.

Para proyectos con React, Angular u otros frameworks más modernos, se siguen pasos parecidos ajustando el proceso de build a las herramientas específicas. Por ejemplo, en un proyecto con React, se instalan las dependencias con npm install, se construye el sitio con npm run build y se despliegan los archivos de la carpeta build.

name: Build and Deploy React App

on:
  push:
    branches:
      - main

jobs:
  build-deploy:
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v3
      - name: Setup Node.js
        uses: actions/setup-node@v3
        with:
          node-version: '16'
      - run: npm install
      - run: npm run build --if-present
      - name: Deploy
        uses: peaceiris/actions-gh-pages@v3
        with:
          github_token: ${{ secrets.GITHUB_TOKEN }}
          publish_dir: ./build

Es importante asegurarse de que los archivos estáticos generados se colocan en el directorio correcto especificado en los ajustes de GitHub Pages. La acción peaceiris/actions-gh-pages hace más fácil este proceso gestionando el push a la rama correspondiente.

Además, se pueden configurar opciones de publicación adicionales en la sección de Settings del repositorio. Allí se puede seleccionar la rama y carpeta desde donde se sirve el sitio, y en caso de utilizar un dominio personalizado, se puede especificar en el archivo CNAME.

Para proyectos que requieren un proceso de build más complejo, se tiene la opción de emplear servicios externos o pipelines más sofisticados.

Casos de uso: Documentación de proyectos, blogs, sitios personales

Uno de los principales usos es la publicación de documentación de proyectos. Al alojar la documentación en GitHub Pages, se facilita el acceso para usuarios y colaboradores, manteniendo todo el contenido actualizado y versionado junto con el código fuente. Mediante generadores como MkDocs o Docusaurus, se pueden crear sitios de documentación profesionales a partir de archivos Markdown.

Otro caso de uso común es la creación de blogs personales o técnicos. Gracias a la integración con Jekyll, es posible desarrollar y desplegar un blog estático de manera sencilla.

GitHub Pages también es se usa para construir sitios personales o portfolios. Profesionales pueden mostrar sus trabajos, proyectos y habilidades en un sitio web personalizado, aprovechando HTML, CSS y JavaScript para diseñar una página que refleje su trabajo.

Además, se utiliza para presentar demos o prototipos de aplicaciones web. Al desplegar versiones estáticas de aplicaciones construidas con frameworks como React o Angular, se puede compartir el estado actual del desarrollo con equipos o clientes.

Grupos y comunidades pueden emplear GitHub Pages para crear sitios informativos de eventos, proyectos colaborativos o iniciativas abiertas.

En el ámbito educativo, GitHub Pages se usa para publicar materiales de enseñanza, como cursos, guías o ejercicios. Esto beneficia tanto a docentes como a estudiantes, al centralizar los recursos y permitir actualizaciones rápidas.

Finalmente, para proyectos de código abierto, GitHub Pages ofrece una plataforma para presentar el proyecto, proporcionando documentación, instrucciones de instalación y guías de contribución.