Ehundu

Ehundu es un generador de sitios estáticos escrito en PHP. Toma una carpeta con contenido en Markdown, datos en YAML y plantillas Twig, y produce un sitio web de HTML plano que se puede alojar en cualquier servidor.

Estado: 0.16. Compila sitios reales, también en varios idiomas, los previsualiza y los publica, saca en PDF las páginas que lo piden, genera una página por cada etiqueta, publica las entradas en su fecha, deja las páginas de una carpeta sin la carpeta en la URL, avisa a los lectores de pantalla de los enlaces que abren otra pestaña, da un id, y si se quiere un enlace permanente, a los encabezados del Markdown, para enlazar a un apartado o hacer un índice, ordena los textos al estilo español, sin contar los signos ¿ y ¡, enlaza el CSS y el JavaScript de una página como un fichero con la huella de su contenido en el nombre, para que el navegador lo guarde, convierte a HTML el texto con formato de un campo, de una línea o de varios párrafos, con el filtro markdown, escribe el srcset (y el <picture>, si hay varios formatos) de las imágenes que ya tienen variantes de ancho, parte una lista larga en páginas con paginar, reparte la compilación y la subida de un sitio grande en varias llamadas de unos segundos cada una, recuerda lo que compila entre un proceso y otro para rehacer solo lo que un cambio afecta, marca sus páginas con una etiqueta generator (que se quita con generador: no), y lleva la versión del formato (formato: 1 en sitio.yml) y una lista corta y documentada de lo que se promete de la biblioteca (docs/biblioteca.md), que es lo que la 1.0 congelará. La 0.16 es la relectura final del contrato: tres lectores comprobaron cada afirmación contra el código, lo que el motor hacía sin decirlo queda escrito, lo que antes tomaba a ciegas (un formato que no es un número, una url con ruta, un punto en el nombre de una página que no es de idioma, un robots.txt.twig) detiene el build o avisa, las fechas de un campo propio caen en la zona del sitio, y lo que la incremental recuerda entre procesos se guarda y se lee por registros, con bastante menos memoria de PHP y un aviso claro si no cabe en el memory_limit. El registro de decisiones está al final del documento, el esquema tiene el suyo (docs/esquema.md) y ehundu --version dice qué versión es. Hasta la 1.0 el formato del proyecto todavía puede cambiar; cada cambio queda anotado, con su motivo, en el registro de decisiones de docs/formato.md.

Por qué otro generador

Los generadores de sitios estáticos más conocidos están pensados para ejecutarse desde la línea de comandos, en el ordenador de quien desarrolla o en un servicio de integración continua. Ehundu nace de una necesidad distinta: poder compilar un sitio también desde un proceso web, en un alojamiento PHP corriente, con los límites de tiempo y de recursos que eso supone.

Eso permite que una herramienta de edición guarde un cambio y publique el sitio al momento, sin depender de servicios externos, repositorios en la nube ni cadenas de despliegue ajenas. Y permite también lo contrario: trabajar sin ninguna herramienta de edición, con un editor de texto y la línea de comandos, exactamente con el mismo resultado.

Principios

PHP puro y pocas exigencias. Ehundu funciona con PHP 8.4 o superior y no necesita ejecutar programas externos ni extensiones poco habituales. Si un alojamiento compartido ejecuta PHP, puede ejecutar Ehundu.

Tu contenido son ficheros. Todo lo que define un sitio vive en su carpeta: Markdown, YAML, plantillas y archivos estáticos. Sin base de datos y sin nada oculto que cambie el resultado (lo que el motor recuerda entre compilaciones vive en una carpeta .ehundu/ que se puede borrar). Una carpeta copiada a otra máquina compila igual.

Sin dependencia de servicios. Ehundu se apoya en software libre que se puede conservar y mantener, nunca en servicios cuyas condiciones pueden cambiar de un día para otro. Publica en una carpeta, por FTP, por SFTP o en cualquier almacenamiento compatible con S3, sin APIs propias de ningún proveedor.

En español. El formato del proyecto está en español: las carpetas se llaman contenido, plantillas o publico, y los campos del front matter titulo, fecha o etiquetas. Es una decisión deliberada. La comunidad hispanohablante que desarrolla para la web es enorme y merece herramientas pensadas en su idioma. Para migrar desde Eleventy o Lume se aceptan los nombres ingleses habituales (title, date, tags, layout, permalink).

Instalación

Hace falta PHP 8.4 o superior con la extensión mbstring. Para publicar por FTP, además, la extensión ftp, que viene con PHP aunque a veces está desactivada; y para FTPS o S3, openssl, que traen casi todas las instalaciones.

Para generar el PDF de una página (pdf: sí) hace falta además dompdf, que es PHP puro y necesita la extensión dom: composer require dompdf/dompdf. Es opcional, y el ehundu.phar no lo trae.

