✨ 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,193 @@
# Crear un tema
**Objetivo:** elegir el aspecto de la aplicación y, si hace falta, crear un tema propio que herede
de otro y cambie sólo lo necesario.
El tema es la **piel** de la aplicación: maqueta la página por regiones, aporta estilos y
*scripts*, y decide cómo se ve cada componente. Cambiar de tema no obliga a tocar las páginas.
## 1. Elige un tema
PageTop trae el tema `Basic`. Hay otros como extensiones:
| Tema | *Crate* | Estilo |
|---|---|---|
| Basic | `pagetop` | Sobrio, sin dependencias |
| Bootsier | `pagetop-bootsier` | [Bootstrap 5](https://getbootstrap.com) |
| Aliner | `pagetop-aliner` | Muestra la estructura de la página, para pruebas |
Para usar uno, declara su extensión como dependencia y selecciónalo en la configuración:
```rust,no_run
# use pagetop::prelude::*;
pub struct MyApp;
#[async_trait]
impl Extension for MyApp {
fn dependencies(&self) -> Vec<ExtensionRef> {
vec![&pagetop_bootsier::Bootsier]
}
}
```
```toml
[app]
theme = "Bootsier"
```
Si el tema configurado no está disponible, PageTop usa `Basic` y avisa al arrancar.
## 2. Crea un tema
Un tema es una extensión que además implementa `Theme`. Todos los métodos de `Theme` tienen
implementación por defecto, así que el mínimo es éste:
```rust,no_run
use pagetop::prelude::*;
pub struct Earth;
#[async_trait]
impl Extension for Earth {
fn theme(&self) -> Option<ThemeRef> {
Some(&Self)
}
}
#[async_trait]
impl Theme for Earth {}
```
## 3. Hereda de otro tema
Lo más práctico es partir de un tema existente y cambiar sólo lo necesario. Un **tema hijo**
hereda todo de su padre:
```rust,no_run
use pagetop::prelude::*;
pub struct Earth;
#[async_trait]
impl Extension for Earth {
fn dependencies(&self) -> Vec<ExtensionRef> {
vec![&pagetop_bootsier::Bootsier]
}
fn theme(&self) -> Option<ThemeRef> {
Some(&Self)
}
}
#[async_trait]
impl Theme for Earth {
fn parent(&self) -> Option<ThemeRef> {
Some(&pagetop_bootsier::Bootsier)
}
// Adds its own style sheet to every page.
fn before_render_page_body(&self, page: &mut Page) {
if let Some(parent) = self.parent() {
parent.before_render_page_body(page);
}
page.alter_assets(StyleSheet::from("/static/css/earth.css").with_weight(10));
}
}
```
`before_render_page_body()` es donde un tema añade sus recursos. Al sobrescribirlo, llama al del
padre para no perder los suyos.
No olvides seleccionarlo en la configuración (`theme = "Earth"`) y declararlo como dependencia
de la aplicación.
## 4. Ajusta componentes
`setup_component()` permite retocar cualquier componente antes de pintarlo. La macro
`setup_component!` lo distingue por tipo:
```rust,no_run
# use pagetop::prelude::*;
# pub struct Earth;
# #[async_trait]
# impl Extension for Earth {}
#[async_trait]
impl Theme for Earth {
fn setup_component(&self, component: &mut dyn Component, _cx: &mut Context) {
setup_component!(component, {
Button => |button| { button.alter_prop(PropsOp::add_classes("earth-button")); },
Block => |block| { block.alter_prop(PropsOp::add_classes("earth-block")); },
});
}
}
```
## 5. Reescribe componentes
Para cambiar el HTML entero de un componente, usa `render_component()` con la macro
`render_component!`. Lo que no captures se pinta como siempre:
```rust,no_run
# use pagetop::prelude::*;
# pub struct Earth;
# #[async_trait]
# impl Extension for Earth {}
#[async_trait]
impl Theme for Earth {
async fn render_component(
&self,
component: &dyn Component,
cx: &mut Context,
) -> Option<Result<Markup, ComponentError>> {
render_component!(component, {
Badge => |badge| Ok(html! {
span class="earth-label" { (badge.label().using(cx)) }
}),
})
}
}
```
Como el componente expone sus datos con *getters* (`badge.label()`), el tema no depende de sus
detalles internos.
## 6. Cambia las páginas de error
Las páginas 403, 404 y de error grave se pintan con la plantilla activa, para no perder la
navegación. Un tema puede cambiar su contenido:
```rust,no_run
# use pagetop::prelude::*;
# pub struct Earth;
# #[async_trait]
# impl Extension for Earth {}
#[async_trait]
impl Theme for Earth {
fn error_404(&self, page: &mut Page) {
page.alter_title(Lc::n("Not found")).alter_child_in(
&CoreRegions::Content,
ChildOp::Prepend(
Html::with(|_| {
html! {
h1 { "This page has gone off to plant tomatoes" }
p { a href="/" { "Back to home" } }
}
})
.into(),
),
);
}
}
```
## Más allá
Un tema también puede definir **regiones** y **plantillas** propias, fijar los anchos de los
puntos de corte (`breakpoint_entry()`) o traducir las intenciones a su paleta de colores
(`intent_color()`). La documentación del módulo `core::theme` en
[docs.rs](https://docs.rs/pagetop) recorre los seis pasos para personalizar un tema por completo.
## Siguiente
- [Intervenir con acciones](actions.md): retocar componentes desde una extensión que no es un tema.
- [Componentes, temas y renderizado](../explanation/rendering.md).