Última actualización: 2025-07-01 | Mejora esta página

Tiempo estimado: 0 minutos

Hoja de ruta

Preguntas

¿Qué es una web estática?
¿Por qué debería utilizar GitHub o GitLab Pages para crear mi página web?

Objetivos

Explicar qué hace un generador de páginas estático
Escoger la herramienta apropiada para tu website/proyecto

Cómo funcionan los sitios web

Cuando utilizamos un navegador web para visitar una página de la World-Wide Web, el navegador solicita información a un servidor - un ordenador que almacena los datos relevantes para el sitio y está configurado para recibir y responder a las peticiones de esos datos. Suponiendo que no haya problemas en esta etapa (por ejemplo, que se pida una página que no existe o que no se pueda llegar al servidor), nuestro navegador recibe e interpreta esta información para renderizar y mostrar la página web en nuestra pantalla.

Un desarrollador web probablemente se horrorizaría al leer una simplificación tan burda, que es sólo una de las razones por las que los desarrolladores web no son el público objetivo de este tutorial.

La página que muestra el navegador web es el resultado de combinar HTML -un formato jerárquico que describe los elementos estructurales de la página y su contenido en bruto- con CSS -un conjunto ordenado de instrucciones de estilo que indican al navegador cómo debe organizarse y formatearse el contenido- y cualquier imagen que deba incrustarse en la página. Otra información recibida del servidor, pero no mostrada por el navegador, incluye metadatos, cookies y otros elementos no visibles en el HTML -información sobre el sitio que podría ser relevante para un ordenador pero que probablemente no sea interesante para un ser humano (hay excepciones a esto)- y scripts que el navegador puede ejecutar para hacer algo en respuesta a varios disparadores.

Hola Mundo en HTML

Al aprender un nuevo lenguaje de programación, es frecuente encontrar una referencia al popular ejemplo Hello world. Estos ejemplos suelen capturar el código más simple que puede producir y mostrar el texto “¡Hola, mundo!” en pantalla.

Como HTML requiere que ciertas etiquetas estén presentes y casi siempre en pares coincidentes (abrir <tag> y cerrar </tag>), los documentos HTML tienden a volverse verbosos con bastante rapidez.

El HTML más simple y válido Hello world es:

HTML

<!DOCTYPE html>
<html>
  <head>
    <title>Page title</title>
  </head>
  <body>
    <p>Hello, World!</p>
  </body>
</html>

Así que, como puedes imaginar, escribir documentos HTML largos a mano es bastante doloroso. Observe que no hemos especificado nada sobre cómo y dónde debe mostrarse el texto.

Para conseguir esto necesitaríamos además incluir etiquetas estilizadas o instrucciones Cascading Style Sheets (CSS). Si no proporciona instrucciones CSS (ya sea dentro de su documento HTML o como un archivo separado), un navegador web hará una mejor suposición con respecto a la disposición de los elementos HTML en la página basándose en sus valores predeterminados.

Las Muchas Etiquetas en HTML

En el ejemplo Hello world de arriba se usan 5 etiquetas diferentes (html, head, title, body y p) en su forma abierta <> y cerrada </>. También vemos la etiqueta especial doctype que indica el formato y la versión del documento, en este caso, [HTML(5)][html5-wikipedia].

Existen muchas otras etiquetas para definir:

elementos estructurales, como table, div, span, nav, section;
listas, como ul (para listas desordenadas) y or (para listas ordenadas);
elementos estilizados, como i/em (para cursivas/énfasis), b/strong (para negrita) y u (para texto subrayado);
encabezados, numerados de h1 a h6 para títulos y subtítulos progresivamente más pequeños;
elementos multimedia, como img, video, audio para incrustar contenido multimedia enriquecido; y
links, utilizando la importante etiqueta a (anchor) para enlazar a secciones de la misma página o a otras páginas dentro del mismo sitio web o de sitios web externos.

La lista de etiquetas HTML válidas es bastante extensa, cubriendo una rica gama de características que potencian la actual world wide web.

Ejercicio: Escribiendo HTML Básico

Dado el texto estilizado:

Hello, World!

escribir el HTML que producirá el mismo resultado. Pista la fuente grande se consigue mediante el uso de un encabezado.

Solución

HTML

<h1><em>Hello</em>, World!</h1>

Escribamos un ejemplo HTML más complejo utilizando una tabla que muestre el texto “¡Hola, mundo!” en diferentes idiomas y que se renderice como: Ejemplo de tabla HTML

El HTML para producir dicha tabla tiene este aspecto (puedes copiar+pegar el fragmento en el archivo HTML que creaste en el ejemplo anterior):

HTML

<table>
    <tr><th>Language</th><th>Text</th></tr>
    <tr><td>English</td><td>Hello, World!</td></tr>
    <tr><td>French</td><td>Bonjour, le monde!</td></tr>
    <tr><td>Portuguese</td><td>Olá, Mundo!</td></tr>
    <tr><td>Serbian</td><td>Zdravo, svete!</td></tr>
</table>

Cada fila está encerrada entre etiquetas table row <tr> y </tr>. Dentro de una fila, las etiquetas <th> y </th> se utilizan para contener tables headings (celdas especiales de la tabla que aparecen en negrita), mientras que las celdas de tables de datos normales están contenidas dentro de las etiquetas <td> y </td>.

Un ejemplo similar escrito utilizando listas HTML tendría el siguiente aspecto: Ejemplo de lista HTML

HTML

<ul>
    <li>English: Hello, World!</li>
    <li>French: Bonjour, le monde!</li>
    <li>Portuguese: Olá, Mundo!</li>
    <li>Serbian: Zdravo, svete!</li>
</ul>

Aquí, usamos etiquetas unordered list <ul> y </ul> para definir una lista con 4 elementos, cada uno a su vez envuelto en etiquetas individuales list item (<li> y </li>).

Sitios estáticos vs dinámicos

Las páginas estáticas son aquellas cuyo contenido se almacena en un servidor en un estado listo para ser enviado a cualquier usuario que haga una petición para esa página web. Cuando se realiza una petición, el servidor sólo tiene que enviar la información que compone esa página web (como HTML y CSS). Los sitios que no cambian a menudo, como un sitio web que contiene el currículum de una persona, suelen almacenarse como sitios estáticos.

Por el contrario, los sitios dinámicos son aquellos cuyas páginas se generan cuando un usuario solicita una página web. Dependiendo del momento en que se realice la solicitud, el contenido puede cambiar; por ejemplo, si se hace clic en actualizar al ver un debate en un foro web, pueden aparecer nuevos comentarios. La diferencia clave es que las páginas estáticas sólo necesitan generarse una vez, tras lo cual permanecen sin cambios en el servidor, en comparación con las páginas dinámicas, que son regeneradas por un servidor cada vez que recibe una petición.

Ejemplos en el ámbito de las Ciencias de la Vida

Un ejemplo típico de sitio web estático en el campo de las Ciencias de la Vida sería la documentación de una herramienta o un formato de archivo, como esta página en wwpdb.org.

Las páginas de entrada de la base de datos PDB, en cambio, cargan el contenido de forma diferente en función de las herramientas de visualización y las opciones elegidas por el usuario. Una base de datos o un servidor web suele ser un sitio web dinámico.

Esta lección se centra en los sitios estáticos y en las herramientas que se pueden utilizar para crearlos, conocidas como Generadores de sitios estáticos.

Una de las ventajas de utilizar generadores de sitios estáticos es que eliminan la necesidad de producir manualmente una gran cantidad de HTML, lo que nos permite centrarnos en el contenido legible por humanos que queremos que contengan nuestras páginas. Sin embargo, aún necesitamos una forma de decirle al generador cómo queremos que se vea nuestro contenido cuando se muestre en el navegador. Para ello, utilizaremos una herramienta llamada Markdown, sobre la que aprenderemos en un siguiente episodio.

Las páginas pueden crearse de varias maneras: generación estática del lado delservidor (donde el HTML se genera una vez en el servidor y no cambia a partir deentonces), generación dinámica del lado del servidor (donde el servidor puede actualizary enviar nuevo HTML basándose en las peticiones del navegador del usuario), y generacióndel lado del cliente (donde partes de las páginas HTML son generadas por el navegadorusando código Javascript)

Figura 1.1: Alternativas de generación de páginas. Esta figura es una versión modificada de la original publicada en JavaScript for Data Science, y se reproduce aquí con permiso del autor.

Los sitios generados estáticamente son una buena opción cuando la información que se quiere mostrar en un sitio web es la misma independientemente de quién lo visite y cuándo, y si es poco probable que el contenido de las páginas tenga que cambiar muy a menudo. Esto hace que los generadores de sitios estáticos sean una buena opción para sitios que ofrecen documentación o contenido didáctico, como esta página: el objetivo de la página es ofrecer la misma información a todos los visitantes. El visitante puede llegar, (con suerte) encontrar y leer lo que necesita, y marcharse sintiéndose feliz y satisfecho.

