Generadores de Sitios Estáticos desde Cero: Vocabulario, historia y una primera creación
Aprende los términos que se asume que ya conoces en los documentos de SSG, cómo se combinan los diseños, las partes parciales y el contenido preliminar, de dónde provienen los generadores y cómo elegir uno sin complicaciones.
Los generadores de sitios estáticos prometen algo sencillo: escribir artículos en Markdown, mantener el encabezado y el pie de página en un mismo lugar, y obtener un sitio web rápido creado con archivos simples. Para muchos principiantes, la realidad es un muro de jerga inexplicable, una terminal que muestra rastros de ejecución y documentación que presupone años de conocimientos previos. Esta guía cierra esa brecha desde cero. Aprenderá qué habilidades debe tener antes de comenzar, qué significa realmente cada término recurrente en la documentación del generador, cómo se combinan las partes de un proyecto típico de Eleventy, de dónde provienen estas herramientas y qué opciones más ligeras existen cuando las populares parecen demasiado complejas.
Antes de elegir un generador: las habilidades necesarias
Un generador de sitios estáticos (SSG) es una capa de abstracción sobre las páginas web. Si nunca has creado una página web a mano, esa abstracción oculta exactamente las cosas que necesitas entender cuando algo falla. Para tus primeros sitios, escribir el HTML y CSS por tu cuenta es un mejor método de aprendizaje. Sentirás el esfuerzo de copiar la misma navegación en diez archivos, y ese esfuerzo es precisamente lo que te hará recurrir a un generador más adelante.
Casi todos los generadores esperan, de forma silenciosa, que tengas conocimientos básicos en HTML y CSS, a menudo también algo de JavaScript, algunas ideas generales de programación como variables y bucles, el símbolo del sistema y, por lo general, Git. Nadie necesita dominar todo esto al principio. Lo importante es que tener un modelo mental básico de cada capa convierte un fallo de construcción enigmático en un problema resoluble en lugar de un misterio.
Un camino de estudio con recursos gratuitos
Los siguientes recursos funcionan bien más o menos en este orden. Crea sitios temporales pequeños a medida que avanzas, en lugar de tratar la lista como tarea pendiente que debes terminar primero.
- HTML: HTML for People está escrito para lectores sin experiencia alguna en programación. Si deseas profundizar en los elementos semánticos y la accesibilidad, dirígete al módulo de MDN sobre estructuración de contenido.
- CSS: El módulo básico de estilización de MDN aborda conceptos como el modelo de caja y el diseño de layouts. Si prefieres ejercicios prácticos, el curso de freeCodeCamp sobre diseño responsive explica HTML, CSS, accesibilidad y diseño responsive (prácticamente, adaptado a dispositivos móviles).
- JavaScript: El módulo de scripting de MDN continúa de forma natural a partir del material sobre HTML y CSS, mientras que el plan de estudios de JavaScript de freeCodeCamp ofrece una alternativa interactiva.
Si prefieres un centro de recursos único en lugar de una colección, el área de aprendizaje de MDN abarca HTML, CSS, JavaScript y los fundamentos del navegador en un único plan de estudios. web.dev, The Odin Project y w3schools son otras opciones.
Mantén la perspectiva: un sitio web personal suele ser un proyecto como hobby. Las soluciones no convencionales y los errores forman parte del proceso, y cada pequeño sitio que terminas agrega una nueva habilidad que puedes incorporar al siguiente.
El vocabulario que asumen conocidos los documentos de static-site
La documentación de generadores tiende a usar una docena de términos como si todos los hubieran aprendido al nacer. Esta sección los define en lenguaje sencillo y muestra cada uno en un archivo pequeño y concreto de un proyecto Eleventy (11ty).
Marcado, estilo y comportamiento: HTML, CSS y JavaScript
HTML (HyperText Markup Language) describe la estructura y el significado de un documento: encabezados, párrafos, enlaces, imágenes, listas. No es un lenguaje de programación. No puede tomar decisiones ni repetir nada por sí mismo; simplemente declara lo que hay en la página. La página más pequeña y útil cuenta con un doctype, un <head> que incluye un conjunto de caracteres y un título, y un <body> con contenido. Tenga en cuenta que nada aquí controla los colores o las fuentes, por lo que el navegador utiliza sus estilos predeterminados.
<!DOCTYPE html>
<html lang="en">
<head>
<meta charset="utf-8">
<title>My First Page</title>
</head>
<body>
<h1>Hello, world!</h1>
<p>This page has a <a href="https://brennan.day">link</a> and a list:</p>
<ul>
<li>HTML gives a page its structure.</li>
<li>There's no CSS yet, so this is all default styling.</li>
</ul>
</body>
</html>Copy
Al guardar esto como index.html y abrirlo en cualquier navegador, obtendrá una página web funcional, sin necesidad de servidor. (El Copy al final de la etiqueta cerrada es un resto de un botón de copiar y no forma parte del marcado.)
CSS (Hojas de estilo en cascada) controla cómo se presenta esa estructura: colores, espaciado, tipografía y la forma en que el diseño se adapta a diferentes tamaños de pantalla. Las reglas siguientes establecen un tipo de letra con serif, limitan el ancho del texto para que las líneas sigan siendo legibles, centran la columna con márgenes automáticos y asignan al página un fondo cálido y colores oscuros para el texto. El encabezado cuenta con su propia regla de color.
body {
font-family: Georgia, serif;
max-width: 35rem;
margin: 2rem auto;
padding: 0 1rem;
background: #fff2ce;
color: #02005d;
}
h1 {
color: rebeccapurple;
}Copy
Al colocar estas reglas dentro de un elemento <style> en el <head> de la página anterior, se transforma su apariencia sin cambiar ni una sola palabra del HTML. Esa separación entre contenido y presentación es un principio que se mantiene en todos los generadores de sitios estáticos.
JavaScript es el lenguaje de programación que ejecutan los navegadores. Añade comportamientos: reacciona a clics, cambia contenido y obtiene datos. También es la forma más sencilla de hacer que una página simple sea lenta y pesada, por lo que un buen criterio por defecto para un sitio personal es usarlo solo donde realmente sea necesario. El fragmento a continuación encuentra un elemento con el id surprise, escucha los clics en él y reemplaza el texto del primer <h1> cuando ocurre el clic.
const button = document.querySelector("#surprise");
button.addEventListener("click", () => {
document.querySelector("h1").textContent = "JavaScript did this!";
});Copy
Para que esto funcione, la página necesita un <button id="surprise"> correspondiente. Sin él, querySelector devuelve null y la llamada a addEventListener lanza un error, lo cual es el primer problema común.
JavaScript también está presente en el lado del generador, no solo en el navegador. Muchos SSGs están escritos en JavaScript y lo utilizan para ejecutar la compilación o evaluar plantillas. Eleventy incluso permite que toda una plantilla sea un archivo JavaScript: cualquier cadena que devuelva la función exportada se convierte en el contenido de la página.
// hello.11ty.js
module.exports = function () {
return "<h1>Hello from JavaScript!</h1>";
};Copy
Este ejemplo utiliza CommonJS module.exports. Las versiones recientes de Eleventy también soportan la sintaxis de módulos ES (export default), así que verifica qué estilo utiliza la documentación de tu versión instalada.
Qué significan realmente “estático”, “compilación” y “salida”
- Estático se refiere a la forma de entrega: el servidor entrega un archivo tal como está almacenado, en lugar de generar una respuesta nueva para cada visitante. Una página estática puede seguir incluyendo JavaScript y aún puede ser editada y vuelta a publicar. Esto no implica que la página sea aburrida o permanezca inmutable para siempre.
- Dinámico significa que algo calcula la respuesta en el momento de la solicitud. Un sistema clásico de gestión de contenidos consulta una base de datos y compone la página en cada visita. Una tienda en línea es el ejemplo típico, ya que el inventario y los carritos de compra cambian constantemente.
- Un generador de sitios estáticos es un programa que lee material de origen (contenido en Markdown, plantillas, configuraciones, imágenes y otros recursos) y genera un conjunto completo de archivos HTML, CSS, JavaScript e imágenes que cualquier servidor estático puede servir.
_site/, public/ o dist/. Por lo general no se editan manualmente, ya que la siguiente construcción los sobrescribe.localhost:8000 y, a menudo, vuelve a generarlo automáticamente cada vez que guardas un archivo de origen.Archivos de configuración y datos del sitio
- Un archivo de configuración almacena ajustes para todo el sitio, como el nombre del sitio, la URL base, los menús, el directorio de salida o las opciones de feed. Los nombres y formatos varían según la herramienta:
config.yml,hugo.toml,eleventy.config.jsy otros. - YAML es un formato de datos amigable para el usuario, común en configuraciones y contenido preliminar. Permite expresar cadenas de texto, números, listas y asociaciones clave-valor. La sangría tiene significado, por lo que un espacio fuera de lugar puede arruinar el proceso de compilación.
- Una pareja clave-valor es un ajuste que consta de un nombre y un valor, como
title: Mi publicación. En YAML, un grupo de estas parejas se denomina mapeo. - Un parámetro o opción es un ajuste que se pasa a una orden o se incluye en un archivo. La bandera
--serveque verá más adelante es un ejemplo.
En Eleventy, los archivos de la carpeta _data se convierten en datos globales disponibles para cada plantilla. El archivo src/_data/site.json alberga los detalles que ven los visitantes: el nombre del sitio, una breve descripción, el autor, la URL pública y el idioma.
{
"name": "My Cool Blog",
"description": "Where I write about whatever interests me.",
"author": "Your Name",
"url": "https://example.com",
"language": "en"
}
Cada clave se convierte en una variable de plantilla. Un layout que contenga {{ site.name }} mostrará el valor “My Cool Blog”; por lo tanto, cambiar el nombre del sitio implica editar una sola línea aquí en lugar de buscar en cada página. Jekyll guarda este mismo tipo de información en config.yml y Hugo en hugo.toml; la idea es idéntica, solo cambia el archivo. Tenga en cuenta que JSON es estricto: una coma al final después de la última entrada constituye un error de sintaxis, detalle que será importante más adelante en esta guía.
Layouts, partials y plantillas
- Un template es un archivo reutilizable que define la estructura de una página y contiene marcadores de posición para las partes que cambian.
- Un layout es un template para toda una página: la declaración del lenguaje, el
<head>, el encabezado, el área principal de contenido y el pie de página. - Un partial es un pequeño fragmento reutilizable como una barra de navegación, un pie de página o un bloque de metadatos de entrada. Una instrucción include sirve para incorporar un fragmento en otro archivo.
- Un lenguaje de plantillas es la sintaxis utilizada para mostrar variables, iterar sobre datos y tomar decisiones dentro de las plantillas. Liquid, Nunjucks y los templates de Go son ejemplos comunes.
- Una regla condicional es una norma de tipo sí o no en una plantilla, por ejemplo “mostrar la imagen principal solo cuando la entrada la defina”.
El diseño base que se muestra a continuación, _includes/layouts/base.njk, está escrito en Nunjucks. El título combina el título propio de la página con el nombre global del sitio; dos etiquetas include insertan las secciones de encabezado y pie de página, y el cuerpo de la página renderizada se muestra dentro de <main>.
<!DOCTYPE html>
<html lang="en">
<head>
<meta charset="utf-8">
<title>{{ title }} | {{ site.name }}</title>
</head>
<body>
{% include "partials/header.njk" %}
<main>
{{ content | safe }}
</main>
{% include "partials/footer.njk" %}
</body>
</html>
El filtro | safe es importante. Nunjucks escapa el contenido por defecto, lo que convertiría el HTML del post en etiquetas visibles. Al marcar content como seguro, se indica al motor que esta cadena es de confianza y corresponde a HTML ya renderizado. Úselo únicamente para contenido que usted controle.
Los fragmentos parciales son simplemente fragmentos de HTML que pueden utilizar variables e incluir otros fragmentos parciales. El encabezado hace un enlace de vuelta a la página principal utilizando el nombre del sitio e incluye la navegación; la navegación es una lista sencilla de enlaces; el pie de página muestra una línea de derechos de autor con el nombre del autor extraído de los datos del sitio.
<!-- partials/header.njk -->
<header>
<a href="/">{{ site.name }}</a>
{% include "partials/nav.njk" %}
</header>
<!-- partials/nav.njk -->
<nav>
<a href="/">Home</a>
<a href="/archive/">Archive</a>
<a href="/about/">About</a>
</nav>
<!-- partials/footer.njk -->
<footer>
<p>© 2026 {{ site.author }}</p>
</footer>
Así es como se conectan las partes. Cuando una entrada declara layout: base.njk en su contenido inicial, Eleventy renderiza la entrada y luego coloca el resultado donde se encuentra {{ content | safe }} en el diseño, reemplazando cada etiqueta include por su fragmento parcial correspondiente. Al cambiar la navegación una sola vez, todas las páginas del sitio la adoptan en la siguiente compilación. Eliminar este mantenimiento basado en copiar y pegar es la razón principal de la existencia de los SSG. Una pequeña advertencia: el año en el pie de página está codificado de forma fija, por lo que no se actualizará automáticamente a menos que lo reemplaces por una variable.
Archivos de contenido, Markdown y material preliminar
- archivo de contenido es un archivo fuente para una página o publicación. Markdown es el formato más común, pero muchos generadores aceptan HTML, texto plano u otros formatos.
- Markdown es un lenguaje de marcado ligero en el que la puntuación representa la estructura:
#para encabezados, asteriscos para énfasis y guiones para listas. El generador lo convierte a HTML. - Materia preliminar es un bloque de metadatos en la parte superior de un archivo de contenido, generalmente delimitado por dos líneas con tres guiones. Puede contener un título, fecha, etiquetas, nombre de layout o indicador de borrador.
- Metadatos son información descriptiva sobre un contenido: título, autor, fecha de publicación, etiquetas, descripción, URL canónica o layout elegido.
El archivo posts/my-first-post.md a continuación combina todo esto. El front matter en YAML establece un título, una fecha, dos etiquetas, un diseño y una marca de borrador. El cuerpo mezcla Markdown normal con sintaxis de plantillas al estilo Nunjucks que muestra el título y, condicionalmente, una oración.
---
title: My First Post
date: 2026-09-22
tags:
- posts
- cats
layout: post.njk
draft: false
---
Welcome to my blog! This paragraph is **Markdown**.
This post is called "{{ title }}".
{% if draft %}
This sentence only appears while the post is a draft.
{% endif %}
Eleventy lee el contenido preliminar antes de renderizar cualquier cosa. La clave layout selecciona la plantilla de envoltorio, la etiqueta posts agrega el archivo a una colección llamada posts (que una página de archivo puede recorrer), y date determina el orden de clasificación según la fecha del blog. Todo lo que está después de los guiones de cierre constituye el cuerpo del contenido. Dado que draft tiene el valor false aquí, la oración condicional no aparece en la salida. Tenga en cuenta que la clave draft no tiene un significado inherente en Eleventy; excluir los borradores de una compilación para producción es algo que debe configurarse manualmente.
Términos de hosting, servidores backend y despliegue
- Hosting es el servicio o la máquina que almacena sus archivos de salida y los hace accesibles en Internet. Se trata de un aspecto distinto a la creación del sitio y al control de versiones.
Control de versiones en una sola página
- Control de versiones registra los cambios en los archivos a lo largo del tiempo para que pueda revisar el historial, comparar versiones, revertir cambios y colaborar.
- Git es un programa específico de control de versiones. Funciona íntegramente en su ordenador y no necesita ningún servicio en línea para registrar el historial.
- repositorio (repo) es una carpeta de proyecto cuyo historial gestiona Git.
- commit es una instantánea guardada de los cambios, generalmente acompañada de un mensaje que los describe.
- remoto es otra copia del repositorio, a menudo alojada en Codeberg, GitHub, GitLab o en su propio servidor.
- Push envía tus commits locales a un servidor remoto; pull recupera los commits del servidor remoto y los fusiona con tu copia local.
- Los servicios de hosting de Git almacenan los repositorios y suelen añadir seguimiento de problemas, revisión de código y compilaciones automatizadas. Son prácticos, pero no son Git en sí mismo, y Git funciona perfectamente sin ellos.
Publicar una nueva entrada con Git desde la terminal requiere cuatro comandos. El primero se ejecuta solo una vez por proyecto; los otros tres forman el proceso diario de preparar un archivo, tomar una captura y enviarla al servidor remoto.
git init # turn this folder into a repository (once)
git add posts/new-post.md # stage the file for your next commit
git commit -m "Add new post" # save a snapshot with a message
git push # copy your commits to the remoteCopy
En la práctica, git push solo funciona después de haber configurado un remoto, por ejemplo con git remote add origin <url>; además, el primer envío de un branch suele requerir git push -u origin main o algo similar. Una vez hecho esto, basta con un simple git push.
De dónde provienen los generadores de sitios estáticos
Con este vocabulario ya establecido, la historia cobra más sentido, ya que cada generación de herramientas añadió uno de los conceptos mencionados anteriormente.
La separación entre la escritura del contenido y el marcado precede con creces a la expresión “generador de sitios estáticos”. HSC, abreviatura de “HTML Sucks Completely”, fue un preprocesador para HTML lanzado por Thomas Aglassinger en 1996. Ya incluía funciones como inclusiones, condicionales y validación de enlaces, aproximadamente una década antes de que la categoría tuviera un nombre propio.
A lo largo de finales de la década de 1990 y la de 2000, la mayoría de las personas que querían un blog optaban por servicios dinámicos alojados como Blogger, LiveJournal o Open Diary, o instalaban software basado en bases de datos como WordPress. Movable Type, una plataforma en Perl creada por Ben y Mena Trott en 2001, siguió un camino diferente: cada vez que se publicaba a través de su interfaz web, el blog se regeneraba como archivos HTML estáticos simples. Los usuarios nunca tocaban una terminal, pero los lectores recibían páginas estáticas. Esto brindó las ventajas de la salida estática a personas que nunca escribirían una orden de compilación.
Nanoc llegó en 2007, creado por Denis Defreyne después de que los sistemas de gestión de contenidos Ruby resultaran excesivamente lentos en su servidor virtual de 96 MB. Introdujo diseños personalizados, metadatos por página, soporte para Markdown y plugins. En diciembre de 2008, Tom Preston-Werner, cofundador de GitHub, lanzó Jekyll, motivado por su insatisfacción con los motores de blogs pesados. Jekyll se basó en las ideas de Nanoc y aportó dos características definitorias: contenido preliminar en YAML al principio de cada archivo de contenido, y funcionalidades para blogs listas para usar desde el primer momento, de modo que una carpeta con archivos Markdown se convertía en un blog sin necesidad de configuraciones adicionales. GitHub Pages se lanzó al mismo tiempo como servicio gratuito de alojamiento estático, y esta combinación fue lo que más contribuyó a popularizar los SSG.
Casi todo lo que ha surgido desde entonces ha sido una reinterpretación del mismo patrón en otros lenguajes. Octopress, ya descontinuado, y Middleman continuaron la línea de herramientas en Ruby. Pelican está basado en Python, mientras que Hyde se desarrolla sobre Laravel.
Steve Francia lanzó en julio de 2013 Hugo, un programa en Go distribuido como un único binario compilado. En comparación con Jekyll, no había entorno de Ruby que instalar ni versiones de gem que armonizar, y su velocidad de generación, medida en segundos incluso para sitios con miles de páginas, se convirtió en su característica distintiva.
A finales de 2017, Zach Leatherman publicó Eleventy (11ty), una alternativa flexible a Jekyll que funciona con JavaScript e se instala mediante npm. Jekyll te vincula a Liquid; Eleventy acepta una larga lista de formatos de plantillas:
- marcado y contenido: HTML puro (
.html), Markdown (.md) y MDX (.mdx)
.11ty.js, TypeScript (.ts), JSX (.jsx) y WebC (.webc).njk), Handlebars (.hbs), Mustache, EJS, Haml y Pug.scss)Algunos de estos formatos requieren un plugin o una configuración adicional para funcionar sin modificaciones, por lo que consulte la documentación actual de Eleventy antes de confiar en uno. Si ya conoce un lenguaje de programación específico, el directorio de generadores de Jamstack.org le permite filtrar herramientas escritas en ese lenguaje.
Muchos generadores en ese directorio no han tenido una nueva versión en años, y para un sitio personal eso suele ser aceptable. Un sitio estático no expone código del lado del servidor ni bases de datos a los visitantes, lo que elimina la superficie de ataque más común en los blogs dinámicos. Si una nueva versión de tu generador añade funciones que no te gustan, puedes seguir usando la antigua, ya que seguirá generando el mismo sitio. La advertencia es que “sin actualizaciones” no significa “sin riesgos”: las dependencias utilizadas en el momento de la compilación, la máquina que ejecuta dicha compilación y cualquier JavaScript de terceros que incluyas siguen requiriendo atención, y una herramienta sin mantenimiento podría dejar de instalarse correctamente en un sistema operativo o entorno de ejecución más reciente.
Git resuelve dos problemas, pero no necesitas ninguno de ellos
Las guías para principiantes casi siempre indican que se debe usar Git. En parte, esto se debe simplemente a la costumbre entre los desarrolladores, pero también hay un factor histórico: Jekyll, el primer SSG ampliamente adoptado, nació como un proyecto de GitHub. Al alojar el contenido en GitHub, Codeberg o GitLab, la pregunta “¿Dónde están mis archivos?” recibe como respuesta “en el repositorio”. Servicios como Neocities o Nekoweb responden de manera diferente: se suben los archivos a través del sitio.
En plataformas de alojamiento basadas en Git, como Codeberg Pages o GitLab Pages, incluso las ediciones realizadas a través de la interfaz web se convierten en commits y se envían en segundo plano. Estás utilizando Git, independientemente de si escribes alguna vez una orden de Git o no.
Si alojas el sitio tú mismo, los archivos se encuentran en tu propia máquina, generalmente en un directorio como /var/www/html en Linux. En una máquina compartida de la comunidad, como un servidor Tildeverse, se ubican en la carpeta pública de tu cuenta; un flujo de trabajo común allí es compilar localmente y utilizar rsync para copiar el resultado al ordenador compartido, donde se sirve automáticamente.
Es útil separar las dos tareas que realiza Git en estos entornos:
- mantener un historial de versiones, para que puedas deshacer una edición incorrecta y ver qué cambió y cuándo
- llevar los archivos compilados al lugar desde donde se sirven
Ninguno de estos trabajos requiere estrictamente Git. rsync, un cliente FTP o un formulario de carga en el navegador son suficientes para publicar un sitio sin problemas, y las copias de seguridad habituales pueden servir como registro histórico en un pequeño proyecto personal. Git es popular porque permite realizar ambas tareas al mismo tiempo, no cuesta nada y se integra con alojamiento gratuito, lo que lo convierte en la opción más sencilla y no en un requisito obligatorio.
La diferencia entre el diagrama ideal y la implementación real
Sobre el papel, la arquitectura de un generador de blogs es casi excesivamente ordenada:
- los artículos son archivos Markdown en la carpeta
posts/ - un template en la carpeta
layout/los muestra - ese template reúne fragmentos HTML de
partials/, comoheader.htmlyfooter.html
config.yml (o equivalente) en la raíz del proyecto contiene parámetros para toda la página, como el nombre o los colores"2024-03-14-my-post-title.md"Lo que el diagrama omite es la infraestructura necesaria. Convertir esas carpetas en una página web renderizada, por ejemplo en _site/, requiere un entorno de ejecución de lenguaje de programación para hacer funcionar el generador, y cada eslabón de esa cadena es un punto donde pueden ocurrir fallos.
Las herramientas convencionales se esfuerzan por ocultar esto detrás de un único comando, como hugo build o npx @11ty/eleventy --serve. La opción --serve en el comando Eleventy inicia un servidor de desarrollo local y vuelve a compilar cada vez que se guarda un archivo fuente, en lugar de compilar una sola vez y terminar. Ese rápido ciclo de retroalimentación es lo que hace que editar un sitio estático parezca casi tan inmediato como editar una página en tiempo real.
Las plataformas de despliegue extienden la misma idea a la nube. Netlify, o Coolify de auto-hospedaje, ejecutan tu proceso de construcción en una máquina remota, detectan qué generador utilizas, ejecutan la orden correspondiente y publican la carpeta de resultados en una dirección como yoursitename.netlify.app. Conceptualmente es lo mismo que subir HTML escrito a mano a Neocities y obtener yoursitename.neocities.org, excepto que la construcción se realiza en su máquina. Flujos de trabajo similares los ofrecen surge.sh, GitHub Pages, Vercel y, por parte de Cloudflare, su producto Pages; la opción adecuada depende de cuánto valores la comodidad frente a la independencia de las grandes plataformas. Si deseas ver un flujo de despliegue completo de principio a fin, nuestra guía sobre enviar un sitio web pequeño a Cloudflare aborda un caso concreto.
Por qué una sola coma al final puede arruinar todo
Cada una de esas comodidades se basa en suposiciones: que tus archivos estén correctos, que el entorno de ejecución del lenguaje esté instalado sin problemas y que te sientas cómodo en una terminal. Los desarrolladores suelen sobreestimar cuán común es esta última habilidad, un punto ciego que este cómic de XKCD ilustra muy bien.
La compilación también es frágil. Un pequeño error de sintaxis en un archivo importante, tan sencillo como una coma adicional, puede detener por completo la instalación o la compilación. Peor aún, el mensaje de error suele provenir del entorno de ejecución o del analizador subyacente, no del generador, por lo que está redactado en términos del lenguaje de programación y no de tu sitio web. Un ejemplo real: un archivo de datos JSON con una coma al final después de su última propiedad hace que la compilación en Netlify falle, mostrando un rastro del analizador que nunca menciona el archivo real en términos fáciles de entender para principiantes.
Al enfrentarse a un resultado así, muchas personas deciden razonablemente escribir HTML a mano, pasar a un CMS alojado o renunciar por completo a tener un sitio web. Este último resultado es la verdadera pérdida. Algunos hábitos reducen las posibilidades de llegar a eso:
- Ejecutar la compilación localmente con el servidor de desarrollo antes de subir los cambios, para que los fallos aparezcan primero en la propia pantalla
- Cambiar una cosa a la vez, de modo que la edición más reciente sea el sospechoso obvio cuando algo falla
- Leer el error de abajo hacia arriba y buscar un nombre de archivo y un número de línea, que suele ser la pista real
- Validar JSON y YAML con una extensión de editor o un linter, ya que estos formatos causan una gran parte de los errores en principiantes
- Hacer commits frecuentes con el estado del trabajo, para poder volver siempre a la última versión que funcionó
Aprender modificando un proyecto inicial
Una forma comprobada de aprender a usar un generador es tomar un inicio o tema listo, comenzar a desarrollarlo y luego modificarlo poco a poco hasta comprender cada archivo. Con el tiempo, tendrás suficientes conocimientos como para crear uno propio desde cero. Los buenos inicios para este propósito comparten algunas características: documentación clara, un número reducido de archivos y un lugar evidente tanto para el contenido como para la configuración. Algunos ejemplos típicos son los siguientes:
- un inicio de Hugo donde las entradas se guardan en
/posty la personalización del sitio se realiza enhugo.toml, opcionalmente con funciones de IndieWeb como microformats2 y una tarjeta h preconstruida - un inicio de Eleventy donde las entradas se encuentran en
/postsy los detalles del sitio están en un archivo de datos comosite.js - un inicio de Jekyll donde las entradas se almacenan en
/_postsy la configuración se encuentra en_config.yml
Los iniciadores deliberadamente sencillos son una ventaja para aprender. Cuando el estilo es mínimo, la estructura es fácil de ver, y todo el trabajo de diseño queda en tus manos para que lo realices tú mismo.
Generadores diminutos con casi ninguna parte móvil
Hugo, Eleventy y Jekyll son las opciones más populares, pero existe toda una familia de generadores muy pequeños para quienes quieren comprender la herramienta completa en una tarde.
- barf, abreviatura de “blogs are really fun”, es un script shell de aproximadamente 170 líneas creado por btxx, derivado de blog.sh de Karl Bartel. No cuenta con información preliminar ni plantillas. Escribes archivos en Markdown, ejecutas
make build, y subes la carpeta resultantebuild/mediante rsync. Se generan feeds RSS automáticamente; el script funciona de forma nativa en OpenBSD, macOS y Linux, y su hoja de estilo consta de cuatro líneas. El README y una demostración en vivo muestran cómo queda el resultado final.
bb.sh, de aproximadamente 1,000 líneas que no requiere dependencias además de las utilidades estándar de Unix como date, grep, sed y head. Carlos Fenollosa escribió la primera versión en 2011 y explicó el enfoque en una entrada de blog de esa época; seguía manteniéndose al momento de redactar este texto. Una vez que bb.sh se encuentre en el directorio público de su servidor, ejecutar ./bb.sh post crea una nueva entrada. Los borradores, las etiquetas, Markdown y RSS funcionan sin necesidad de realizar ningún paso de instalación. Una versión derivada de la comunidad, bashblog-ng, añade más funcionalidades.Otras opciones interesantes:
- ssg es un script de shell compatible con POSIX desarrollado por Roman Zolotarev que sirvió de inspiración para varias herramientas de esta lista; pyssg es una versión reescrita en Python.
- sw, escrito en C, es un framework web deliberadamente minimalista, y su bifurcación simple-static lo reduce aún más a lo que su README describe como el generador de sitios estáticos más simple que su mantenedor podría imaginar.
- makesite.py es el equivalente en Python de barf y bashblog, con menos de 130 líneas, creado por Sunaina Pai bajo el principio de que el propio código es la documentación. No existe una capa de configuración; se lee el script y se edita directamente.
Ninguno de estos llega siquiera cerca del conjunto de funciones de Hugo o Eleventy, y ese es precisamente el objetivo. Lo que sacrifican en plugins y formatos de plantillas lo compensan con transparencia: cuando algo falla, todo el programa cabe en la pantalla.
Si está dispuesto a salir por completo de la web, publicar en el protocolo Gemini es otra opción. Las páginas de Gemini utilizan un formato de texto simple que se sirve tal cual, por lo que a menudo no hay nada que generar en absoluto.
Puntos clave
- Aprenda primero a escribir una página a mano; un generador automatiza la repetición que ya debería reconocer.
- La mayor confusión con SSG se debe al vocabulario. Una vez que están claros el código fuente, la salida, la generación, el diseño, los fragmentos y el contenido preliminar, la documentación de cada herramienta tiene un formato similar.
- Los diseños, los fragmentos y los archivos de datos globales existen para que un cambio realizado una vez se refleje en todas partes en la siguiente generación.
- Git proporciona un historial y una vía de publicación, pero rsync, FTP o la carga a través de un navegador son alternativas válidas para un sitio personal.
Lecturas relacionadas
- Mapeo del vocabulario de autenticación: claves API, sesiones, JWT, OAuth2, OIDC, SSO — Aprenda cómo se relacionan las claves API, sesiones, JWTs, OAuth2, OpenID Connect y SSO al clasificar cada uno bajo una misma pregunta: ¿quién está realizando la llamada o qué pueden hacer?
- Angular CLI más allá de ng serve: Generadores, destinos, caché y estadísticas de construcción — Conozca las opciones de Angular CLI que eliminan el trabajo rutinario: flags de generadores, ayuda integrada, comandos por proyecto, destinos de ng run, limpieza del caché y estadísticas de construcción.