Desplegar en GitHub Pages

Desplegar en GitHub Pages (sin GitHub Actions)

Publicado 01/01/2022 Actualizado 10/01/2026

Por mcherrera

8 min de lectura

Jekyll: Desplegar en GitHub Pages

GitHub Pages permite publicar sitios estáticos directamente desde un repositorio. Jekyll está soportado de forma nativa, por lo que no es necesario usar GitHub Actions si seguimos la estructura y configuración correcta.

En este post veremos el flujo más simple y estable para dejar un sitio Jekyll en línea usando únicamente GitHub Pages.

1. Crear el repositorio

Crea un repositorio en GitHub. Puede ser público o privado (con cuenta Pro).

Opciones comunes:

usuario.github.io: sitio principal
nombre-del-proyecto: sitio de proyecto

En esta pantalla, completamos el campo Repository Name. El campo Description es opcional y dejamos el repositorio como Public (las páginas de GitHub no se habilitan para su visualización en repositorios privados). A continuación, hacemos clic en el botón verde Create repository, ubicado en la parte inferior de la pantalla.

Ejemplo:

Nombre y descripción del repositorio

Configuración repositorio

2. Clonar el repositorio e inicializar el entorno de desarrollo

Una vez creado el repositorio en GitHub, seguimos estos pasos para preparar el entorno local y configurar las dependencias necesarias para trabajar con Jekyll y GitHub Pages.

2.1 Copia la url del repositorio

En la página del respositorio copia la URL para clonar luego. Ejemplo:

2.2 Clona el repositorio en tu máquina

Ejecuta el comando git clone y pega la URL del repositorio. Ejemplo:

git clone url-del-repositorio.git

Durante el proceso, se enumeran y reciben todos los objetos del repositorio para crear una copia exacta local.

2.3 Entrar al directorio del proyecto

Con el comando cd accede al directorio del proyecto clonado. Ejemplo:

cd nombre-del-proyecto

2.4. Crear un Gemfile

Para gestionar las dependencias de Ruby y Jekyll, inicializamos Bundler. Ejemplo:

bundle init

Este comando genera un archivo Gemfile vacío en el directorio actual.
El Gemfile es donde se definirán las gemas necesarias para el proyecto.

2.5 Agregar la gema github-pages

Añadimos la gema oficial de GitHub Pages en el grupo jekyll_plugins, que incluye Jekyll y sus dependencias compatibles. Ejemplo:

bundle add github-pages --group "jekyll_plugins"

Esta gema asegura que el entorno local use las mismas versiones de Jekyll y plugins que GitHub Pages utiliza en producción.
Agruparla en jekyll_plugins garantiza que solo se cargue cuando se ejecuten comandos relacionados con Jekyll, optimizando el entorno.

2.6 Instalar las dependencias

Finalmente, instalamos las gemas indicadas en el Gemfile. Ejemplo

bundle install

Esto deja el entorno listo para construir y servir el sitio localmente.

A continuación, se puede observar los comandos explicados anteriormente:

2.7 Ignorar Gemfile.lock

Antes de continuar, es importante realizar una acción previa que consiste en añadir el archivo Gemfile.lock a los archivos ignorados en el .gitignore. Por ejemplo:

Puedes añadir Gemfile.lock al .gitignore de forma rápida y directa desde la terminal, aquí tienes los comandos listos para copiar:

# Abrir (o crear) el .gitignore y añadir Gemfile.lock
echo "Gemfile.lock" >> .gitignore

# Quitar Gemfile.lock del control de versiones (sin borrarlo localmente)
git rm --cached Gemfile.lock

# Agregar los cambios al staging (incluye .gitignore modificado)
git add .gitignore

# Confirmar cambios
git status

# Hacer commit del cambio
git commit -m "chore: ignorar Gemfile.lock para GitHub Pages"

3. Estructura mínima del proyecto

El proyecto Jekyll debe tener, como mínimo los siguientes archivos:

