Documentación · Guías

La estructura de un proyecto

Qué guarda cada carpeta, cómo se convierte en direcciones y qué no debes versionar.

Versión 0.16

Un proyecto de Ehundu es una carpeta con los nombres de siempre. Esto es lo que tendrás casi siempre:

mi-sitio/
  sitio.yml
  contenido/
    index.md
    blog/
      _datos.yml
      un-articulo.md
  datos/
    menus.yml
  plantillas/
    base.twig
    pagina.twig
  parciales/
    cabecera.twig
  publico/
    css/
    img/
    favicon.ico

Los nombres de las carpetas no se configuran, y es a propósito: cuando has visto un proyecto, los has visto todos. Puedes abrir el de otra persona, o pasar de uno tuyo a otro, sin averiguar cómo está organizado.

Qué va en cada carpeta¶

Carpeta	Qué guarda
`sitio.yml`	El nombre, la dirección y el resto de la configuración. Es lo único obligatorio.
`contenido/`	Tus páginas, en `.md` y `.twig`. Cada una genera una página, y su dirección sale de su ruta. Lo que no es una página (una foto, un PDF) se copia tal cual.
`datos/`	Lo que usan varias páginas: el menú, los datos de la empresa, los textos del pie. Un fichero `datos/menus.yml` es `datos.menus` en las plantillas.
`plantillas/`	Los layouts que envuelven a las páginas.
`parciales/`	Trozos de HTML para reutilizar con `{% include %}`. En `parciales/atajos/` están las plantillas de tus atajos.
`publico/`	El CSS, el JavaScript, las imágenes, las tipografías y el favicon. Se copia a la raíz del sitio: `publico/img/logo.svg` queda en `/img/logo.svg`.

De la ruta a la dirección¶

Cada fichero de contenido/ se convierte en una dirección con su carpeta y su nombre, y index.md es la página de su carpeta:

contenido/index.md              →  /
contenido/servicios/index.md    →  /servicios/
contenido/servicios/diseno.md   →  /servicios/diseno/
contenido/blog/foto.jpg         →  /blog/foto.jpg

La última no es una página, así que se copia con la misma ruta. Si quieres otra dirección para una página, la escribes en su front matter con url.

Lo que heredan las páginas¶

Un fichero _datos.yml dentro de una carpeta de contenido/ da valores a todas las páginas de esa carpeta y de las que cuelgan de ella. Así, en contenido/blog/_datos.yml pones lo que comparten todos los artículos y no lo repites en cada uno:

plantilla: articulo
etiquetas: [blog]

Si una página escribe el mismo campo, gana la página. Con etiquetas, css y js no hay duelo: se suman.

Lo que escribe el motor¶

Ehundu solo lee de la carpeta del proyecto y solo escribe en dos sitios:

salida/ es el sitio terminado, el que subes al servidor. Se rehace en cada compilación.
.ehundu/ es lo que el motor recuerda entre una compilación y la siguiente, para rehacer solo lo que ha cambiado. Puedes borrarlo cuando quieras: lo único que pierdes es el ahorro de la próxima vez.

Junto a ellos puede haber un .secretos.yml con las contraseñas del despliegue. Ninguno de los tres va a Git:

salida/
.ehundu/
.secretos.yml

Dos cosas que pillan¶

Un punto en el nombre de una página está reservado para el idioma. contacto.eu.md es la página de contacto en euskera. Por eso guia.v2.md o 2024.10.01-titulo.md detienen la compilación con un error que nombra el fichero: usa guiones (guia-v2.md).
Los ficheros que empiezan por guion bajo no se copian a salida/. Por eso _datos.yml no llega al sitio publicado. Los .md y los .twig con guion bajo siguen siendo páginas.

El detalle completo está en la estructura del proyecto y en los ficheros de contenido.