Los sitios dinámicos ofrecen muchas más posibilidades de interactividad y contenidos personalizados o de actualidad. Pero su creación es mucho más complicada y supone una carga adicional considerable para el servidor, sobre todo en términos de requisitos informáticos y consideraciones de seguridad. Entre otras cosas, esto significa que, a diferencia de lo que ocurre con las páginas estáticas (véase el resto de esta lección), es poco probable que encuentre plataformas gratuitas que le ayuden a ofrecer contenidos dinámicos.

Ejercicio: La herramienta perfecta para el trabajo

Dados los siguientes tipos de sitios web, razona si un generador de sitios estáticos es una solución adecuada para implementarlos.

1. Un sitio web personal con las secciones Acerca de y *Proyectos
1. Un foro o plataforma de debate
1. Un blog comunitario o sitio web de noticias
1. Un motor de búsqueda (como google.com)
1. Un wiki (como wikipedia.com)
1. Un libro en línea

Solución

sitio web personal: En la mayoría de los casos, Sí. Este tipo de contenido suele ser escrito/editado por una sola persona y destinado a tener un acceso de sólo lectura para los visitantes.

foro o discusión: Lo más probable es que No. Un sitio web de este tipo requiere interactividad y formas de identificar quién escribió qué contenido.

Para las preguntas 3 y 5 la respuesta es tanto Sí como No dependiendo de los requisitos y la funcionalidad necesaria.

blog/noticias: Un blog sencillo o un sitio web de noticias, mantenido por un pequeño grupo de usuarios, es perfectamente realizable utilizando un generador estático. Para grupos muy numerosos de creadores de contenidos o si es necesario controlar individualmente el acceso a los artículos, el uso de un generador estático planteará difíciles problemas técnicos.

motor de búsqueda: La mayoría de las veces No. Implementar algo tan sofisticado como la búsqueda de Google sería casi imposible con un generador estático. Hay formas de tener un motor simple que busque en todas las páginas producidas por un generador estático utilizando la indexación y haciendo un uso inteligente de las características del navegador, pero este enfoque tiene muchas limitaciones.

wiki: Un wiki sencillo es perfectamente factible con un generador estático (por ejemplo, GitHub Wiki Pages), sin embargo se vuelve limitante en cuanto su contenido necesita ser editado o discutido por muchos usuarios, como es el caso de Wikipedia.

libro en línea: Definitivamente Sí. Los generadores estáticos son perfectos para este tipo de sitios web. Normalmente proporcionan formas de evitar la repetición de contenido (variables y plantillas), creación automática de una Table Of Contents, entre otras bondades.

GitLab pages

Si el sitio que quieres crear se ajusta bien a los puntos fuertes de un generador de sitios estáticos -es relativamente pequeño, se actualizará con poca frecuencia, y el contenido no necesita ser personalizado para el visitante - entonces crearlo con GitLab Pages es una buena opción. GitLab Pages es un sistema que permite a los usuarios crear y servir sitios web directamente desde sus repositorios de GitLab. El servicio es gratuito para los repositorios públicos y se pueden crear y servir páginas sencillas con muy poca configuración.

Pasaremos por una lista de plantillas, de complejidad creciente. Mientras que las primeras se basarán en Markdown plano, las más avanzadas se basarán en múltiples tecnologías (en el diagrama siguiente se muestra un ejemplo). Puede parecer abrumador al principio, pero explicaremos la mayoría de estas tecnologías en esta lección - sólo no cubriremos CSS/Sass (lenguaje de estilo que se compila en CSS) y JavaScript/CoffeeScript (lenguaje de scripting que se compila en JavaScript) en detalle.

Static websites in GitHub Pages technology overview diagram

En primer lugar, vamos a configurar un proyecto para almacenar nuestros archivos y aprender más acerca de cómo crear y dar formato al contenido de nuestras páginas utilizando HTML y Markdown, antes de configurar GitLab para mostrar este contenido como un sitio web utilizando GitLab Pages.

Configurar un proyecto

Antes de ponernos manos a la obra debemos crear un proyecto en el que trabajar. Este proyecto es similar a una carpeta en su ordenador, las principales diferencias son que la carpeta vive en la web en GitLab / GitHub (aunque también puede mantener una copia en su ordenador si es necesario) y que la carpeta está utilizando un software de control de versiones llamado git para realizar un seguimiento de los cambios en los archivos. Para nuestros propósitos vamos a ignorar el software de control de versiones, aunque puede ser útil si necesitas volver a versiones antiguas (ver Software Carpentry - Version Control with Git para una introducción). En esta lección vamos a trabajar con esta carpeta en la web para controlar el sitio web que vamos a crear.

Accede a tu cuenta de GitLab

Antes de que pueda crear un repositorio, tendrá que iniciar sesión en el EMBL GitLab

Hay dos formas de crear un nuevo proyecto:

Haz clic en el botón “+” de la barra de navegación de la parte superior y elige “nuevo proyecto”

o, si estás en la página de proyectos, haz clic en el botón “Nuevo proyecto

Se le redirigirá a una página que ofrece tres opciones:

Crear proyecto en blanco
Crear a partir de plantilla
Importar proyecto Tómese su tiempo para leer las descripciones de los diferentes casos. Seleccione “Crear proyecto en blanco”.

A continuación tendrás que rellenar algunos datos sobre tu proyecto.

En esta lección, vamos a trabajar en un sitio web de grupo en general. Puedes imaginar que este sitio web puede ser para tu grupo de laboratorio, un grupo de proyecto específico u otro grupo con el que trabajes. En el campo “Nombre del proyecto”, escribe group-website.

El Project slug determinará la URL para acceder a tu proyecto y sitio web, se genera automáticamente cuando rellenas el campo Project name. Déjalo como está.

Eche un vistazo al menú desplegable situado junto al campo Project URL. La opción por defecto es su propio usuario, esto se refiere a su propio espacio de nombres. Otros espacios de nombres pueden estar disponibles, dependiendo de los grupos a los que pertenezcas. Por ejemplo, si se planea que este sea el sitio web de su grupo, puede ser una buena opción seleccionar el espacio de nombres de su grupo para alojarlo. Esto tanto para facilitar el acceso al proyecto a otros miembros del grupo como para tener tu nombre de grupo (y no tu nombre de usuario) en la URL del sitio web. Sin embargo, vamos a inicializar este proyecto de prueba en nuestro propio espacio de nombres.

También podemos añadir una descripción (por ejemplo, “Proyecto para aprender a hacer sitios web con GitLab pages”) para que sepamos qué es este proyecto cuando lo volvamos a encontrar después del taller.

También comprobaremos la opción Initialize repository with a README. Es una buena práctica tener un archivo README que da más información acerca de su repositorio.

GitLab vs GitHub

La mayoría de los pasos aquí descritos son muy similares en GitHub. Lo que GitLab llama “Proyecto”, en GitHub es un “Repositorio”, así que si tu instructor confunde los dos términos aquí está el porqué. Además, los “Grupos” son en GitLab “organizaciones”.

Más relevantes son las diferencias en cuanto al nivel de visibilidad y las opciones de configuración. En GitHub, sólo hay dos opciones disponibles para un repositorio: “Público” o “Privado”. GitLab del EMBL permite un ajuste más específico de los permisos a través de la opción “Interno”, es decir, accesible sólo por el usuario conectado. Por último, mientras que GitLab sólo permite inicializar el repositorio con un README, GitHub incluye la opción de inicializarlo también con un .gitignore y archivos de licencia.

Una vez que hayas terminado estos pasos puedes hacer clic en el botón Create Project. GitLab configurará el repositorio y debería crear el repositorio llamado group-website con un archivo README.md en él. Lo que la interfaz gráfica nos acaba de ayudar a hacer, son básicamente los siguientes pasos:

BASH

mkdir group-website
cd group-website
git init
cat > README.md
git add README.md
git commit -m "Initial commit"

En un servidor remoto. La rama por defecto es main.

Repositorio de Github para el sitio web del grupo

Antes de pasar al siguiente capítulo, echa un vistazo a los botones de la parte superior, como Add LICENSE, Add CHANGELOG etc., que te sugieren posibles pasos a seguir. Por nombrar uno, la Licencia es definitivamente algo que podrías querer incluir en tu proyecto. No vamos a examinar esto en detalle, pero tenga en cuenta que la licencia es una buena práctica (si no necesaria) para cualquier proyecto que incluya datos o software. Tu sitio web, aunque sea muy sencillo y estático, incluirá algún tipo de datos, aunque sólo sean nombres de personas. Las tecnologías y plantillas que utilizarás para generarlo son software. Un consejo.

Puntos Clave

Un generador de sitios estáticos combina contenido específico de cada página con elementos de diseño y estilos para construir páginas web individuales.
GitHub/GitLab Pages es una buena opción para personas que ya están familiarizadas con Git y GitHub/GitLab.
Este enfoque puede utilizarse para crear un sitio web o blog relativamente pequeño con un presupuesto limitado.

Content from Creación con Markdown

Última actualización: 2025-07-01 | Mejora esta página

Tiempo estimado: 0 minutos

Hoja de ruta

Preguntas

¿Cómo puedo escribir contenido para mi página web?
¿Cómo enlazo a otras páginas?

Objetivos

crear páginas simples de texto formateado

Markdown