_config.yml
index.md (o index.html)
_posts/ (opcional)
- YYYY-MM-DD-nombre-post.md
assets/(opcional)

Ejemplo de los archivos que vamos a subir para el despliegue:

FOLDERS

Sin archivo x

          
        
          <!DOCTYPE html>
<html lang="es">
  <head>
    <meta charset="UTF-8" />
    <title>
      {% if page.title %}
        {{ page.title }} | {{ site.title }}
      {% else %}
        {{ site.title }}
      {% endif %}
    </title>
    <meta name="viewport" content="width=device-width, initial-scale=1" />
    <meta name="description" content="{{ page.excerpt | strip_html | truncate: 160 }}">
    <link rel="stylesheet" href="{{ '/assets/css/style.css' | relative_url }}">
  </head>

  <body>
    <header>
      <h1>
        <a href="{{ '/' | relative_url }}">
          {{ site.title }}
        </a>
      </h1>
      <p>{{ site.description }}</p>
      <hr>
    </header>

    <main>
      {{ content }}
    </main>

    <footer>
      <hr>
      <p>
        © {{ "now" | date: "%Y" }} {{ site.title }} —
        Publicado con Jekyll y GitHub Pages
      </p>
    </footer>
  </body>
</html>

          
        
          /* ===== Reset mínimo ===== */
html, body {
  height: 100%;
  margin: 0;
}

/* ===== Base ===== */
body {
  font-family: system-ui, -apple-system, Segoe UI, Roboto, sans-serif;
  line-height: 1.65;
  color: #1f2937;
  background: #f3f4f6;
}

/* ===== Layout vertical ===== */
.page {
  min-height: 100%;
  display: flex;
  flex-direction: column;
}

header,
main,
footer {
  max-width: 900px;
  margin: 0 auto;
  padding: 2.5rem 2rem;
}

main {
  flex: 1;
  background: #ffffff;
}

/* ===== Header ===== */
header h1 {
  margin: 0;
  font-size: 2rem;
}

header p {
  margin-top: 0.5rem;
  max-width: 60ch;
  color: #6b7280;
}

header a {
  color: inherit;
  text-decoration: none;
}

/* ===== Typography ===== */
h1, h2, h3 {
  line-height: 1.3;
  margin-top: 3rem;
}

h2 {
  font-size: 1.5rem;
  border-bottom: 1px solid #e5e7eb;
  padding-bottom: 0.4rem;
}

p {
  margin: 1.2rem 0;
  max-width: 72ch;
}

/* ===== Links ===== */
a {
  color: #2563eb;
}

a:hover {
  text-decoration: underline;
}

/* ===== Code ===== */
pre {
  background: #f9fafb;
  border: 1px solid #e5e7eb;
  padding: 1.25rem 1.5rem;
  overflow-x: auto;
}

code {
  background: #eef2ff;
  padding: 0.2em 0.4em;
  font-size: 0.95em;
}

pre code {
  background: none;
  padding: 0;
}

/* ===== Footer ===== */
footer {
  text-align: center;
  font-size: 0.9rem;
  color: #6b7280;
}

/* ===== Responsive ===== */
@media (max-width: 640px) {
  header,
  main,
  footer {
    padding: 1.5rem 1.2rem;
  }
}

          
        
          title: 'Jekyll + GitHub Page'
description: 'Despliegue simple de un sitio Jekyll en GitHub Pages, sin usar GitHub Actions'
base_url: '/demo-jekyll-deploy-gh-pages'

          
        
          _site/
.sass-cache/
.jekyll-cache/
.jekyll-metadata
.bundle/
vendor/
Gemfile.lock

          
        
          ---
layout: default
title: Inicio
---

## Hola Jekyll ❤️
Mi sitio está funcionando.

Selecciona un archivo para ver su contenido

El archivo _config.yml es clave para que GitHub Pages genere el sitio correctamente.

Ejemplo básico:

title: Mi sitio hecho con Jekyll
description: Descripción de ejemplo para el sitio
baseurl: "/nombre-del-proyecto" # si NO es usuario.github.io
url: "https://tu-usuario.github.io"

