✨ 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,59 @@
# Si vienes de Axum
PageTop está construido **sobre** [Axum](https://docs.rs/axum) y [Tokio](https://tokio.rs), no al
lado. Lo que sabes de Axum sigue valiendo: las rutas, los extractores, las respuestas y el
*middleware* son los suyos, reexportados en `web`. PageTop añade lo que una aplicación web completa
necesita encima, y una forma de organizarlo.
## Lo que se traduce directamente
| En Axum | En PageTop | Qué cambia |
|---|---|---|
| `Router::new().route(...)` | `configure_router()` de cada extensión | Cada extensión añade sus rutas al mismo `Router` |
| `axum::routing::get`, `post`... | `web::get`, `web::post`... | Nada: son los mismos |
| `Path`, `Query`, `Form`, `Json` | `web::Path`, `web::Query`, `web::Form`, `Json` | Nada |
| `Request` | `HttpRequest` | Una vista clonable de la petición, que no consume el cuerpo y se puede pedir junto a cualquier extractor |
| `impl IntoResponse` | `IntoResponse`, `Response` | Nada; `Markup` y `ErrorPage` también la implementan |
| `Redirect::to(...)` | `Redirect::see_other(...)`, `found()`, `temporary()`... | Un constructor por código de estado |
| `middleware::from_fn` | `web::middleware::from_fn` en `configure_middleware()` | Se aplica a las rutas de todas las extensiones |
| `ServeDir` | `serve_static_files!` en `configure_static_files()` | Los archivos pueden ir dentro del binario |
| `#[tokio::main]` | `#[pagetop::main]` | Prepara el *runtime* que usa PageTop |
| `#[tokio::test]` | `#[pagetop::test]` | Igual, para las pruebas |
| `State<T>` | Ajustes con `#[settings]`, estáticos propios | Ver abajo |
## Lo que PageTop añade
- **Páginas completas** con `Page`: el `<head>`, los recursos sin duplicados, el idioma, la
dirección del texto y la estructura del tema.
- **Componentes** con su HTML, sus estilos y su comportamiento, que se adaptan al tema activo.
- **Temas intercambiables** desde la configuración.
- **Configuración en cascada** con validación al arrancar.
- **Traducciones** con Fluent, integradas en el binario.
- **Extensiones** con dependencias y un orden de arranque garantizado, que se suman con una línea.
- **Páginas de error** (403, 404, 500...) con el aspecto del sitio.
## El estado de la aplicación
En Axum, el estado compartido suele viajar con `State<T>`. En PageTop, cada extensión gestiona el
suyo:
- La **configuración** se declara con `#[settings]` y se lee desde cualquier sitio con su estático
(`SETTINGS.page_size`), sin pasarla de *handler* en *handler*.
- Los **recursos** que se crean al arrancar (una conexión, un cliente HTTP, una caché) se
inicializan en `initialize()` y se guardan en un estático (`OnceLock`, `LazyLock`). Así lo hace
`pagetop-seaorm` con su `dbconn()`. Paso a paso en [Compartir un servicio entre
rutas](../how-to/services.md).
- Lo que depende de **cada petición** (el idioma, el usuario, el tema) está en el `Context` que crea
`Page::new(request)` y que reciben todos los componentes.
## Mezclar código de Axum
`configure_router()` recibe y devuelve un `Router` de Axum, así que puedes añadirle cualquier cosa
que Axum admita: rutas con capas propias, servicios de Tower, rutas anidadas o un `Router`
existente con `merge()`. Una ruta que devuelve JSON convive sin problemas con las que devuelven
páginas.
## Siguiente
- [Arquitectura: del arranque a la respuesta](architecture.md).
- [Tu primera aplicación](../tutorials/first-app.md).