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.md)
- [UD2. Instalación de sistemas operativos](ud2.md)
- [UD3. Gestión de la información](ud3.md)

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

Publicar con GitHub Pages

GitHub Pages puede configurarse desde las opciones del repositorio.

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://usuario.github.io/repositorio/

Por ejemplo:

https://student.github.io/technical-documentation/

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

TIP

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:

Modificar documentación
        ↓
      git add
        ↓
     git commit
        ↓
      git push
        ↓
       GitHub
        ↓
   GitHub Pages

Por ejemplo:

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

Después de enviar los cambios, GitHub actualizará el sitio publicado.

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

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.

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.

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.