✨ Serve the PageTop guides with pagetop-mdbook

Rebuild the website on the current PageTop API, with Bootsier as its
theme and edition 2024. Add the first Spanish guide (doc/v0.6/es) as an
mdBook book, built in build.rs and served with pagetop-mdbook, and the
/doc/latest/{lang} redirect.

Add `tools/doccheck.sh` to check the links of the guides and to compile,
run and test their examples against PageTop.

Move the configuration to config/common.toml and translate the README
to English.
This commit is contained in:
Manuel Cillero 2026-10-17 08:06:02 +02:00
parent e41e71cc78
commit 1a41a456d4
80 changed files with 14112 additions and 1218 deletions

View file

@ -0,0 +1,68 @@
# HTML por la red: por qué HTMX
PageTop genera HTML en el servidor. Para la interactividad podría haber elegido un *framework* de
JavaScript que pidiera JSON y pintara la interfaz en el navegador. Elige [HTMX](https://htmx.org)
porque encaja con todo lo demás: el servidor sigue generando el HTML, y el navegador sólo decide
cuándo pedirlo y dónde ponerlo.
## Dos formas de hacer una interfaz interactiva
| | Aplicación de una sola página (SPA) | HTMX |
|---|---|---|
| El servidor envía | JSON | HTML |
| La interfaz se genera en | El navegador, con JavaScript | El servidor, con los mismos componentes que la página |
| Estado de la interfaz | Duplicado: en el servidor y en el cliente | En el servidor |
| Lo que hay que mantener | Dos aplicaciones y la API que las une | Una aplicación |
| Validación | En los dos lados | En el servidor |
| Sin JavaScript | No funciona | Funciona, con recargas completas, si se diseña así |
Con HTMX, una ruta que responde a una interacción es una ruta como las demás: recibe la petición,
consulta lo que haga falta y devuelve HTML. No hay que diseñar una API, ni serializar, ni mantener
en sincronía dos modelos de datos.
## Por qué encaja con PageTop
- **Los mismos componentes.** El fragmento que devuelve una ruta para HTMX se genera con los mismos
componentes, el mismo tema y las mismas traducciones que la página entera. No hay una segunda
versión de la interfaz en JavaScript.
- **Los atributos son sólo atributos.** Los componentes de PageTop no conocen HTMX. Aceptan
atributos con `with_prop()`, y `hx-get` es uno más. Por eso HTMX es una extensión opcional, y
un componente sirve igual con HTMX o sin él.
- **Lo que se prueba es HTML.** Una ruta para HTMX se prueba como cualquier otra: se envía la
petición y se comprueba el HTML y las cabeceras de la respuesta. El comportamiento en el navegador
lo declaran los atributos, sin lógica propia que probar.
- **Un solo lenguaje.** La lógica de la interfaz está en Rust, comprobada por el compilador.
## Mejora progresiva
Una página bien hecha con HTMX funciona **antes** de que HTMX llegue: los enlaces llevan su `href` y
los formularios su `action`. HTMX intercepta esa navegación y la convierte en una petición parcial,
y la ruta responde según quién llame:
```text
+--> HX-Request: true --> only the fragment
GET /plants?q=to ------+
+--> (no header) --> the whole page
```
Así, la misma URL sirve para buscar sin recargar, para compartir el resultado y para recargar la
página. Las guías de [búsqueda](../how-to/htmx-search.md) y de [tablas](../how-to/htmx-tables.md) lo
aplican.
## Cuándo no es la herramienta adecuada
HTMX resuelve muy bien las interfaces de gestión, los formularios, los listados, los paneles y la
mayoría de webs con contenido. No es la mejor opción para:
- interfaces que deben funcionar **sin conexión**;
- interacciones de **alta frecuencia** en el propio navegador, como un editor gráfico, un juego o
arrastrar elementos con respuesta inmediata a cada píxel;
- aplicaciones donde casi todo ocurre en el cliente y el servidor apenas interviene.
Para esos casos puntuales, nada impide añadir JavaScript propio a una página o a un componente:
PageTop lo gestiona como cualquier otro recurso.
## Siguiente
- [Tareas del huerto con HTMX](../tutorials/htmx-tasks.md): el enfoque en la práctica.
- [HTMX: atributos, cabeceras y respuestas](../reference/htmx.md).