GitHub Pages

GitHub Pages es un servicio de GitHub que permite publicar sitios web estáticos directamente desde un repositorio.

Podemos utilizarlo para publicar documentación, páginas personales, sitios de proyectos y otros contenidos que no necesiten procesamiento en un servidor.

Durante esta unidad lo utilizaremos para publicar en Internet la documentación técnica creada con Markdown y almacenada en GitHub.

De repositorio a sitio web

Hasta ahora nuestro flujo de trabajo termina en un repositorio de GitHub:

Archivos
   ↓
Visual Studio Code
   ↓
Markdown
   ↓
Git
   ↓
GitHub

GitHub Pages añade un último paso:

Archivos
   ↓
Visual Studio Code
   ↓
Markdown
   ↓
Git
   ↓
GitHub
   ↓
GitHub Pages
   ↓
Sitio web

De esta forma, la documentación puede consultarse mediante un navegador sin necesidad de acceder directamente al repositorio.

Sitios web estáticos

GitHub Pages permite alojar sitios web estáticos.

Un sitio web estático está formado por archivos que pueden ser enviados directamente al navegador, como:

• HTML.
• CSS.
• JavaScript.
• Imágenes.
• Otros recursos estáticos.

GitHub Pages también permite trabajar con archivos Markdown y generar a partir de ellos las páginas que formarán parte del sitio.

No proporciona un servidor de aplicaciones para ejecutar tecnologías de backend como PHP, Python, Java o Node.js.

Repositorio

El contenido que queremos publicar debe encontrarse en un repositorio de GitHub.

Por ejemplo:

technical-documentation/
├── index.md
├── installation.md
├── configuration.md
└── images/
    └── terminal.png

El archivo:

index.md

puede utilizarse como página principal de nuestra documentación.

README.md e index.md

README.md se utiliza habitualmente como documento principal de un repositorio GitHub.

index.md puede utilizarse como página principal del sitio publicado.

Aunque ambos pueden contener información similar, cumplen funciones diferentes dentro de nuestro flujo de trabajo.

Crear la página principal

Podemos crear un archivo index.md:

touch index.md

y editarlo con Visual Studio Code.

Por ejemplo:

# Sistemas informáticos

Documentación de las prácticas realizadas durante el módulo.

## Unidades didácticas

- [UD1. Documentación técnica](ud1-technical-documentation/index.md).
- [UD2. Instalación de sistemas operativos](ud2/index.md).
- [UD3. Gestión de la información](ud3/index.md).

Este documento servirá como punto de entrada a la documentación publicada.

Los enlaces utilizan rutas relativas para facilitar la navegación entre los diferentes documentos.

Publicar con GitHub Pages

GitHub Pages puede configurarse desde las opciones del repositorio.

Visibilidad del repositorio

La posibilidad de publicar un repositorio privado mediante GitHub Pages depende del plan de GitHub y de la configuración de la organización.

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

El sitio publicado mediante GitHub Pages será accesible públicamente, por lo que no debemos incluir información privada o sensible en la documentación.

Accedemos a:

Settings → Pages

En la configuración de Build and deployment podemos seleccionar la forma en la que se publicará el sitio.

Para un proyecto sencillo podemos publicar el contenido desde una rama del repositorio.

Seleccionamos:

Source → Deploy from a branch

A continuación indicamos la rama desde la que queremos publicar, por ejemplo:

main

y el directorio correspondiente:

/

Finalmente guardamos la configuración.

GitHub iniciará el proceso de publicación del sitio.

Dirección del sitio

Una vez completada la publicación, GitHub Pages proporcionará una dirección desde la que podremos acceder al sitio.

Para un repositorio de proyecto, la dirección tendrá normalmente una estructura similar a:

https://propietario.github.io/repositorio/

El propietario puede ser una cuenta personal o una organización de GitHub.

Por ejemplo, para los repositorios utilizados durante esta unidad:

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

Podemos abrir esta dirección en un navegador para comprobar el resultado.

Publicación

La publicación puede tardar unos instantes después de activar GitHub Pages o enviar nuevos cambios al repositorio.

Actualizar la documentación

Una vez configurado GitHub Pages, no necesitamos volver a activar el servicio cada vez que modifiquemos la documentación.

Continuaremos trabajando mediante el flujo habitual de Git, comprobando primero si existen cambios remotos pendientes de incorporar.

Antes de modificar la documentación:

git status
git fetch
git status

Si existen cambios remotos pendientes, podemos revisarlos mediante Visual Studio Code y Git Graph y posteriormente incorporarlos:

git pull

Después de modificar la documentación:

git status
git add .
git commit -m "Update documentation"
git push

El flujo habitual será:

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
    ↓
GitHub
    ↓
GitHub Pages

Después de enviar los cambios, GitHub Pages iniciará la actualización del sitio publicado.

Esto permite mantener el repositorio y la documentación publicada a partir de los mismos archivos.

Actualización automática

Una vez configurado GitHub Pages, los nuevos commits enviados a la rama y directorio seleccionados se utilizarán para actualizar el sitio.

No es necesario repetir la configuración de GitHub Pages después de cada git push.

Enlaces entre documentos

Podemos dividir la documentación en diferentes archivos Markdown y relacionarlos mediante enlaces.

Por ejemplo:

technical-documentation/
├── index.md
├── installation.md
├── configuration.md
└── troubleshooting.md

Desde index.md podemos crear un pequeño índice:

# Documentación técnica

## Contenidos

- [Instalación](installation.md).
- [Configuración](configuration.md).
- [Resolución de problemas](troubleshooting.md).

Esto permite organizar la documentación en diferentes páginas en lugar de concentrar toda la información en un único documento.

Los enlaces deben utilizar rutas correctas respecto a la ubicación del archivo Markdown que los contiene.

Imágenes y otros recursos

Los recursos utilizados por la documentación pueden almacenarse dentro del propio repositorio.

Por ejemplo:

technical-documentation/
├── index.md
├── installation.md
└── images/
    ├── installation-01.png
    └── installation-02.png

Desde un documento Markdown podemos utilizar una ruta relativa:

![Proceso de instalación](images/installation-01.png)

Mantener los recursos dentro del repositorio permite gestionarlos y versionarlos junto con el resto de la documentación.

Comprobar la publicación

Después de publicar o actualizar el sitio debemos comprobar el resultado desde el navegador.

Entre otros aspectos debemos revisar:

• Que la página principal se muestra correctamente.
• Que los encabezados y listas tienen la estructura esperada.
• Que los enlaces funcionan.
• Que las imágenes se muestran.
• Que los bloques de código son legibles.
• Que podemos navegar entre los diferentes documentos.
• Que los últimos cambios enviados a GitHub aparecen en el sitio publicado.

Publicar correctamente un sitio no garantiza que su contenido o estructura sean correctos. La comprobación del resultado forma parte del proceso de publicación.

Flujo completo de documentación

Con GitHub Pages completamos el flujo de trabajo utilizado durante la unidad:

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

A partir de este momento podremos crear documentación en nuestro equipo, mantener su historial mediante Git, almacenarla en GitHub y publicarla como un sitio web accesible desde Internet.

Este será el procedimiento utilizado para publicar la documentación de las prácticas realizadas durante el módulo de Sistemas informáticos.