Un solo fichero. Descarga ehundu.phar de la página de versiones y úsalo con PHP:

php ehundu.phar compilar mi-sitio

Con Composer, como orden global:

composer global require ehundu/ehundu

o dentro de un proyecto, que es como lo usaría un programa que incruste el motor:

composer require ehundu/ehundu

La orden queda en vendor/bin/ehundu.

Un primer sitio

mi-sitio/
  sitio.yml
  contenido/
    index.md
    blog/
      _datos.yml
      primer-articulo.md
  plantillas/
    pagina.twig

sitio.yml dice cómo se llama el sitio y dónde se publica:

nombre: Mi sitio
url: https://www.ejemplo.com
idioma: es

Cada página es un Markdown con su front matter:

---
titulo: Primer artículo
fecha: 2026-10-01
---

Texto del artículo en **Markdown**.

Lo que comparten todas las páginas de una carpeta va en su _datos.yml, así que un artículo nuevo solo necesita título y texto:

etiquetas: [blog]
url: "/blog/{{ titulo|slug }}/"

La plantilla es Twig, con las funciones que añade Ehundu, como coleccion(), y las fechas en el idioma de la página:

<!doctype html>
<html lang="{{ pagina.idioma }}">
<meta charset="utf-8">
<title>{{ pagina.titulo }} · {{ sitio.nombre }}</title>
<main>
  <h1>{{ pagina.titulo }}</h1>
  {{ pagina.contenido }}
  {% for articulo in coleccion('blog')|invertir %}
    <p><a href="{{ articulo.url }}">{{ articulo.titulo }}</a>, {{ articulo.fecha|fecha }}</p>
  {% endfor %}
</main>

ehundu compilar mi-sitio escribe el resultado en mi-sitio/salida/: la portada, /blog/primer-articulo/ y un sitemap.xml.

Las órdenes

ehundu compilar [carpeta]     compila el proyecto en su carpeta salida/
ehundu servir [carpeta]       lo previsualiza en el navegador y lo
                              recompila cuando cambia algo
ehundu desplegar [carpeta]    lo compila y lo publica en el destino de
                              sitio.yml

servir rehace solo lo que afecta a cada cambio, en unas décimas de segundo, y da siempre lo mismo que una compilación completa. desplegar sube lo nuevo o cambiado y borra lo que subió Ehundu y ya no se genera; lo demás que haya en el servidor no lo toca nunca. Con --simular dice qué haría sin hacerlo. ehundu --ayuda enseña todas las opciones.

Qué hace

• Markdown CommonMark, con tablas, notas al pie, tachado y enlaces automáticos. Una imagen sola en su párrafo es una figura con su pie, y los enlaces a otros dominios se abren aparte.
• Atajos para lo que el Markdown no tiene, sin meter lógica en el texto: [imagen …], [video …] (YouTube sin cookies y Vimeo sin seguimiento), [archivo …] (con su tipo y su peso) y [dato …]. Un sitio puede añadir los suyos o cambiar el marcado de estos con una plantilla.
• Plantillas Twig con colecciones por etiqueta, filtros para ordenarlas y recorrerlas, SVG incrustados, el ancho y el alto de las imágenes, y el menú activo.
• Datos globales en YAML o JSON, y por carpeta en un _datos.yml que heredan todas sus páginas y subcarpetas.
• URL que salen de la ruta del fichero o de un patrón con los campos de la página.
• Una página por cada valor de un campo, como una por etiqueta, con una sola página que declara agrupar: una etiqueta nueva tiene su página sin que nadie la escriba.
• Listas partidas en páginas con paginar: la propia página es la primera, en su dirección, y el motor genera las demás (/blog/pagina/2/, o la forma que se pida), con las entradas de cada trozo y los enlaces para moverse. Una entrada nueva que desborde la última abre la siguiente sola.
• Imágenes con varios anchos. El motor no las genera, pero si otra herramienta las deja en publico/ (foto-480.webp, foto-960.webp…) y el sitio las declara en imagenes, variantes(), el atajo [imagen …] y las figuras del Markdown escriben el srcset con el ancho real de cada fichero.
• Varios idiomas, con un fichero por idioma en el mismo árbol (contacto.md, contacto.eu.md): cada idioma con su prefijo en la URL, las traducciones enlazadas entre sí para los hreflang y el selector de idioma, colecciones y datos de cada idioma, y las fechas en castellano, euskera, inglés o alemán. Traducir solo parte del sitio es lo normal, no una excepción.
• El CSS y el JavaScript de cada página, reunidos e incrustados en ella o enlazados como un fichero cuyo nombre lleva la huella de su contenido, para que el navegador lo guarde: cada plantilla declara lo que necesita donde lo usa. Y version('css/estilo.css'), para dar a cualquier otro fichero de publico/ una dirección que cambia cuando cambia su contenido.

