A7. GitHub Pages

En esta actividad se utilizará GitHub Pages para publicar en Internet la documentación almacenada en el repositorio de GitHub.

Partiremos del repositorio utilizado en las actividades anteriores:

usuario-docs

El objetivo será completar el flujo de trabajo utilizado durante la unidad:

Documentación local
        ↓
       Git
        ↓
     GitHub
        ↓
  GitHub Pages
        ↓
Documentación publicada

1. Preparar la navegación

Antes de publicar la documentación, comprueba que el archivo:

index.md

funciona como página principal.

Desde este documento debe existir un enlace a:

ud1-technical-documentation/index.md

El index.md de la unidad deberá permitir acceder mediante enlaces Markdown a las diferentes actividades realizadas.

La navegación deberá permitir realizar, como mínimo, el siguiente recorrido:

Página principal
      ↓
UD1. Documentación técnica
      ↓
Actividad

Añade también en las páginas de las actividades los enlaces necesarios para poder regresar al índice de la unidad.

Antes de comenzar las modificaciones, comprueba el estado del repositorio y si existen cambios remotos pendientes de incorporar, siguiendo el procedimiento aprendido en la actividad anterior.

Comprueba mediante la previsualización de Markdown de Visual Studio Code que los enlaces funcionan correctamente.

Registra los cambios realizados mediante Git y envíalos a GitHub.

2. Publicar con GitHub Pages

Visibilidad del repositorio

Para publicar mediante GitHub Pages, el repositorio debe cumplir los requisitos de visibilidad y del plan de GitHub utilizado.

Si GitHub Pages no está disponible para el repositorio privado, será necesario cambiar su visibilidad a Public antes de continuar, siempre que el profesor lo autorice.

Accede en GitHub a la configuración del repositorio:

Settings → Pages

En Build and deployment, selecciona:

Source → Deploy from a branch

Selecciona como rama:

main

y como directorio:

/

Guarda la configuración.

GitHub iniciará el proceso de despliegue de la documentación.

Publicación

La primera publicación puede tardar unos instantes.

GitHub Pages mostrará la dirección del sitio cuando el despliegue haya finalizado.

Documenta mediante capturas la configuración realizada.

3. Acceder al sitio publicado

Cuando finalice el despliegue, accede a la dirección proporcionada por GitHub Pages.

La dirección tendrá una estructura similar a:

https://iesgrao-daw1-si-2627.github.io/usuario-docs/

Incluye en la documentación de esta actividad:

• La URL del sitio publicado.
• Una captura de su página principal.

4. Comprobar la publicación

Navega por la documentación publicada y comprueba:

• Que se muestra correctamente la página principal.
• Que los encabezados y listas tienen la estructura esperada.
• Que funcionan los enlaces entre documentos.
• Que es posible acceder a las diferentes actividades.
• Que las imágenes se muestran correctamente.
• Que los bloques de código son legibles.
• Que es posible regresar desde las actividades al índice de la unidad.

Si detectas algún problema, comprueba primero que el repositorio local está actualizado respecto al remoto.

Corrige los archivos Markdown necesarios, registra los cambios mediante Git y envíalos nuevamente a GitHub.

Comprueba posteriormente que GitHub Pages muestra el resultado corregido.

5. Actualizar la documentación publicada

Realiza una pequeña modificación en alguno de los documentos Markdown.

Por ejemplo, puedes:

• Corregir un texto.
• Añadir o mejorar un enlace.
• Mejorar alguna explicación.
• Corregir algún elemento de Markdown.

Antes de comenzar, comprueba si existen nuevos cambios en el repositorio remoto y, si los hay, revísalos mediante Visual Studio Code y Git Graph antes de incorporarlos al repositorio local.

Registra y envía el cambio utilizando el flujo habitual:

git status
    ↓
git fetch
    ↓
git status
    ↓
Revisar cambios en VS Code
    ↓
git pull (si hay cambios pendientes)
    ↓
Modificar documentación
    ↓
git status
    ↓
git add
    ↓
git commit
    ↓
git push

Accede a GitHub y comprueba que aparece el nuevo commit.

Espera a que GitHub Pages actualice el sitio y comprueba desde el navegador que la modificación también aparece en la documentación publicada.

Documenta mediante capturas:

• El cambio realizado.
• El nuevo commit.
• El resultado actualizado en GitHub Pages.

Actualización de GitHub Pages

Una vez configurado GitHub Pages, no es necesario repetir su configuración cada vez que modificamos la documentación.

Los cambios enviados al repositorio mediante git push se utilizarán para actualizar el sitio publicado.

6. Comprobación final

Comprueba que el resultado final permite recorrer correctamente todo el flujo de documentación:

Archivos y directorios
        ↓
Visual Studio Code
        ↓
     Markdown
        ↓
       Git
        ↓
     GitHub
        ↓
  GitHub Pages
        ↓
Documentación publicada

Comprueba finalmente que:

• El repositorio local está actualizado.
• El repositorio de GitHub contiene los últimos commits.
• GitHub Pages está publicado.
• La página principal se muestra correctamente.
• La navegación entre documentos funciona.
• Las imágenes y demás recursos se muestran correctamente.
• El sitio publicado contiene la última versión de la documentación.

Documentación de la actividad

Documenta todo el proceso realizado en el archivo correspondiente a esta actividad.

Incluye:

• La configuración utilizada para GitHub Pages.
• La URL de la documentación publicada.
• Una breve explicación de las operaciones realizadas.
• Capturas de pantalla que permitan comprobar el proceso.
• Los problemas encontrados y cómo los has solucionado, cuando corresponda.

Referencias

Añade las fuentes utilizadas para realizar la actividad.

Utiliza preferentemente la documentación oficial:

• GitHub Pages documentation.
• GitHub Docs.