Markdown es un lenguaje de marcado ligero, es decir, una convención para añadir información de estilo al contenido textual. Como su nombre indica, los elementos sintácticos de este lenguaje se reducen al mínimo. Al tener una sintaxis más bien minimalista, el texto formateado en Markdown es comparablemente legible. Esta puede ser una de las razones por las que Markdown se ha convertido en el lenguaje preferido para las entradas de usuario formateadas en sitios web como, por ejemplo:

¿Dónde empezar a escribir Markdown?

Existen muchas herramientas para renderizar código fuente Markdown. La renderización es el proceso de generar una vista agradable del contenido utilizando la información de estilo incluida en el texto fuente. Es muy probable que tu editor pueda hacerlo. Como estamos trabajando en la creación de sitios web utilizando páginas de GitLab, utilizaremos GitLab directamente para aprender los fundamentos de Markdown. El proyecto GitLab que creaste en el último episodio contiene un archivo README.md. Haz clic en el nombre del archivo para acceder a él.

La siguiente imagen muestra la vista por defecto. Esta vista incluye una vista renderizada del contenido dentro del archivo README.md, como la de la página principal de nuestro proyecto.

Los botones de la derecha permiten interactuar con el archivo y la visualización. El primer par de botones, los que tienen los iconos, le permiten cambiar entre Display source y Display rendered file. Pase con el ratón sobre ellos para mostrar estos dos mensajes en tooltips. La fuente es la vista no renderizada de nuestro archivo. Podemos editarla a través del botón azul Edit. Haga clic en él.

Interfaz de edición del archivo README de los sitios web degrupo

Podemos cambiar el contenido y echar un vistazo a la vista renderizada haciendo clic en la pestaña Preview de la parte superior.

Vista previa del contenido renderizado del archivo README de los sitios web delgrupo

Añadamos Some **bold** font y veamos qué pasa cuando lo previsualizamos usando la pestaña de previsualización. ¿Qué ha pasado con la negrita del mundo?

Para guardar el contenido en el archivo README.md, debemos hacer clic en el botón Commit changes en la parte inferior de la página. Atención: no se trata de un simple botón de “Guardar”, sino de un commit real. Esta versión del proyecto se almacenará en git con el Commit message que especificaremos en el menú de commit aquí y en la rama que establezcamos como Target branch. Sólo tenemos la rama principal por el momento - por lo que la elección es obvia - y el mensaje de confirmación está precompilado con el nombre del archivo que acabas de editar. Es posible que desee ser más específico en su mensaje de confirmación, pero por el momento vamos a ir con la opción por defecto proporcionada. Confirme este cambio.

Escribiendo un mensaje de confirmación

Un mensaje de confirmación es un comentario corto, descriptivo y específico que nos ayudará a recordar más tarde qué hicimos y por qué. Encontrarás más información sobre cómo escribir un mensaje de confirmación en esta sección de la lección de Git-novice.

La interfaz te redirige a la página principal del proyecto. En la parte superior, un mensaje dice “Your changes have been successfully committed” Nuestros cambios fueron incluidos en el archivo README, que ahora muestra la segunda línea con la fuente en negrita.

Escribiendo Markdown

Ahora que ya conocemos la interfaz de edición y la pestaña de vista previa de nuestros proyectos README.md podemos utilizarlo como editor de texto e investigar algunas características de Markdown.

Nuestro README.md ya contiene texto y dos funciones de formato:

Encabezado # group-website
Énfasis usando **bold**.

Aprendamos un poco más de Markdown añadiendo algo de formato y veamos qué ocurre cuando lo previsualizamos usando la pestaña de previsualización. Añade lo siguiente a tu archivo README.md.

MARKDOWN

# group-website
Repo for learning how to make websites with GitLab pages

## Learning Markdown

Vanilla text may contain *italics* and **bold words**.

This paragraph is separated from the previous one by a blank line.
Line breaks
are caused by two trailing spaces at the end of a line.

