✨ 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,131 @@
# Arquitectura: del arranque a la respuesta
Una aplicación PageTop vive dos momentos distintos: el **arranque**, que ocurre una vez y prepara
todo, y la **petición**, que ocurre miles de veces y debe ser rápida. Entender qué pasa en cada uno
explica casi todas las decisiones de diseño de PageTop.
## Un árbol de extensiones
Una aplicación es un **árbol de extensiones**. En la raíz está la tuya; de ella cuelgan las que
declara como dependencias, y de esas, las suyas:
```text
MyApp <- root extension
├── Bootsier <- theme
├── User <- accounts and permissions
│ ├── Admin
│ ├── SeaORM <- database
│ └── Htmx
└── Blog <- your feature
└── SeaORM <- the same one: each extension is registered once
```
Este árbol es independiente de las dependencias de `Cargo.toml`: Cargo decide qué se **compila**;
`dependencies()` decide qué se **activa** y en qué orden. Una extensión compilada pero que nadie
declara no registra rutas ni ajustes.
Separar la extensión raíz en `src/lib.rs` y dejar `src/main.rs` con lo mínimo permite usar la
aplicación como biblioteca, por ejemplo desde las pruebas:
```text
my-app/
├── Cargo.toml
├── config/
│ ├── common.toml <- common settings
│ └── local.toml <- local settings (not versioned)
└── src/
├── lib.rs <- root extension
├── main.rs <- startup
└── locale/ <- translations
├── en-US/
└── es-ES/
```
## El arranque
`Application::prepare()` sigue siempre los mismos pasos:
```text
Application::prepare(&MyApp)
1. banner and traces [log] settles how much is traced and where
2. language and time zone the defaults of [app]
3. register extensions walks the tree: dependencies first, each one once
4. load settings every settings() section, validated
5. default theme the one in [app] theme, or Basic with a warning
6. register actions every actions(), sorted by weight
7. initialize extensions every initialize(), dependencies first
|
v
.run()
8. build the server routes + middleware + static files
9. serve requests until Ctrl+C or SIGTERM
```
Dos consecuencias importantes:
- **Lo que falla, falla al arrancar.** Una clave mal escrita, un valor no válido, una base de datos
que no responde o una migración rota detienen la aplicación antes de servir una sola petición,
con un mensaje que explica la causa. Nunca hay una aplicación a medias en producción.
- **Lo costoso se hace una vez.** Las traducciones, los ajustes, las acciones y los recursos
estáticos se cargan o se registran al arrancar; en cada petición sólo se consultan.
## La petición
Cuando llega una petición, recorre las capas que construyó `run()`:
```text
request
|
v
+------------------------------------------------------------+
| static files (/static, /htmx...) -> served directly, |
| without middleware |
+------------------------------------------------------------+
| middleware of the extensions (session, current user...) |
| +------------------------------------------------------+ |
| | router -> your handler | |
| | Page::new(request) builds the Context: | |
| | language, theme, user, zone | |
| | .with_child(...) adds components, not HTML | |
| | .render() the theme lays out the page | |
| +------------------------------------------------------+ |
+------------------------------------------------------------+
|
v
response (complete HTML, or a fragment for HTMX)
```
- Los **archivos estáticos** se registran después del *middleware*, así que no pasan por él:
servir una hoja de estilos no resuelve sesiones ni consulta la base de datos.
- El **middleware** de cada extensión (`configure_middleware()`) envuelve las rutas de **todas**
las extensiones. Así, `pagetop-user` resuelve la sesión una vez y cualquier ruta sabe quién pide.
- El ***handler*** es un *handler* de Axum normal. `Page::new(request)` crea el **contexto** de la
petición, que viajará por todos los componentes: el idioma negociado, el tema, el usuario, la
zona horaria, los recursos y los mensajes.
Qué pasa dentro de `render()` se explica en [Componentes, temas y renderizado](rendering.md).
## Sin estado mutable compartido
Los ajustes son de sólo lectura, las acciones se registran una vez y los componentes globales
(`InRegion`) se **clonan** para cada página. Cada petición trabaja con su propio contexto y sus
propias copias: lo que un componente cambia al renderizarse no afecta a otras peticiones. El estado
que debe compartirse entre peticiones (datos, sesiones) vive en la base de datos o, si es tuyo, en
tus propias estructuras.
## El preludio
Casi todo lo que necesitas está en un solo `use`:
```rust
use pagetop::prelude::*;
```
Trae los tipos principales (`Extension`, `Page`, `Component`, `Lc`...), los componentes base, las
macros (`html!`, `include_locales!`...) y accesos directos a módulos como `web`, `trace`, `util` o
`global`. Las extensiones tienen el suyo: `pagetop_htmx::prelude::*`, `pagetop_user::prelude::*`...
## Siguiente
- [Componentes, temas y renderizado](rendering.md).
- [Si vienes de Axum](coming-from-axum.md): qué es igual y qué cambia.