README

Una documentación hecha con Ehundu, el generador de sitios estáticos en PHP. Es un andamio: la estructura de partida de una documentación, con el menú por secciones, el índice de cada página, el «anterior» y «siguiente» y un enlace para editar cada página en tu repositorio. Cambias los textos, los datos y el CSS, y es tuyo.

Puedes verlo funcionando, sin instalar nada, en andamio-documentacion.ehundu.com.

Necesitas PHP 8.4 o superior y Composer.

Empezar

Si lo has creado con composer create-project, ya está todo instalado. Si has usado el botón «Use this template» de GitHub, o has descargado el zip, instala el motor:

composer install

Las tres órdenes que vas a usar:

composer servir      # lo previsualiza en http://127.0.0.1:8000/ y rehace solo lo que cambia
composer compilar    # deja el sitio terminado en la carpeta salida/
composer desplegar   # lo compila y lo sube al servidor que digas en sitio.yml

Escribir una página

Copia una página de contenido/guias/, ponle un nombre nuevo (será su dirección: mi-pagina.md sale en /guias/mi-pagina/) y cambia su texto y su front matter: el título, la descripción y el orden. No hace falta tocar nada más: la página aparece en el menú, en la portada y en el «anterior» y «siguiente».

Las páginas se agrupan en secciones. Cada sección es una carpeta de contenido/ con un _datos.yml, y su título y su orden están en datos/secciones.yml. Para añadir una, una carpeta y una entrada en esa lista. La propia documentación que trae el andamio lo cuenta con detalle.

Qué hay en cada carpeta

sitio.yml                  el nombre, la dirección, los encabezados y adónde se publica
contenido/                 las páginas, en Markdown: cada fichero es una página
  index.md                 la portada
  empezar/, guias/, referencia/
                           las secciones; cada una con su _datos.yml
datos/                     las secciones del menú, el nombre del proyecto y su repositorio
plantillas/                el HTML de cada tipo de página, con Twig
parciales/                 trozos de HTML que reutilizan las plantillas (el menú y el índice)
publico/                   el CSS y el icono: se copia tal cual a la raíz

salida/ (el sitio compilado) y .ehundu/ (lo que recuerda el motor) los crea Ehundu y no se versionan.

Lo primero que cambiar

En sitio.yml, el nombre y la dirección del sitio.
En datos/cliente.yml, el nombre de tu proyecto y, si quieres el enlace «Editar esta página», la dirección de tu repositorio.
Los textos de contenido/index.md y las páginas de ejemplo (puedes borrarlas).
En publico/css/estilos.css, los colores: están al principio, en variables, con su pareja para el modo oscuro.

Lo que no trae

No tiene buscador, ni versiones, ni varios idiomas. Las preguntas frecuentes de la propia documentación cuentan cómo resolver cada cosa.

Publicarlo

Descomenta la sección despliegue de sitio.yml y rellénala. La contraseña no va ahí, porque sitio.yml se comparte: crea un fichero .secretos.yml en la raíz del proyecto, entre comillas simples:

despliegue:
  clave: 'la-contraseña'

Antes de subir nada, mira qué haría:

composer desplegar -- --simular

Y cuando todo cuadre, composer desplegar. La guía Desplegar el sitio explica los destinos (carpeta, FTP, SFTP y S3) y cómo decide Ehundu qué sube y qué borra.

Para seguir

Tu primer sitio, un recorrido paso a paso.
La hoja de referencia rápida, con todo lo que vas a necesitar cada día.
La documentación completa.

Licencia MIT.

ehundu / andamio-documentacion

Package info

Security

Statistics