[Carpentries Webpage](https://carpentries.org/)

### Carpentries Lesson Programs:
- Software Carpentry
- Data Carpentry
- Library Carpentry

A continuación, puedes volver a hacer clic en la pestaña de vista previa para ver cómo se muestra el formato.

Vista previa del formato añadido al README

Los espacios finales de Markdown son significativos

En el ejemplo anterior hay dos espacios al final de Line breaks. Estos introducen lo que se llama un salto de línea duro, haciendo que ese párrafo continúe en la siguiente línea añadiendo un <br/> al HTML generado.

Si rompes la línea en un archivo markdown pero no incluyes los dos espacios finales, el HTML generado continuará en la misma línea sin introducir un <br/>. Esto se denomina salto de línea suave.

En algunos casos puedes encontrar que los saltos de línea suaves introducen un <br/>. Esto puede ocurrir cuando se utilizan diferentes sabores markdown. {: .language-markdown }

Puedes confirmar estos cambios para guardarlos. Pero primero, vamos a hacer un ejercicio para probar a escribir más markdown.

Ejercicio: Probar Markdown

Usa this cheatsheet para añadir lo siguiente a tu README.md:

Otro encabezado de segundo nivel
Algún texto bajo ese encabezado de segundo nivel que incluye un enlace y texto ~~tachado~~.
Un encabezado de tercer nivel
Una lista numerada
Bonus: Añadir esta imagen https://github.com/carpentries/carpentries.org/blob/main/images/TheCarpentries-opengraph.png

Ejemplo de solución

Por ejemplo, tu markdown podría tener el siguiente aspecto:

MARKDOWN

## More info on the lesson
You can find this lesson [here](https://grp-bio-it-workshops.embl-community.io/building-websites-with-gitlab/).

### Four reasons you should learn Markdown:

1. Less formatting than HTML
2. Easy to read even with formatting
3. Commonly used for websites and software development
4. We ~~don't~~ use it in The Carpentries

![Carpentries Logo](https://github.com/carpentries/carpentries.org/raw/main/images/TheCarpentries-opengraph.png)

Enlaces de estilo de referencia

Hasta ahora, hemos utilizado enlaces inline-style que tienen la URL en línea con el texto de la descripción, por ejemplo:

MARKDOWN

[Carpentries Webpage](https://carpentries.org/)

Si utilizas un enlace más de una vez, considera la posibilidad de utilizar los llamados enlaces de estilo referencia. Los enlaces de tipo referencia hacen referencia a la URL mediante una etiqueta. La etiqueta va entre corchetes [ ] justo después del texto de descripción del enlace y después, normalmente al final de la página, puede conectar esa etiqueta a la url a la que hace referencia para completar el enlace. Esto se parece a:

MARKDOWN

[Carpentries Webpage][carpentries]

[carpentries]: https://carpentries.org/

Seguiremos utilizando Markdown y aprendiendo más a lo largo del resto de la lección. Tanto si decides estructurar tu sitio web mediante tecnologías basadas en Markdown como en HTML, seguirás necesitando conocer algunos conceptos básicos de Markdown para editar tu archivo README. El archivo README proporcionará una guía esencial -que se mostrará en la página de inicio de tu proyecto- para tus colaboradores y también para que tú entiendas de qué trata el proyecto y cómo contribuir.

Sabores de Markdown

La descripción inicial de Markdown era informal y contenía ciertas ambigüedades, por lo que a lo largo de los años aparecieron diferentes implementaciones de Markdown y variaciones sintácticas (a menudo denominadas “sabores”) para soportar diversas características y extensiones sintácticas. Como consecuencia, la sintaxis de una variante puede no interpretarse como se espera en otra - hay que ser consciente de cuál está siendo utilizada por una plataforma concreta. Estas son algunas de las variantes más conocidas:

GitLab-flavored Markdown (utilizado en esta lección y por GitLab)
GitHub-flavored Markdown (utilizado por GitHub)
Kramdown (una implementación rápida, en Ruby y de código abierto publicada bajo la licencia MIT)

Mardown es también el lenguaje de la plataforma de notas colaborativas disponible en el EMBL. Puede acceder a ella aquí. La plataforma está basada en CodiMD.

Ejercicio: Añade los detalles de tu repositorio a CodiMD

Utiliza la sintaxis Markdown para añadir un enlace en el documento de notas colaborativas que estás utilizando para seguir esta lección. El texto del enlace debe ser tu nombre de usuario de GitLab, y el objetivo tu repositorio.

Puntos Clave

Markdown es una forma relativamente sencilla de escribir texto con formato
Se pueden usar etiquetas Markdown y HTML juntas en una misma página
Recomiendo escribir los enlaces en Markdown con el estilo de referencia
La página de inicio de un sitio web se nombra convencionalmente como index.md

Content from Alojar páginas en GitLab

Última actualización: 2025-07-01 | Mejora esta página

Tiempo estimado: 0 minutos

Hoja de ruta

Preguntas

¿Cómo publicio mis páginas via GitLab?

Objetivos

publicar HTML en la red con GitLab Pages

PGitLab pages

Sólo sitios web estáticos

Como se anticipó en los capítulos anteriores, para publicar un sitio web con GitLab Pages puedes utilizar varias tecnologías diferentes como Jekyll, Gatsby, Hugo, Middleman, Harp, Hexo, y Brunch, sólo por nombrar algunas. También puedes publicar cualquier sitio web estático escrito directamente en HTML plano, CSS y JavaScript. Pages no soporta el procesamiento dinámico del lado del servidor, por ejemplo, como requieren .php y .asp.

La clave para que tu sitio web funcione como se espera es el archivo de configuración de GitLab CI, llamado .gitlab-ci.yml. Este archivo configura cómo se construirá tu sitio web. Está escrito en YAML, que tiene su propia sintaxis que no explicaremos en detalle, por lo que te recomendamos que sigas esta guía de inicio rápido antes de configurarlo. Para que funcione correctamente, debe colocarse en su directorio raíz, es decir, al mismo nivel que nuestro archivo README, en la carpeta principal del proyecto.

El hecho más importante es que con GitLab CI, tomas el control sobre tus compilaciones. No estarán en una caja negra invisible donde no sabes lo que está pasando Serás capaz de ver cualquier compilación ejecutándose en vivo navegando a la Pipelines de tu proyecto (lo haremos más adelante). También puedes añadir cualquier comando a tu script .gitlab-ci.yml. Esto le permite hacer en el servidor remoto prácticamente cualquier cosa que haga en su máquina local. Más adelante veremos algunos ejemplos de cómo ejecutar comandos de construcción personalizados a través del archivo .gitlab-ci.yml..

Trabaja localmente o en GitLab

Esta lección no pretende enseñar Git y cómo trabajar localmente (en tu portátil) en un proyecto versionado y gestionado en Git. Sin embargo, si tienes una comprensión básica de Git, puedes hacer los siguientes pasos localmente para aprender a desarrollar correctamente un sitio web: probarlo localmente y sólo confirmar y empujar versiones significativas del mismo. Por el contrario, trabajar en la plataforma en línea nos obligará a cometer versiones que no serán muy significativas, en aras del aprendizaje.

Si usted tiene una comprensión básica de Git, la configuración de un proyecto local para el despliegue. Clone su repositorio localmente (consulte la lección git novice si necesita repasar lo que hace el comando git clone y cómo git push cambios de proyectos locales a remotos). En resumen, ahora deberías ejecutar, desde un terminal:

BASH

git clone https://git.embl.de/<your username>/group-website.git
cd group-website

Y sigue trabajando en tu directorio clonado. Puedes añadir y editar tus archivos a través de vim o desde cualquier editor que te guste - no tiene que ser lanzado desde el terminal, pero recuerda mantener el terminal abierto para cuando tengas que empujar los cambios de nuevo al remoto.

Empezaremos con el ejemplo más simple, un sitio HTML plano con páginas GitLab.

Vamos a crear el archivo .gitlab-ci.yml directamente en nuestro proyecto GitLab online. Tendremos que trabajar en varios archivos. Para ello, queremos abrir el IDE Web haciendo clic en el botón en la parte superior derecha de nuestro proyecto: Edit > Web IDE.

Si es la primera vez que lo abre, aparecerá un panel de personalización. Ignórelo por ahora, pero sepa que el look-and-feel de las siguientes capturas de pantalla puede diferir de lo que ve basado en la plantilla por defecto. Sin embargo, deberías tener los mismos menús y archivos disponibles para su uso. En particular, el EXPLORER (un explorador de archivos) a la derecha lista los archivos y carpetas de su repositorio (por el momento, sólo debería haber el archivo README), y el panel de la derecha muestra el contenido de dichos archivos cuando los abre.

Pasa el ratón por encima del nombre de tu proyecto en la carpeta EXPLORER para ver un pequeño menú que incluye un icono para añadir archivos a la carpeta. Haga clic en él y cree un archivo .gitlab-ci.yml. A continuación, rellénalo con el siguiente contenido

Crea tu fichero .gitlab-ci.yml y escribe en él:

YAML

pages:
  stage: deploy
  script:
    - echo 'Nothing to do...'
  artifacts:
    paths:
      - public
  only:
    - main

Lo que hace este código es crear un trabajo llamado “pages” que le dice a GitLab que despliegue el contenido del sitio web en public, siempre que se envíe un commit y sólo a la rama principal. No tiene mucho que hacer más que mirar el contenido en público, de ahí que la configuración del “script” sea básicamente ninguna (sólo hace eco de “Nada que hacer” en el terminal).

Validando el archivo gitlab-ci.yml

Antes de añadir cualquier .gitlab-ci.yml a su proyecto, puede validar su sintaxis con la herramienta llamada CI Lint. Necesitas estar conectado a tu cuenta para tener acceso a esta herramienta. Se encuentra navegando a los Pipelines de tu proyecto: hay un botón en la parte superior derecha de tu pantalla. Puedes leer la documentación completa de .gitlab-ci.yml para más información.

Ramas Git y archivos GitLab CI

Puedes tener un .gitlab-ci.yml distinto para cada proyecto - pero incluso podrías tener distintas configuraciones de GitLab CI para cada rama. Esto significa que podrías probar tu script en ramas paralelas antes de enviarlo a tu rama principal. Si la compilación tiene éxito, se fusiona. Si no, puedes hacer ajustes y tratar de construir de nuevo sin estropear tu rama principal.

A continuación, crearemos la carpeta public (usa el icono de nueva carpeta en el menú EXPLORER), que contiene un archivo index.html.

Trabaja localmente o en GitLab

Si estás trabajando en local, puedes hacerlo desde el terminal a través de:

BASH

mkdir public
cat > public/index.html

Rellena el nuevo fichero index.html con este contenido:

HTML

<html>
    <head>
        <title>Home</title>
    </head>
    <body>
        <h1>Hello World!</h1>
    </body>
</html>

Antes de seguir con el capítulo, intenta imaginar cuál será la visualización final en la página web resultante. Puedes dibujarlo en un papel.

Trabaja localmente o en GitLab

Si estás trabajando localmente, ahora confirma y envía tus cambios. Puedes hacerlo desde la carpeta principal del proyecto a través de:

BASH

git add .
git commit -m "simple html in public"
git push -u origin main

Si has creado el archivo .gitlab-ci.yml, y la carpeta public que contiene el archivo index.html, deberías verlos todos en la carpeta EXPLORER. Ahora, vamos a guardar la primera versión de nuestro proyecto (commit), seleccionando el menú Source control en el lado izquierdo.

Esto cambiará el panel de la izquierda, que listará los archivos que hemos cambiado (dos archivos añadidos) y esperará que introduzcas un mensaje de confirmación (una breve descripción de la versión del proyecto que estás confirmando) en el cuadro de texto de arriba. Nuestro mensaje de confirmación en este caso podría ser: “Deploy simple HTML through GitLab pipeline”. Introduzca este u otro mensaje, y luego Commit to 'main'.

Vuelve a tu proyecto remoto en GitLab. La siguiente captura de pantalla muestra cómo debería verse:

Captura de pantalla del proyecto HTML simple

La carpeta public contiene el archivo index.html. El comando push que acabas de lanzar debería haber activado tu primer pipeline. En el menú de la izquierda, seleccione Build > Pipelines para visualizarlo.

Desde que nos detuvimos y comprobamos cómo era nuestra carpeta remota, puede que tu pipeline ya esté passed . Si no es así, espera a que lo sea.

¡Tu primer sitio web ha sido desplegado con éxito! ¿Te preguntas dónde puedes verlo? Vaya a Deploy > Pages. La URL de su sitio web se informa allí. Debería ser: https://<your user name>.embl-community.io/group-website.

La URL de la página en Configuración>Páginas

La siguiente captura de pantalla también contiene una alerta interesante. Lee siempre este tipo de mensajes que muestra la interfaz de GitLab, suelen ser relevantes para ti. Dice “El control de acceso está habilitado para este sitio web de Pages; sólo los usuarios autorizados podrán acceder a él. Para hacer que tu sitio web esté disponible públicamente, navega a Configuración > General > Visibilidad de tu proyecto y selecciona Todos en la sección de páginas.” También enlaza con más documentación si quieres saber más. Sigue las instrucciones si quieres hacer pública tu página web.

Sea pública o no, deberíamos poder visualizar nuestra propia web. Pincha en el enlace, y aquí lo tienes:

Ejercicio: Compara con tu boceto

¿Tiene el sitio web que acabas de desplegar el aspecto que pensabas que tendría, dado el código html del archivo index? ¿Pensabas que se mostraría otra cosa? Coméntalo con el compañero que tienes al lado.

Ejercicio: La plantilla plain-html

GitLab proporciona una serie de plantillas de páginas web desplegadas a través de Pages. Una de ellas se llama “plain-html”, puedes acceder a ella en este enlace. La estructura general es bastante similar a la que acabamos de utilizar. Vaya a la carpeta public. Aquí hay dos archivos, uno style.css y otro index.html.

Entraremos en detalle en el funcionamiento del archivo .css en esta lección, pero puede ser interesante ahora echar un vistazo a su sintaxis y contenido. Este tipo de archivo se utiliza para dar estilo al contenido HTML. Este archivo específico proporciona instrucciones de estilo para tres elementos: el body, el navbar y el texto del enlace (a) dentro de la barra de navegación, que cambia de color cuando el ratón está sobre él (a:hover). No te preocupes ahora por entender cómo funciona esto exactamente, pero cuando vayas a visualizar esta página, recuerda pasar el ratón por encima de los enlaces de la navbar para ver esto en acción.

Ahora abre el archivo index.html. Su contenido se muestra a continuación.

HTML

<!DOCTYPE html>
<html>
 <head>
   <meta charset="utf-8">
   <meta name="generator" content="GitLab Pages">
   <title>Plain HTML site using GitLab Pages</title>
   <link rel="stylesheet" href="style.css">
 </head>
 <body>
   <div class="navbar">
     <a href="https://pages.gitlab.io/plain-html/">Plain HTML Example</a>
     <a href="https://gitlab.com/pages/plain-html/">Repository</a>
     <a href="https://gitlab.com/pages/">Other Examples</a>
   </div>

   <h1>Hello World!</h1>

   <p>
     This is a simple plain-HTML website on GitLab Pages, without any fancy static site generator.
   </p>
 </body>
</html>

¡Es hora de dibujar de nuevo! Dibuja la página web resultante, siempre que el contenido de este archivo HTML. Pista: la navbar es una barra en la parte superior de la página, que nos permite navegar por el contenido de la web.

Pregunta opcional: ¿cómo se utiliza el archivo .css? ¿Cómo sabe el sitio web cuál es el archivo correcto que debe leer?

Solución

Puedes ir al sitio web desplegado para comprobar cómo queda. A continuación se muestra una captura de pantalla del resultado:

¿Hay alguna diferencia con tu boceto?

Pregunta opcional: la ubicación del fichero .css está especificada en el fichero .html, a través de: <link rel="stylesheet" href="style.css">.

Enlaces útiles

Ya tienes las herramientas mínimas para poder jugar con HTML y css. Puedes copiar los dos archivos del último ejercicio template en tu repositorio e intentar editar el tamaño del texto, el color de la barra de navegación, añadir enlaces o el formato del texto. Si decides hacer un fork de este repositorio para experimentar, por favor, haz lo que los autores piden en su archivo README (una razón más para consultar los archivos README de cada uno de los otros proyectos y compilarlos cuidadosamente): “Si ha bifurcado este proyecto para su propio uso, por favor vaya a Settings de su proyecto y elimine la relación de bifurcación, lo cual no será necesario a menos que quiera contribuir de nuevo al proyecto upstream.”

En w3schools se puede encontrar un extenso tutorial sobre elementos HTML, que incluye ejemplos de incrustación de formularios, medios y enlaces. Además de éste, muchos otros recursos proporcionan tutoriales de HTML, sin duda puedes elegir uno que se adapte a tus gustos para aprender más.

Puntos Clave

GitLab sirve páginas en tu proyecto concorde a tu fichero de configuración llamado .gitlab-ci.yml

Content from Páginas GitLab con Jekyll

Última actualización: 2025-07-01 | Mejora esta página

Tiempo estimado: 0 minutos

Hoja de ruta

Preguntas

¿Cómo publico páginas web via GitLab y Jekyll?

Objetivos

Publicar ficheros Markdown como HTML en la red con GitLab Pages

Jekyll es un potente generador de sitios estáticos que puede estar detrás de GitLab Pages. Crea contenido HTML estático para sitios web a partir de varios archivos de tu repositorio (archivos Markdown, hojas de estilo CSS, plantillas/diseños de página, etc.). Este contenido ‘compilado’ es luego servido como tu sitio web.

Jekyll facilita la gestión de su sitio web porque depende de plantillas. Las plantillas (o diseños en notación Jekyll) son planos que pueden ser reutilizados por múltiples páginas. Por ejemplo, nosotros (tus instructores) no hemos dado estilo a cada uno de los ejercicios de esta lección por separado: hemos creado una plantilla que especifica cómo deben mostrarse los ejercicios (el cuadro naranja, el cuadro de solución desplegable, etc.) y cada vez que etiquetamos un bloque de texto como “Ejercicio” se muestra de esta manera.

Cubriremos los diseños de Jekyll en un momento; por ahora empecemos a aprender Jekyll y su lenguaje de scripting llamado Liquid.

Parámetros globales

También en este caso, activaremos y personalizaremos nuestro despliegue desde el archivo .gitlab-ci.yml. Puedes decidir editar tu versión anterior del repositorio group-website, pero te sugerimos crear uno nuevo. Siga los pasos en “Configuración de un proyecto” en la introducción si desea hacerlo. Crea/cambia el contenido del fichero .gitlab-ci.yml con:

YAML

image: ruby:latest

pages:
  script:
    - gem install bundler
    - bundle install
    - bundle exec jekyll build -d public
  artifacts:
    paths:
      - public
  only:
    - main

Este código requiere que el script se ejecute en el entorno de la última versión de Ruby, instala la gema Jekyll, y construye el sitio en la ruta pública (creando la carpeta remotamente, no debes preocuparte por ello en este punto). El resultado afecta sólo a la rama principal.

La ejecución de este pipeline también requiere un Gemfile. Créelo en la carpeta raíz con el siguiente contenido:

source "https://rubygems.org"

gem "jekyll"

En resumen, pero lo veremos con más detalle, Jekyll busca archivos de texto que empiecen con una cabecera formateada así:

---
variable: value
other_variable: other_value
---

...stuff in the page...

e inserta los valores de esas variables en la página al formatearla. Los tres guiones que comienzan la cabecera deben ser los tres primeros caracteres del archivo: incluso un solo espacio antes de ellos hará que Jekyll ignore el archivo.

El contenido de la cabecera debe estar formateado como YAML, y puede contener booleanos, números, cadenas de caracteres, listas y diccionarios de pares nombre/valor. Los valores de la cabecera se denominan en la página page.variable. Por ejemplo, esta página:

---
name: Science
---
{% raw %}Today we are going to study {{page.name}}.{% endraw %}

se traduce como:

HTML

<html>
  <body>
    <p>Today we are going to study Science.</p>
  </body>
</html>

:::::::::::::::::::::::::::::::::::::: challenge

Ejercicio: Sintaxis de Jekyll

Pon a prueba tu comprensión de la sintaxis de Jekyll. ¿A qué se traduciría esta plantilla?

---
name: Tom
location: Heidelberg
---
{% raw %}{{page.name}} is in {{page.location}}. I believe {{page.location}} is a very nice city.{% endraw %}

Solución

HTML

<html>
  <body>
    <p>Tom is in Heidelberg. I believe Heidelberg us a very nice city.</p>
  </body>
</html>

::::::::::::::::::::::::::::::::::::::::::::::::::

Sin embargo, las principales opciones de configuración de Jekyll se especifican en otro fichero, llamado _config.yml. Vamos a crear algunos parámetros de configuración para nuestro sitio web.

Cree un archivo _config.yml en el directorio raíz de su sitio.
Añádele los parámetros description y email como:

YAML

description: This project develops training materials for reseachers wanting to learn to build project
websites in GitLab Pages.
email: team@carpentries.org

Los parámetros de configuración global de _config.yml están disponibles como variable site.PARAMETER_NAME en cada página dentro del sitio web. Por lo tanto, el parámetro global email que definimos anteriormente sería accesible como site.email. Nota: estos son parámetros globales, por lo tanto diferentes de los parámetros locales específicos de la página en los ejemplos anteriores.

Para acceder al valor del parámetro dentro de una página, se utiliza la notación de Liquid para mostrar el contenido rodeando una variable entre llaves como {% raw %}{{ variable }}{% endraw %}.

Parámetros globales predefinidos

Además de los parámetros globales que defina, Jekyll también pone a su disposición una serie de útiles variables predefinidas para todo el sitio dentro de su sitio web: por ejemplo {% raw %}{{ site.time }}{% endraw %} (la hora actual) o {% raw %}{{ site.pages }}{% endraw %} (una lista de todas las páginas).

Cree un archivo index.md en la carpeta raíz, con el siguiente contenido:

MARKDOWN

{% raw %}---
title: My first Jekyll page
---{% endraw %}

# Building Websites with Jekyll and GitLab

## Description
{% raw %}{{ site.description }}{% endraw %}
Welcome to {% raw %}{{ page.title }}{% endraw %}

Have any questions about what we do? [We'd love to hear from you!]({% raw %}mailto:{{ site.email }}{% endraw %})

Tu proyecto debe incluir los siguientes archivos:

Confirme y envíe sus cambios, después monitorice la ejecución del proceso y compruebe el resultado final en su URL https://<your user name>.embl-community.io/group-website.

Ejercicio: Crear un parámetro global de Twitter

En about.md tenemos una URL de Twitter bajo la sección Contacta con nosotros. Esa es una pieza de información que podría ir en los parámetros globales en _config.yml ya que es posible que desee repetirlo en un pie de página de cada página. Realice cambios en su sitio web para extraer la URL de Twitter como parámetro global.

Solución

Añade el parámetro twitter a _config.yml:

YAML

description: "This research project develops training materials for reseachers wanting to learn to build project
websites in GitHub with GitHub Pages."
email: "team@carpentries.org"
twitter: "https://twitter.com/thecarpentries"

Hacer uso del parámetro twitter en about.md:

MARKDOWN

# About

## Project

{% raw %}{{ site.description }}{% endraw %}

## Funders

We gratefully acknowledge funding from the XYZ Founding Council, under grant number 'abc'.

## Cite us

You can cite the project as:

> *The Carpentries 2019 Annual Report. Zenodo. https://doi.org/10.5281/zenodo.3840372*

## Contact us

- Email: [{% raw %}{{ site.email }}{% endraw %}](mailto:{% raw %}{{ site.email }}{% endraw %})
- Twitter: [{% raw %}{{ site.twitter }}{% endraw %}]({% raw %}{{ site.twitter }}{% endraw %})

Ten en cuenta que en realidad no deberías ver ningún cambio en tu sitio web. Sin embargo, ahora puede acceder a su URL de Twitter desde cualquier página del sitio web, en caso de que lo necesite.

Parámetros locales

Además de los parámetros globales (para todo el sitio) disponibles a través de la variable global site, Jekyll pone a su disposición información local (específica de la página) a través de la variable page. Algunos de estos parámetros están predefinidos - como page.title, que te da el título de la página que está actualmente activa/visitándose. Otras puede definirlas usted mismo. Consulte esta lista de parámetros de página predefinidos.

Puede definir parámetros locales utilizando notación YAML dentro de una página Markdown incluyéndola en una cabecera de página y delimitando la cabecera con líneas discontinuas triples ---. Estas cabeceras se llaman front matter y se usan para establecer variables y metadatos en páginas individuales de tu sitio Jekyll.

Portada

Del sitio web de Jekyll:

Cualquier archivo que contenga un bloque YAML front matter será procesado por Jekyll como un archivo especial. El front matter debe ser lo primero en el archivo y debe tener la forma de un conjunto YAML válido entre líneas discontinuas triples.

Los parámetros globales y locales distinguen entre mayúsculas y minúsculas

Es importante tener en cuenta que los parámetros utilizados en los sitios distinguen entre mayúsculas y minúsculas. Por convención, suelen ir todos en minúsculas.

He aquí un ejemplo:

YAML

---
layout: post
title: "My first blog post"
author: "Danger Mouse"
---

Entre estas tres líneas discontinuas, puedes sobrescribir variables predefinidas (como page.layout o page.title) o crear las que necesites localmente en la página (como page.author). Podrá acceder a estas variables utilizando las etiquetas de Liquid (por ejemplo, {% raw %}{{{% endraw %} page.title {% raw %}}}{% endraw %} ) más abajo en el archivo y también en cualquier archivo que incluya éste. Tenga en cuenta que estas variables sólo son accesibles en esa página. Obtendrá un error si intenta hacer referencia a una page.variable definida en una página diferente.

Ejercicio: Practica con Variables Locales

Practiquemos la creación y el uso de variables locales. Piensa en una variable local que quieras utilizar sólo en tu página about.md o index.md. Si no se te ocurre ninguna, crea una variable local llamada lección-ejemplo con el valor https://carpentries.github.io/lesson-example/ y haz referencia a ella en tu index.md.

¿Qué has añadido a tu index.md para crear esta variable? ¿Dónde añadiste la materia prima en tu index.md? ¿Cómo hiciste referencia a esa variable?

Solución

Cree una cabecera YAML en la parte superior de index.md y añada la variable lesson-example entre los delimitadores de triple guión. A continuación, puede hacer referencia al valor dentro de su página index.md como {% raw %}{{{% endraw %} page.lesson-example {% raw %}}}{% endraw %}. Su archivo debería tener ahora el siguiente aspecto:
MARKDOWN
---
lesson-example: "https://carpentries.github.io/lesson-example/"
---

# Building Websites in GitHub

## Description
{% raw %}{{ site.description }}{% endraw %}

More details about the project are available from the [About page](about).

See some [examples of our work]({% raw %}{{{% endraw %} page.lesson-example {% raw %}}}{% endraw %}).

Have any questions about what we do? [We'd love to hear from you!]({% raw %}mailto:{{ site.email }}{% endraw %})
Tenga en cuenta que esta variable no es accesible desde la página about.md y es local a index.md.

Añadir nuevas páginas

El siguiente paso será crear otra página de este sitio web. Idealmente, nuestro sitio web tendrá múltiples páginas y por lo tanto, para mantener las cosas en orden, crearemos la carpeta pages para almacenarlas. En esta carpeta, cree un archivo about.md con el siguiente contenido:

MARKDOWN

{% raw %}---
title: About
permalink: /about/
---{% endraw %}

# About

## Project

{% raw %}{{ site.description }}{% endraw %}

## Funders

We gratefully acknowledge funding from the XYZ Founding Council, under grant number 'abc'.

## Cite us

You can cite the project as:

>    *The Carpentries 2019 Annual Report. Zenodo. https://doi.org/10.5281/zenodo.3840372*

## Contact us

- Email: [{% raw %}{{ site.email }}{% endraw %}](mailto:{% raw %}{{ site.email }}{% endraw %})
- Twitter: [@thecarpentries](https://twitter.com/thecarpentries)

Observe que la dirección URL de esta página se especifica en la cabecera, mediante el atributo permalink.

Este es el aspecto actual de sus carpetas:

Ahora, debemos editar el archivo index.md para incluir un enlace a esta nueva página acerca de, con el fin de ser capaz de llegar a ella desde la página principal. Añade una línea en index.md para incluir:

MARKDOWN

More details about the project are available from the [About page](about).

El enlace en esta línea redirigirá a https://<your user name>.embl-community.io/group-website/about, que es la URL de nuestra nueva página acerca de.

Commit, push y vaya a su sitio web para ver los cambios. Ten en cuenta que los parámetros del sitio no se mostrarán correctamente cuando veas los archivos en GitHub (se mostrarán como texto {% raw %}{{ site.PARAMETER_NAME }}{% endraw %} en lugar del valor mostrado del parámetro) pero sí en el sitio web.

Reutilizar y reducir

Los parámetros globales de Jekyll son una forma útil de mantener toda la configuración de tu sitio en un único lugar (incluso si sólo los usas una vez). En combinación con los layouts/plantillas de Jekyll (que veremos en el próximo episodio) son una buena forma de crear fragmentos de código reutilizables que pueden repetirse en varias o incluso en todas las páginas de tu sitio web. La reutilización te ayuda a reducir la cantidad de código que tienes que escribir.

Enlaces útiles

Esto sólo pretendía ser un tutorial muy básico. Las posibilidades de personalización de sitios con Jekyll van mucho más allá de lo mostrado aquí, podrías por ejemplo:

diseño de páginas (como los ejercicios/soluciones de esta lección),
trabajar con bucles para procesar variables que contienen múltiples valores de forma iterativa,
utilizar filtros para controlar el formato de las variables cuando se insertan en una página,

y más. Esta lección de The Carpentries, aunque diseñada para GitHub, es un recurso valioso para aprender más sobre cómo hacerlo.

Si buscas la documentación oficial de GitLab sobre GitLab Pages con Jekyll, sigue este enlace.

Por último, este proyecto contiene una plantilla más elaborada de un sitio web basado en GitLab y Jekyll.

Puntos Clave

A través de Jekyll, GitLab sirve las páginas generadas de archivos .md

Content from Páginas GitLab con Sphinx

Última actualización: 2025-07-01 | Mejora esta página

Tiempo estimado: 0 minutos

Hoja de ruta

Preguntas

¿Cómo publico páginas web a través de GitLab y Sphinx?

Objetivos

Publicar ficheros reStructuredText como HTML en la red con GitHub Pages

Sphinx es una herramienta para generar páginas web o PDF, principalmente diseñada para crear la documentación de un proyecto. Fue creada originalmente para la documentación de Python, pero tiene excelentes facilidades para la documentación de proyectos de software en una gama de lenguajes. Los sistemas de documentación políglotas pueden ser muy útiles en caso de que tu proyecto aumente en complejidad o número de colaboradores, así que toma nota al respecto.

En este capítulo de la lección utilizaremos el lenguaje de programación Python. Aunque no sea estrictamente necesario, te sugerimos que te familiarices con Python, ya que explicarlo queda fuera del propósito de esta lección. Puedes optar por hacerlo repasando la lección de Las Carpinterías Programando con Python.

Ejercicio: Documentación

En un grupo, haz que cada miembro abra la documentación de uno de los siguientes paquetes

Discutir cuáles son los componentes comunes, lo que es útil acerca de estos sitios de documentación, la forma en que abordan los conceptos generales sobre la documentación, cómo son similares y cómo son diferentes.

Mientras que Jekyll convierte archivos Markdown (.md) en HTML, Sphinx convierte archivos reStructureText (.rts). Si bien estos dos formatos pueden parecer muy similares a primera vista, fueron creados para dos propósitos diferentes: Markdown para escribir para la web, reStructuredText para escribir documentación. Esta entrada de blog proporciona más información sobre lo que esto significa en la práctica. El punto más importante que nos gustaría destacar en este contexto es que reStructuredText también es adecuado para la conversión a PDF. Esto lo convierte en una herramienta útil también para el desarrollo de documentos que pueda necesitar tanto en línea como en copias en papel, por ejemplo materiales de formación o la agenda de una reunión.

Inicio rápido de Sphinx

En aras de la claridad, los próximos pasos de este capítulo sólo se centrará en los archivos Sphinx que son relevantes para la generación de archivos HTML. Sin embargo, instalando Sphinx localmente puede ejecutar el comando quickstart para iniciar un proyecto básico de Sphinx. Recomendamos encarecidamente esta opción si desea ampliar su comprensión de cómo documentar con Sphinx. Para ello, informamos aquí de los pasos necesarios.

Su sistema probablemente tiene Sphinx ya instalado. Compruebe si es así escribiendo en su terminal:

BASH

sphinx-build --version

Si no lo está, podrás instalarlo escribiendo:

BASH

pip install -U sphinx

O consulte las instrucciones de instalación más detalladas aquí. Una vez que Sphinx está instalado, podemos ejecutar el comando quickstart para obtener una visión general del conjunto mínimo de archivos que son necesarios para construir la documentación. El siguiente comando creará un repositorio vacío y ejecutar este comando allí:

BASH

mkdir sphinx-quickstart-test
cd sphinx-quickstart-test
sphinx-quickstart
...
Separate source and build directories (y/n) [n]:
...
Project name: My project
Author name(s): <Your name>
Project release []:
...
Project language [en]:

Se generarán varios documentos. Aquí un resumen:

Los archivos que son relevantes para nosotros en este contexto son el archivo index.rst - que es el equivalente a nuestro archivo index.md en el ejemplo con Jekyll - y el archivo conf.py. Esta es la razón por la que la lección sólo pasa por ellos.

Crea una carpeta de proyecto vacía. Vamos a inicializar nuestro archivo index.rst en la carpeta raíz de nuestro proyecto.

MARKDOWN

.. this is a comment, it is not rendered

Sphinx Example Project's documentation
======================================

Contents:

.. toctree::
    :maxdepth: 2

Reporta el encabezado principal de nuestro proyecto, y luego una tabla de contenidos a través del “árbol TOC”. Se puede dar una opción numérica maxdepth (nosotros la initalizamos en 2) para indicar la profundidad del árbol; por defecto, se incluyen todos los niveles. Más información sobre el árbol TOC en este enlace. En resumen, al añadir archivos *.rst a nuestra tabla de contenido, deben aparecer aquí. Añadamos un archivo para ver cómo funciona esto.

Crea un archivo about.rst, también en la carpeta raíz principal, con el contenido:

MARKDOWN

About
=====

Hello, this is the about page of my project.

Ahora vamos a añadir este archivo al árbol TOC editando el archivo index.rst:

MARKDOWN

.. this is a comment, it is not rendered

Sphinx Example Project's documentation
======================================

Contents:

.. toctree::
    :maxdepth: 2

    about.rst

Ya está: nuestra página de inicio (generada con el archivo index.rst) enlazará ahora con la página Acerca de (about.rst). A continuación, vamos a escribir un archivo conf.py mínimo, también en el directorio raíz.

BASH

# -- Project information -----------------------------------------------------

project = 'My project'
copyright = '2021, <Your name>'
author = '<Your name>'
release = '1.0'

# -- Options for HTML output -------------------------------------------------

html_theme = 'alabaster'

Para obtener una lista completa de las opciones que se pueden especificar en este archivo, consulte la documentación.

Inicio rápido de Sphinx

Una vez más, tener Sphinx instalado localmente le ayudará en las siguientes etapas. De hecho, usted puede construir su sitio web de documentación localmente a través del comando sphinx-build . build/ para ser ejecutado en su carpeta raíz. Una vez ejecutado, se generará el sitio web de salida en la carpeta build/. Puedes visualizarlo simplemente abriendo el archivo index.html a través de tu navegador favorito.

También en este caso, el archivo .gitlab-ci.yml es necesario para especificar las instrucciones para el despliegue de GitLab. Rellénalo con:

YAML

pages:
  stage: deploy
  image: python:3.6
  script:
    - pip install -U sphinx
    - sphinx-build -b html . public
  artifacts:
    paths:
      - public

Este script: especifica el contenedor para nuestro pipeline (Python, versión 3.6), instala Sphinx a través de Pip, ejecuta el comando sphinx-build - que construye archivos HTML en la carpeta raíz (.) a una carpeta public que también crea. Finalmente, especifica dónde encontrar los artefactos HTML (en la carpeta public, efectivamente).

Ya está todo listo. Ahora debemos seguir una vez más la “Configuración de un proyecto” en la introducción para configurar un proyecto remoto en GitLab, configurarlo como remoto para nuestra carpeta local con git remote add origin <git URL>, git add . && git commit -m <message> y luego git push -u. Finalmente, monitoriza la ejecución de tu pipeline y comprueba el resultado final.

Puntos Clave

A través de Sphinx, GitLab sirve páginas generadas de archivos .rst

Content from Páginas GitLab con libros Jupyter

Última actualización: 2025-07-01 | Mejora esta página

Tiempo estimado: 0 minutos

Hoja de ruta

Preguntas

¿Cómo publico páginas web a través de GitLab y Jupyter books?

Objetivos

Publicar Jupyter notebooks como HTML en la red con GitLab Pages

Hagamos algo diferente, que te sonará un poco más familiar si estás acostumbrado a los proyectos Jupyter. De su sitio web:

El Proyecto Jupyter existe para desarrollar software de código abierto, estándares abiertos y servicios para la computación interactiva en docenas de lenguajes de programación.

Los cuadernos Jupyter te permiten crear y compartir documentos que contienen código en vivo, así como texto narrativo. Jupyter Lab amplía sus funcionalidades creando un entorno de desarrollo interactivo (que le permite navegar por su sistema de archivos y definir el entorno de codificación). Jupyter Hub es una versión multiusuario de Jupyer Lab que las instituciones pueden implementar localmente (como hicimos en EMBL).

¿Y Libro de Jupyer?

Jupyter Book es un proyecto de código abierto para crear libros y documentos atractivos y de calidad editorial a partir de material computacional.

El tutorial extenso te guiará a través de los pasos de instalación y la personalización detallada disponible, en el contexto de esta lección vamos a cubrir sólo lo básico. Lo primero es lo primero, vamos a instalar Jupyter Book. En tu terminal:

BASH

pip install -U jupyter-book

Ten en cuenta: necesitarás tener pip instalado también. Ahora, vamos a crear nuestro primer proyecto de libro. El comando jupyter-book --help nos ayudaría a comprobar las opciones aquí, pero en esta lección haremos spoiler de algo: el comando

BASH

jupyter-book create jupyter-book-demo

el comando creará un libro Jupyter básico en una carpeta jupyter-book-demo. Esta carpeta ya incluye las tres cosas necesarias para construir un libro: un archivo _config.yml, una tabla de contenido _toc.yml y el contenido del libro en una colección de archivos MarkDown, reStructuredText o Jupyter Notebook.

Como nos estamos cansando de tanto desarrollo y despliegue, no queremos editar nada del contenido, pero en su lugar priorizamos tenerlo funcionando en GitLab. Adivina, ¿qué necesitamos añadir? Un archivo .gitlab-ci.yml de hecho.

YAML

pages:
  stage: deploy
  image: python:slim
  script:
    - pip install -U jupyter-book
    - jupyter-book clean .
    - jupyter-book build .
    - mv _build/html public
  artifacts:
    paths:
      - public

Este trozo de código:

Instala jupyter-book (o comprueba que está correctamente instalado de forma remota).
Limpia la carpeta de archivos resultantes de (eventuales) construcciones previas.
ejecuta el comando jupyter-book build ., que construye el libro en la carpeta en una subcarpeta _build. Puedes comprobar la salida ejecutando el mismo comando en tu terminal, y te darás cuenta de que los archivos HTML reales están en la subcarpeta _build/html.
A continuación, mueve el contenido HTML a nuestra carpeta habitual public donde se almacenan los artefactos.

Tu tiempo para experimentar con una plantilla

Esta plantilla es deliberadamente mínima para darte la oportunidad de poner a prueba tus habilidades de lectura de documentación. Consulta las guías temáticas en jupyterbook.org y encuentra la manera de:

Añade otra página llamada “Acerca de” y enlazada desde la tabla de contenidos.
Juega con el formato de archivo de esta nueva página, añade el mismo tipo de contenido en formatos MarkDown, reStructuredTex y Notebook.
Añade una figura y un pie de figura.
Inserta una celda de código. Si estás familiarizado con algún lenguaje de programación, añade un trazado sencillo y visualiza la salida de dicho trazado en tu página.
Para funciones de código más avanzadas, consulta cómo hacer que el código sea ejecutable
¡Inspírate en la galería de libros Jupyter!

Puntos Clave

A través de Jupyter books, serás capaz de integrar componentes interactivos y código en tus páginas web

Content from Plantillas GitLab

Última actualización: 2025-07-01 | Mejora esta página

Tiempo estimado: 0 minutos

Hoja de ruta

Preguntas

¿Dónde puedo encontrar proyectos/temas pre-construídos para mi página?

Objetivos

Busca y haz fork de plantillas pre-existentes para determinar las tecnologías detrás de un proyecto y los estilos de la página web derivada

Plantillas Bio-IT

Las plantillas que hemos desarrollado juntos están disponibles en nuestra plataforma GitLab:

Pueden ser ligeramente enriquecidos en comparación con lo que hemos visto durante esta lección, por ejemplo la plantilla HTML simple también cuenta con un archivo .css, pero se mantienen al mínimo a propósito. Si quieres usarlos como base para tu propio proyecto, deberías forkearlos. Si lo haces para desarrollar tu propio proyecto, y no para contribuir a la plantilla en sí, debes eliminar la relación de bifurcación. Repasemos juntos el proceso.

fork a repository through the Fork button

Fork un proyecto haciendo clic en el botón “Fork” a la derecha del título del proyecto. Esto abrirá un menú (mostrado abajo) muy similar al que aparece cuando abres un nuevo proyecto. Puedes decidir mantener tu proyecto en privado y editar el título y la descripción. También puede colocarlo en el grupo/espacio de nombres correspondiente.

Una vez que haya terminado, por favor, elimine la relación de bifurcación. Puede editar la configuración del proyecto en el menú de la izquierda en la página del proyecto, siga: Settings > General > Advanced y luego desplácese hacia abajo hasta la tarjeta “Eliminar relación de bifurcación”.

Una vez hecho esto, puedes clonar tu repositorio localmente y empezar a editar la plantilla. Si necesitas una recapitulación sobre clonación, fork, push y pull en Git por favor revisa esta lección por The Carpentries.

Más plantillas

¿Te preguntas dónde puedes encontrar más ejemplos de proyectos de páginas de GitLab? Consulta este enlace. Incluye más de 40 ejemplos, basados en múltiples tecnologías. También en estos casos, es una buena práctica eliminar la relación fork si tu objetivo es utilizar la plantilla para el desarrollo de tu propio sitio web, y no contribuir a la plantilla en sí. Algunos ejemplos de plantillas que encontrarás en este repositorio son:

courseware-template, una plantilla basada en Jekyll para el sitio web de un curso. Puede verla en acción aquí. Incluye estilos para dar formato al contenido de las clases, cuestionarios y diapositivas.
hugo blog template, la plantilla para construir blogs basada en Hugo.
jupyterbook, una plantilla para generar libros y documentos integrando código Python. Véalo renderizado aquí.

Ahora tienes todos los conocimientos necesarios para empezar a jugar con las páginas de GitLab. No dudes en contactar con nosotros si tienes alguna pregunta o abrir una incidencia en los proyectos de plantilla para solicitar características o plantear problemas. También eres bienvenido a contribuir al desarrollo de plantillas de páginas, tanto las existentes como las nuevas que puedan encajar en tus casos de uso. Por último, consulta el siguiente capítulo (extra) para saber cómo tratar los errores en la ejecución de la canalización y poder solucionar posibles errores de CI/CD

Puntos Clave

Puedes encontrar muchas plantillas ya existentes para sitios en Internet
Puedes consultar los temas presentados para sitios en nuestro GitLab local
Puedes evitar trabajo duplicado basándote en diseños anteriores para crear nuevos

Content from Cuando las cosas van mal

Última actualización: 2025-07-01 | Mejora esta página

Tiempo estimado: 0 minutos

Hoja de ruta

Preguntas

¿Cómo soluciono errores en las pipelines de GitLab?

Objetivos

Obtén feedback de GitLab sobre por qué ha fallado una pipeline

Cuando las cosas van mal

Hasta ahora hemos visto cómo utilizar con éxito varias tecnologías para producir un sitio web. Sin embargo, hay algunas situaciones en las que pueden fallar debido a un error tipográfico o a la falta de información. Vamos a ver uno de estos casos con un ejemplo de Jekyll.

Ejercicio: Solución de problemas de Jekyll

Este ejercicio le ayudará a reconocer cómo son los errores más comunes cuando se trabaja con estos elementos de un sitio web Jekyll.

Edite su archivo _config.yml y sustituya un carácter : por un carácter = en una de las variables.

Solución

Por ejemplo, mail=team@carpentries.org en lugar de mail:team@carpentries.org.
YAML
description: "This research project develops training materials for reseachers wanting to learn to build project
websites in GitHub with GitHub Pages."
email: "team@carpentries.org"
twitter: "https://twitter.com/thecarpentries
Si navegas por tu repositorio de GitHub podrás ver que algo se rompe en about.md donde usamos {% raw %}{{ site.twitter }}{% endraw %} sin embargo, al contrario de lo que vimos antes con Markdown inválido, Jekyll se negará a construir la página y producirá un mensaje de error.

Después veremos dónde encontrar el mensaje de error e identificar qué los causó.

Si estabas echando un ojo a la página de ejecución del pipeline de GitLab hasta ahora (CI/CD > Pipelines), te habrás dado cuenta de que una vez que empujas el pipeline resulta “pendiente”, luego empieza a “ejecutarse”, y finalmente “pasa”. Eventualmente. Si no lo hace, entonces el estado es “fallido”, es posible que recibas un correo electrónico al respecto (dependiendo de la configuración de tu cuenta de GitLab) y no debes entrar en pánico. ¿Cómo podemos entender qué causó el error y solucionarlo? El estado “fallido” resulta ser un botón, hagamos clic en él.

haga clic en el botón de error para acceder al registro de la tubería

Una vez más, puede hacer clic en el botón ❌ pages para acceder a más detalles, es decir, al registro completo de la ejecución de nuestro pipeline. Desplázate por la ventana tipo terminal para ver cómo se inició, preparó los entornos, instaló dependencias y ejecutó correctamente hasta el comando bundle exec jekyll build - public. ¿Lo recuerdas? Es el comando que lanza Jekyll, lo incluimos en el fichero .gitlab-ci.yml.

Basándonos en esto, tenemos razones para sospechar que el error aquí está relacionado con que Jekyll no puede construir la página. Leyendo más detenidamente para obtener más detalles, encontramos:

BASH

$ bundle exec jekyll build -d public
                    ------------------------------------------------
      Jekyll 4.2.1   Please append `--trace` to the `build` command
                     for any additional information or backtrace.
                    ------------------------------------------------
/usr/local/bundle/gems/safe_yaml-1.0.5/lib/safe_yaml/load.rb:143:in `parse': (/builds/hpg_ToyM/0/grp-bio-it/template-pages-jekyll/_config.yml): could not find expected ':' while scanning a simple key at line 3 column 1 (Psych::SyntaxError)

Esto significa dos cosas: en primer lugar, el registro sugiere una forma de obtener eventualmente más detalles, es decir, modificar el fichero .gitlab-ci.yml añadiendo --trace al comando bundle exec jekyll build -d public, que se convierte así en bundle exec jekyll build -d public --trace. Sin embargo, en realidad no necesitamos eso: la siguiente frase es suficientemente clara. Dice, hubo un error al analizar el fichero _config.yml porque Jekyll no pudo encontrar el carácter : esperado. Como este error impide a Jekyll construir la página, el proceso no puede continuar.

El fallo no eliminará su página web

Dado el fallo, puede que se pregunte qué ha pasado con la página web Si visita la dirección encontrará que el sitio web sigue estando disponible.

GitLab mantendrá tu versión anterior en línea hasta que el error sea corregido y una nueva compilación sea completada con éxito.

Deberíamos volver a nuestro archivo _config.yml y corregir el error = que cometimos (a propósito, esta vez). A continuación, empuje el proyecto de nuevo, ¡y problema resuelto!

Ejercicio: Practicar con la solución de problemas de Jekyll

A veces ocurren errores tipográficos que pueden hacer que su sitio web cambie de forma sorprendente. Experimentemos con algunos posibles problemas que puedan surgir y veamos qué ocurre.

Pruebe los cambios que se indican a continuación en su archivo index.md y compruebe qué sucede cuando se renderiza la página. Querrá corregir el error anterior cada vez.

Utilice una variable global o local que no haya definido primero.
Quite el guión del final de la cabecera YAML.
No ponga un espacio entre la cabecera YAML y el resto de la página
Coloque la cabecera YAML en un lugar diferente de la página.

Solución

El lugar donde usó la variable indefinida está en blanco pero por lo demás no hay error. Ejemplo:
MARKDOWN
Hi! {% raw %}{{ site.greeting }}{% endraw %}. What have you been up to?
La cabecera muestra algo en el archivo y la variable que se definió va a la página de índice en lugar del enlace que establecimos.
MARKDOWN
---
lesson-example: "https://carpentries.github.io/lesson-example/"

Examples of our work can be found at: {% raw %}{{ page.lesson-example }}{% endraw %}
Esto no parece afectar a nuestra página pero a menudo puede hacer que páginas más complejas se rompan.
MARKDOWN
---
lesson-example: "https://carpentries.github.io/lesson-example/"
---
Examples of our work can be found at: {% raw %}{{ page.lesson-example }}{% endraw %}
Esto también hace que la cabecera se muestre un poco en la página y rompe el enlace variable que creamos.
MARKDOWN
Examples of our work can be found at: {% raw %}{{ page.lesson-example }}{% endraw %}
---
lesson-example: "https://carpentries.github.io/lesson-example/"
---

Nota: Asegúrese de corregir cualquier error que haya introducido intencionadamente en su página antes de continuar.

Puntos Clave

Si falla una pipeline, GitLab proveerá información útil sobre por qué