✨ 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,206 @@
# Tu primera aplicación
En este tutorial pasas de no tener nada instalado a un servidor web propio con dos páginas, una
de ellas con parámetros en la URL, y un ajuste que cambias sin recompilar.
- **Tiempo:** unos 10 minutos (más lo que tarde la primera compilación).
- **Necesitas:** conocer lo básico de Rust y tener una terminal a mano.
- **Al terminar tendrás:** una aplicación PageTop que entiendes línea a línea.
## 1. Instala Rust
PageTop necesita **Rust 1.88** o posterior. Si no lo tienes, instálalo con
[rustup](https://rustup.rs) y comprueba la versión:
```sh
rustc --version
```
```text
rustc 1.90.0 (1159e78c4 2025-09-14)
```
Cualquier versión igual o superior sirve. Un editor con *rust-analyzer* (VS Code, Zed, RustRover...)
te ahorrará muchos viajes a la documentación.
## 2. Crea el proyecto
```sh
cargo new hello-pagetop
cd hello-pagetop
```
Añade PageTop a `Cargo.toml`. Esta guía describe la versión en desarrollo, que se obtiene del
repositorio oficial:
```toml
[dependencies]
pagetop = { git = "https://git.cillero.es/manuelcillero/pagetop" }
```
No necesitas añadir Tokio ni Axum: PageTop ya los trae y los expone a través de su **preludio**,
`pagetop::prelude::*`.
## 3. Arranca el servidor
Sustituye el contenido de `src/main.rs`:
```rust,no_run
use pagetop::prelude::*;
#[pagetop::main]
async fn main() -> std::io::Result<()> {
Application::new().await.run().await
}
```
Y ejecútalo:
```sh
cargo run
```
La primera compilación tarda unos minutos; las siguientes, segundos. Cuando termine, verás algo así:
```text
PageTop App
Powered by PageTop 0.5.0
INFO pagetop::core::extension::all: Loading settings for all extensions
INFO pagetop::core::extension::all: Calling application bootstrap
```
En un terminal de 80 columnas o más, el nombre aparece en letras grandes. Abre
<http://localhost:8080>: es la página de bienvenida de PageTop. Para el servidor con `Ctrl+C`.
`Application::new()` arranca una aplicación vacía, útil para comprobar que todo funciona. Para hacer
algo propio necesitas una **extensión raíz**.
## 4. Tu primera página
Todo en PageTop es una extensión, empezando por tu aplicación. Cambia `src/main.rs`:
```rust,no_run
use pagetop::prelude::*;
struct HelloPageTop;
#[async_trait]
impl Extension for HelloPageTop {
fn configure_router(&self, router: Router) -> Router {
router.route("/", web::get(home))
}
}
async fn home(request: HttpRequest) -> Result<Markup, ErrorPage> {
Page::new(request)
.with_title(Lc::n("Home"))
.with_child(Html::with(|_| html! {
h1 { "Hello, PageTop!" }
p { "This page is generated by the server." }
}))
.render()
.await
}
#[pagetop::main]
async fn main() -> std::io::Result<()> {
Application::prepare(&HelloPageTop).await.run().await
}
```
Arranca de nuevo y recarga <http://localhost:8080>. Qué está pasando:
1. `HelloPageTop` es una extensión: un *struct* vacío que implementa `Extension`. Todos sus
métodos son opcionales; aquí sólo usa uno.
2. `configure_router()` registra la ruta `/` y la asocia al *handler* `home`.
3. `home` recibe la petición, construye una `Page`, le pone título y contenido, y la **renderiza**:
el tema activo añade el `<head>`, la estructura de la página, los estilos y el pie.
4. `Application::prepare()` arranca la aplicación con `HelloPageTop` como **extensión raíz**.
El contenido se escribe con la macro `html!`: HTML con sintaxis de Rust, comprobado al compilar. Si
olvidas cerrar una llave, no compila. La verás a fondo en [Escribir HTML con
`html!`](../how-to/html.md).
## 5. Una ruta con parámetros
Las rutas pueden capturar segmentos de la URL. Añade una segunda ruta:
```rust,no_run
use pagetop::prelude::*;
struct HelloPageTop;
#[async_trait]
impl Extension for HelloPageTop {
fn configure_router(&self, router: Router) -> Router {
router
.route("/", web::get(home))
.route("/hello/{name}", web::get(hello))
}
}
# async fn home(request: HttpRequest) -> Result<Markup, ErrorPage> {
# Page::new(request).render().await
# }
async fn hello(
request: HttpRequest,
web::Path(name): web::Path<String>,
) -> Result<Markup, ErrorPage> {
Page::new(request)
.with_title(Lc::n("Greeting"))
.with_child(Html::with(move |_| html! { h1 { "Hello, " (name) "!" } }))
.render()
.await
}
#[pagetop::main]
async fn main() -> std::io::Result<()> {
Application::prepare(&HelloPageTop).await.run().await
}
```
Visita <http://localhost:8080/hello/Ana>. Ahora prueba
<http://localhost:8080/hello/%3Cscript%3E>: verás `<script>` como texto, porque `html!` **escapa**
todo lo que insertas. No tienes que acordarte de hacerlo.
Y una ruta que no existe, como <http://localhost:8080/nope>, responde con una página 404 que
mantiene el aspecto del sitio.
## 6. Cambia un ajuste sin recompilar
El título de la pestaña dice «PageTop App | Greeting». Ese nombre es un **ajuste** de la
aplicación. Crea `config/common.toml`, junto a `Cargo.toml`:
```toml
[app]
name = "Hello PageTop"
```
Para el servidor y arráncalo con `cargo run`: no se recompila nada, sólo se lee la configuración.
La pestaña dice ahora «Hello PageTop | Greeting», y el pie de página también usa el nuevo nombre.
Prueba a escribir mal la clave (`nmae = ...`): la aplicación no arranca y te dice qué clave no
reconoce, y cuáles admite:
```text
Invalid settings in section [app]: unknown field `nmae`, expected one of `name`, `theme`, ...
```
Las erratas en la configuración no pasan desapercibidas.
## Lo que has construido
- Un servidor web completo en un solo archivo, sin añadir Tokio ni Axum a mano.
- Una **extensión raíz** con dos rutas, una de ellas con parámetros.
- Páginas completas que el tema rodea de cabecera, estilos y pie.
- HTML comprobado al compilar y escapado automáticamente.
- Un ajuste en `config/common.toml` que cambia la aplicación sin recompilar.
## Siguiente
- [Recorrido por PageTop](tour.md): componentes, formularios, traducciones y pruebas en un solo
paseo.
- [Tareas del huerto con HTMX](htmx-tasks.md), si prefieres ir directo a la interactividad.
- [Arquitectura: del arranque a la respuesta](../explanation/architecture.md), para entender qué
hace `Application::prepare()` por dentro.