Importante
Si el repo es usuario.github.io, deja baseurl vacío:
1 baseurl: ""

4. Probar el sitio usando el servidor de desarrollo

Antes de desplegar tu sitio, es recomendable verificar que todo funciona localmente usando el servidor de desarrollo que incluye Jekyll. Esto te permite revisar posts, estilos y enlaces antes de subirlos a GitHub Pages.

4.1 Iniciar el servidor

Desde la raíz de tu proyecto, ejecuta:

bundle exec jekyll serve --port 3000

Explicación:

bundle exec asegura que se usan las gems definidas en tu Gemfile.
jekyll serve inicia un servidor local.
--port 3000 indica que el sitio estará disponible en http://localhost:3000.

Si omites --port, Jekyll usará el puerto 4000 por defecto.

4.2 Ver el sitio en el navegador

Abre tu navegador web.
Accede a: http://localhost:3000
Navega por tus páginas para asegurarte de que:
- El contenido se muestra correctamente.
- Los enlaces internos funcionan.
- Los estilos CSS y el layout se aplican como esperas.

Ejemplo del sitio que vamos a desplegar:

4.3 Cambios automáticos

El servidor de desarrollo de Jekyll recarga automáticamente la página cuando guardas cambios en tus archivos:

Archivos .md de posts o páginas.
Archivos en _layouts o _includes.
Archivos CSS/JS en assets/.

Si agregas nuevos archivos, a veces es necesario reiniciar el servidor.

Para correr el servidor con LiveReload, ejecuta el siguiente comando:

bundle exec jekyll serve \
  --livereload \
  --livereload-port 35730 \
  --port 3000

--livereload o -l: abre un servidor TCP adicional para recargar el navegador automáticamente
--livereload-port 35730: usar otro puerto para LiveReload.
--port 3000: tu sitio principal sigue en 3000.

4.4 Mensajes frecuentes del servidor

Al iniciar jekyll serve, podrías ver advertencias como:

GitHub Metadata: No GitHub API authentication could be found.
- Esto solo afecta a variables de site.github.
- No impide probar el sitio localmente.
Configuration file: none
- Significa que no tienes _config.yml o Jekyll no lo encuentra.
- No es crítico si tu sitio funciona con configuración por defecto.

5. Subir el proyecto a GitHub

Desde la raíz del proyecto:

git add .
git commit -m "feat: initial Jekyll site"
git branch -M main
git push -u origin main

Si realizamos el push utilizando el protocolo HTTP, se nos pedirá ingresar nuestras credenciales de GitHub a través del navegador. Por ejemplo:

Completado el proceso, se subirán los archivos al repositorio. Por ejemplo:

6. Configurar GitHub Pages

En el repositorio:

Ve a Settings → Pages
En Source selecciona:
- Branch: main
- Folder: /root
Guarda los cambios

GitHub comenzará a construir el sitio automáticamente usando Jekyll.

7. Acceder al sitio

Después de unos segundos:

https://tu-usuario.github.io/nombre-de-proyecto/

Si es un repo tipo usuario.github.io:

https://tu-usuario.github.io/

En la demostración de este artículo, el sitio está desplegado y disponible en la siguiente URL:

https://mc-herrera-90.github.io/demo-jekyll-deploy-gh-pages/

8. Cosas a tener en cuenta

GitHub Pages no ejecuta plugins personalizados de Jekyll.
Solo se permiten los plugins incluidos en github-pages.
No necesitas generar _site/ manualmente.
Cada push a main vuelve a desplegar el sitio.

Este método es ideal si:

Quieres un flujo simple
No necesitas compilación avanzada
Prefieres evitar GitHub Actions

Para proyectos educativos, blogs o páginas de retos, GitHub Pages + Jekyll nativo es más que suficiente y muy estable.

Jekyll, Jekyll-Deploy

Esta entrada está licenciada bajo CC BY 4.0 por el autor.