Lo que no hace, a propósito, en esta versión: generar las variantes de una imagen (solo lee las que ya están hechas), compilar CSS o JavaScript, o ejecutar código propio de cada sitio. El formato está pensado para que lo que llegue después no obligue a cambiarlo, y ya reserva lo que necesitará.

Documentación

• docs/formato.md: el formato de un proyecto, completo. Carpetas, sitio.yml, datos, campos, URL, colecciones, plantillas, Markdown, atajos, CSS y JavaScript, varios idiomas, y el registro de las decisiones tomadas.
• docs/previsualizacion.md: ehundu servir.
• docs/compilacion.md: cómo decide la compilación incremental qué rehace.
• docs/despliegue.md: ehundu desplegar y cada destino.
• docs/biblioteca.md: lo que se promete de la biblioteca PHP y de la orden de consola, y qué es interno.

Dentro de otro programa

La orden de consola es una capa fina sobre una biblioteca, y un programa puede usar esa misma biblioteca para compilar desde un proceso web:

use Ehundu\CompiladorEnProceso;
use Ehundu\ErrorDeProyecto;
use Ehundu\Proyecto;

try {
    $informe = (new CompiladorEnProceso())->compilar(Proyecto::abrir('/ruta/a/mi-sitio'));
    echo $informe->resumen(), "\n"; // Compilado: 2 páginas en 0,07 s.

    foreach ($informe->avisos as $aviso) {
        echo $aviso, "\n";          // con fichero y línea
    }
} catch (ErrorDeProyecto $error) {
    echo $error->getMessage();      // $error->fichero y $error->linea, por separado
}

Ehundu\Despliegue\Desplegador publica de la misma forma y recibe las contraseñas directamente, sin fichero. Los errores y los avisos están en español y señalan el fichero y la línea, para que el programa pueda enseñarlos tal cual. Lo que hace falta para compilar de forma incremental desde un proceso web está explicado en docs/compilacion.md.

El nombre

Ehundu es una palabra en euskera que significa «tejer». La elección no es casual: web, en inglés, es literalmente una tela, un tejido. Un generador de sitios hace eso mismo, entrelazar contenido y plantillas hasta formar páginas.

Se pronuncia más o menos «e-ún-du».

Licencia

Ehundu es software libre bajo licencia MIT. Consulta el fichero LICENSE.

La licencia cubre el código y la documentación, pero no el logotipo ni las ilustraciones de Nidel que hay en marca/: sus condiciones están en marca/README.md.

---

In English

Ehundu is a static site generator written in PHP, designed to build sites both from the command line and from within a web process on ordinary shared PHP hosting. The current version is 0.16: it builds Markdown and Twig sites, multilingual ones included, renders the pages that ask for it as PDF (with the optional dompdf), generates one page per tag, publishes entries on their date, drops a folder name from its pages' URLs, flags external links to screen readers, gives Markdown headings an id (and, if asked, a permalink) so pages can link to a section or build a table of contents, sorts text the way a Spanish dictionary does (ignoring the opening marks ¿ and ¡), links a page's CSS and JavaScript as a file named after a hash of its contents so browsers can cache it for a year, converts the formatted text of a field to HTML, inline or in blocks, with a markdown filter, writes the srcset of images that already have width variants, splits long lists into pages, previews them with incremental rebuilds, spreads the build and the upload of a big site over several calls of a few seconds each (for a web process with a time limit), remembers what it built between one process and the next so that a change rebuilds only the pages it affects, marks its pages with a generator meta tag (generador: no turns it off), and deploys them to a folder, FTP, SFTP or any S3-compatible storage. It needs PHP 8.4 or later with mbstring and nothing else, and ships as a single ehundu.phar or as the Composer package ehundu/ehundu. Projects declare the version of the format they use (formato: 1), and docs/biblioteca.md lists the short part of the PHP library that 1.0 will promise to keep. Version 0.16 is the final read-through of the contract: every claim was checked against the code, what the engine did without saying so is now written down, and a few inputs it used to take at face value (a malformed formato, a url with a path, a dot in a page name that is not a language, a robots.txt.twig) now stop the build or raise a warning. What the incremental build remembers between processes is saved and read record by record, with much less PHP memory and a clear warning when it does not fit in memory_limit. ehundu --version prints the version.

Its project format is deliberately in Spanish (folder names, front matter fields), as a commitment to Spanish-speaking web developers; the usual English field names are accepted to ease migrations from Eleventy or Lume. The documentation is in Spanish, like the format.

The name ehundu is Basque for "to weave".

Ehundu is free software under the MIT licence. The licence covers the code and documentation, not the logo or the Nidel illustrations in marca/ (see marca/README.md).