📝 Cambia el formato para la documentación

helpers/pagetop-build/README.md

@@ -18,6 +18,107 @@ clásica para crear soluciones web SSR (*renderizadas en el servidor*) modulares
 configurables, basadas en HTML, CSS y JavaScript.
 
 
+# ⚡️ Guía rápida
+
+Añadir en el archivo `Cargo.toml` del proyecto:
+
+```toml
+[build-dependencies]
+pagetop-build = { ... }
+```
+
+Y crear un archivo `build.rs` a la altura de `Cargo.toml` para indicar cómo se van a incluir los
+archivos estáticos o cómo se van a compilar los archivos SCSS para el proyecto. Casos de uso:
+
+## Incluir archivos estáticos desde un directorio
+
+Hay que preparar una carpeta en el proyecto con todos los archivos que se quieren incluir, por
+ejemplo `static`, y añadir el siguiente código en `build.rs` para crear el conjunto de recursos:
+
+```rust,no_run
+use pagetop_build::StaticFilesBundle;
+
+fn main() -> std::io::Result<()> {
+    StaticFilesBundle::from_dir("./static", None)
+        .with_name("guides")
+        .build()
+}
+```
+
+Si es necesario, se puede añadir un filtro para seleccionar archivos específicos de la carpeta, por
+ejemplo:
+
+```rust,no_run
+use pagetop_build::StaticFilesBundle;
+use std::path::Path;
+
+fn main() -> std::io::Result<()> {
+    fn only_pdf_files(path: &Path) -> bool {
+        // Selecciona únicamente los archivos con extensión `.pdf`.
+        path.extension().map_or(false, |ext| ext == "pdf")
+    }
+
+    StaticFilesBundle::from_dir("./static", Some(only_pdf_files))
+        .with_name("guides")
+        .build()
+}
+```
+
+## Compilar archivos SCSS a CSS
+
+Se puede compilar un archivo SCSS, que podría importar otros a su vez, para preparar un recurso con
+el archivo CSS minificado obtenido. Por ejemplo:
+
+```rust,no_run
+use pagetop_build::StaticFilesBundle;
+
+fn main() -> std::io::Result<()> {
+    StaticFilesBundle::from_scss("./styles/main.scss", "styles.min.css")
+        .with_name("main_styles")
+        .build()
+}
+```
+
+Este código compila el archivo `main.scss` de la carpeta `static` del proyecto, y prepara un recurso
+llamado `main_styles` que contiene el archivo `styles.min.css` obtenido.
+
+
+# 📦 Módulos generados
+
+Cada conjunto de recursos [`StaticFilesBundle`] genera un archivo en el directorio estándar
+[OUT_DIR](https://doc.rust-lang.org/cargo/reference/environment-variables.html#environment-variables-cargo-sets-for-build-scripts)
+donde se incluyen los recursos necesarios para compilar el proyecto. Por ejemplo, para
+`with_name("guides")` se crea un archivo llamado `guides.rs`.
+
+No hay ningún problema en generar más de un conjunto de recursos para cada proyecto.
+
+Normalmente no habrá que acceder a estos módulos; bastará con incluirlos en el proyecto con
+[`include_files!`](https://docs.rs/pagetop/latest/pagetop/macro.include_files.html), y luego con
+[`include_files_service!`](https://docs.rs/pagetop/latest/pagetop/macro.include_files_service.html)
+configurar un servicio web para servir los recursos desde la ruta indicada:
+
+```rust,ignore
+use pagetop::prelude::*;
+
+include_files!(guides);
+
+pub struct MyExtension;
+
+impl Extension for MyExtension {
+    // Servicio web que publica los recursos de `guides` en `/ruta/a/guides`.
+    fn configure_service(&self, scfg: &mut service::web::ServiceConfig) {
+        include_files_service!(scfg, guides => "/ruta/a/guides");
+    }
+}
+```
+
+También se puede asignar el conjunto de recursos a una variable global; p.ej. `GUIDES`:
+
+```rust,ignore
+include_files!(GUIDES => guides);
+```
+
+
 # 🚧 Advertencia
 
 `PageTop` es un proyecto personal para aprender [Rust](https://www.rust-lang.org/es) y conocer su