diff --git a/.github/workflows/ci.yml b/.github/workflows/ci.yml
index 8c9cd10..32d873f 100644
--- a/.github/workflows/ci.yml
+++ b/.github/workflows/ci.yml
@@ -89,3 +89,13 @@ jobs:
python-version: "3.13"
- run: pip install -e ".[dev]"
- run: zensical build --strict
+
+ examples:
+ runs-on: ubuntu-24.04
+ steps:
+ - uses: actions/checkout@v7
+ - uses: actions/setup-python@v7
+ with:
+ python-version: "3.13"
+ - run: pip install -e .
+ - run: for site in examples/*/; do (cd "$site" && jamstack build --clean); done
diff --git a/examples/README.md b/examples/README.md
new file mode 100644
index 0000000..2d03ff7
--- /dev/null
+++ b/examples/README.md
@@ -0,0 +1,25 @@
+# Examples
+
+Complete sites built with jamstack. Each directory is a standalone project with
+its own `site.toml`, and CI builds every one of them on each change.
+
+| Example | What it shows |
+|---|---|
+| [`minimal`](minimal/) | The smallest site: one page and the bundled `minimal` theme. |
+| [`blog`](blog/) | Posts with dates and summaries using the bundled `blog` theme. |
+| [`atlas`](atlas/) | A local theme with its own navigation, guides, nested routes, overrides and a draft. |
+| [`handbook`](handbook/) | A documentation site: configurable sidebar, previous/next links and footer links from `[extra]`. |
+
+## Running one
+
+```bash
+cd examples/handbook
+jamstack build --clean
+jamstack serve
+```
+
+To build all of them from the repository root:
+
+```bash
+for site in examples/*/; do (cd "$site" && jamstack build --clean); done
+```
diff --git a/examples/atlas/.gitignore b/examples/atlas/.gitignore
new file mode 100644
index 0000000..849ddff
--- /dev/null
+++ b/examples/atlas/.gitignore
@@ -0,0 +1 @@
+dist/
diff --git a/examples/atlas/content/contacto.html b/examples/atlas/content/contacto.html
new file mode 100644
index 0000000..5f66288
--- /dev/null
+++ b/examples/atlas/content/contacto.html
@@ -0,0 +1,21 @@
++++
+title = "Contacto"
+template = "page.html"
++++
+
+
+ Puedes escribir a hola@atlas.example.com.
+ Este archivo es HTML con Jinja, no Markdown: se renderiza con el mismo contexto que
+ cualquier plantilla.
+
+
+
Guías publicadas
+
+
+{% for item in pages if item.template == "guide.html" %}
+
diff --git a/examples/atlas/content/guias/avanzado/despliegue.md b/examples/atlas/content/guias/avanzado/despliegue.md
new file mode 100644
index 0000000..2f9b8b4
--- /dev/null
+++ b/examples/atlas/content/guias/avanzado/despliegue.md
@@ -0,0 +1,43 @@
++++
+title = "Despliegue"
+template = "guide.html"
+summary = "De dist/ a producción: URL base, sitemap, feed y caché."
++++
+
+`jamstack build` deja todo en `dist/`. Ese directorio es el sitio completo: se puede
+subir a cualquier hosting estático sin instalar Python en el servidor.
+
+## Antes de publicar
+
+Configura `base_url` en `site.toml`:
+
+```toml
+[site]
+title = "Atlas"
+base_url = "https://atlas.example.com"
+```
+
+Sin `base_url` el motor no genera `sitemap.xml` ni `feed.xml`, porque no puede construir
+URLs absolutas. Es una decisión deliberada: mejor no publicar un sitemap roto.
+
+## GitHub Pages
+
+```yaml
+- uses: actions/checkout@v7
+- uses: actions/setup-python@v7
+- run: pip install jamstack
+- run: jamstack build
+- uses: actions/upload-pages-artifact@v3
+ with:
+ path: dist
+```
+
+Añade un `.nojekyll` vacío en `dist/` si tu hosting ignora carpetas que empiezan por
+guion bajo. Las URLs limpias (`/sobre/` en vez de `/sobre.html`) funcionan porque cada
+página se escribe como `index.html` dentro de su carpeta.
+
+## Caché
+
+Los assets no llevan hash. Para un sitio pequeño, un `Cache-Control: max-age=3600`
+sobre `dist/` es suficiente; si cambias el CSS, sube el número de versión en el nombre
+o invalida la caché del hosting.
diff --git a/examples/atlas/content/guias/avanzado/plantillas-jinja.md b/examples/atlas/content/guias/avanzado/plantillas-jinja.md
new file mode 100644
index 0000000..b8096cf
--- /dev/null
+++ b/examples/atlas/content/guias/avanzado/plantillas-jinja.md
@@ -0,0 +1,40 @@
++++
+title = "Plantillas con Jinja"
+template = "guide.html"
+summary = "El contexto site/page/pages y un cálculo real de tiempo de lectura."
++++
+
+Toda plantilla recibe tres objetos:
+
+- `site`: la configuración de `site.toml` (título, autor, idioma, URL base).
+- `page`: la página actual (título, URL, fecha, contenido y metadatos).
+- `pages`: todas las páginas publicadas, ordenadas por fecha descendente.
+
+## Filtrar sin lógica en el contenido
+
+El índice usa `pages` para separar posts de guías:
+
+```jinja
+{% set posts = pages | selectattr("date") | list %}
+{% for item in pages if item.template == "guide.html" %}
+ {{ item.title }}
+{% endfor %}
+```
+
+## Un cálculo real
+
+El tiempo de lectura se calcula en la plantilla. No hay campo extra en el contenido:
+
+```jinja
+{% set words = page.content | striptags | wordcount %}
+{% set minutes = [(words / 200) | round(0, "ceil") | int, 1] | max %}
+{{ minutes }} min de lectura
+```
+
+## Reglas del motor
+
+Jinja corre en modo estricto: una variable inexistente es un error, no una cadena vacía.
+Eso convierte los typos en fallos de build en lugar de huecos silenciosos.
+
+Los archivos `.html` de `content/` también usan Jinja y el mismo contexto. `contacto.html`
+recorre las guías publicadas para construir su lista.
diff --git a/examples/atlas/content/guias/escribir-markdown.md b/examples/atlas/content/guias/escribir-markdown.md
new file mode 100644
index 0000000..16347ed
--- /dev/null
+++ b/examples/atlas/content/guias/escribir-markdown.md
@@ -0,0 +1,51 @@
++++
+title = "Escribir Markdown"
+template = "guide.html"
+summary = "Front matter, rutas limpias y qué se puede escribir en cada archivo."
++++
+
+Cada página es un archivo dentro de `content/`. La extensión decide cómo se procesa:
+
+- **`.md`** pasa por MarkdownIt y el resultado se inyecta en la plantilla.
+- **`.html`** se renderiza con Jinja, así que puede usar bucles y condicionales.
+
+## Front matter
+
+El bloque entre `+++` es TOML. Solo `title` es obligatorio; el resto tiene valores por
+defecto razonables.
+
+```toml
++++
+title = "Escribir Markdown"
+template = "guide.html"
+summary = "Una línea para los índices."
+date = 2026-11-07
+draft = false
++++
+```
+
+## Rutas
+
+La ruta del archivo se convierte en la URL:
+
+- `index.md` → `/`
+- `sobre.md` → `/sobre/`
+- `guias/index.md` → `/guias/`
+- `guias/avanzado/despliegue.md` → `/guias/avanzado/despliegue/`
+
+Las tablas usan la sintaxis estándar de CommonMark:
+
+| Clave | Tipo | Uso |
+| --- | --- | --- |
+| `title` | string | Título de la página |
+| `date` | fecha ISO | Orden y feed |
+| `draft` | boolean | Excluir del build |
+
+Si necesitas algo que la tabla no cubra, escribe HTML directamente.
+
+## Lo que sí funciona
+
+Párrafos, **negrita**, *cursiva*, `código`, listas, enlaces, citas, bloques de código y
+HTML crudo. Los encabezados generan anclas automáticas.
+
+> El contenido se escribe una vez; el HTML se genera todas las veces que haga falta.
diff --git a/examples/atlas/content/guias/index.md b/examples/atlas/content/guias/index.md
new file mode 100644
index 0000000..93b8b99
--- /dev/null
+++ b/examples/atlas/content/guias/index.md
@@ -0,0 +1,10 @@
++++
+title = "Guías"
+template = "guide-index.html"
++++
+
+Cuatro guías para entender cómo se arma un sitio con jamstack: el formato del contenido,
+la estructura de un tema, el contexto de las plantillas y el camino hasta producción.
+
+Están ordenadas por profundidad, no por fecha. Si es tu primera vez, empieza por
+*Escribir Markdown*.
diff --git a/examples/atlas/content/guias/personalizar-temas.md b/examples/atlas/content/guias/personalizar-temas.md
new file mode 100644
index 0000000..59fa8ce
--- /dev/null
+++ b/examples/atlas/content/guias/personalizar-temas.md
@@ -0,0 +1,41 @@
++++
+title = "Personalizar temas"
+template = "guide.html"
+summary = "Qué hay dentro de un tema y cómo pisarlo sin copiar todo el proyecto."
++++
+
+Un tema es una carpeta con tres cosas:
+
+```text
+themes/atlas/
+ theme.toml # nombre y descripción
+ templates/ # plantillas Jinja
+ static/ # CSS, imágenes, fuentes
+ scaffold/ # contenido inicial opcional
+```
+
+## Dónde se busca
+
+1. `themes//` dentro del proyecto.
+2. El tema empaquetado con el motor.
+
+El proyecto siempre gana. Si creas `templates/colophon.html`, esa plantilla reemplaza a
+la del tema sin tocar el resto.
+
+## Estáticos
+
+La copia va en dos pasadas: primero el tema, después el proyecto. Un
+`static/atlas.css` en el proyecto sobrescribe el del tema.
+
+Este sitio lo demuestra: el tema trae un logo verde, pero el proyecto publica uno ocre
+con montañas. El CSS del proyecto cambia el acento y el colofón del pie.
+
+## Copiar un tema empaquetado
+
+Sirve para empezar con una base que ya funciona:
+
+```bash
+cp -r "$(python -c 'import jamstack, pathlib; print(pathlib.Path(jamstack.__file__).parent / "themes" / "blog")')" themes/atlas
+```
+
+Luego cambia el nombre en `theme.toml` y apunta `[theme] name` a la nueva carpeta.
diff --git a/examples/atlas/content/index.md b/examples/atlas/content/index.md
new file mode 100644
index 0000000..00caea8
--- /dev/null
+++ b/examples/atlas/content/index.md
@@ -0,0 +1,18 @@
++++
+title = "Atlas"
++++
+
+
Cuaderno de campo · Python y Jinja
+
+Atlas es un sitio de demostración construido con jamstack 2.0. No usa base de datos, ni
+JavaScript en el cliente, ni un servidor en producción: solo Markdown, plantillas Jinja
+y un `jamstack build`.
+
+Existe para probar el motor al límite: rutas anidadas, un tema local, plantillas
+sobreescritas por el proyecto y un borrador que no debe publicarse.
+
+
+ Nota de campo. El tema vive en themes/atlas, pero el
+ proyecto lo pisa con templates/colophon.html y static/atlas.css.
+ Si el colofón del pie menciona las montañas, ganó el proyecto.
+
diff --git a/examples/atlas/content/posts/bienvenida.md b/examples/atlas/content/posts/bienvenida.md
new file mode 100644
index 0000000..464ad5b
--- /dev/null
+++ b/examples/atlas/content/posts/bienvenida.md
@@ -0,0 +1,24 @@
++++
+title = "Bienvenida a Atlas"
+template = "post.html"
+date = 2026-11-07
+summary = "Por qué existe este sitio y qué va a demostrar."
++++
+
+Este es el primer post de Atlas, un sitio que no tiene otro propósito que poner a prueba
+el motor de jamstack 2.0.
+
+## El experimento
+
+La pregunta era simple: ¿cuánto se puede construir con Markdown, Jinja y tres
+dependencias? La respuesta, después de un fin de semana, es bastante.
+
+Hay rutas anidadas, un tema local, plantillas sobreescritas y un feed que solo incluye
+lo que tiene fecha. También hay un borrador que no aparece en ningún índice, ni en el
+sitemap, ni en el feed.
+
+## Lo que viene
+
+En los próximos posts voy a escribir sobre el diseño sin ruido y sobre la decisión de
+mantener tres dependencias. No hay calendario ni suscripción: cuando algo merezca la
+pena, se publica.
diff --git a/examples/atlas/content/posts/borrador.md b/examples/atlas/content/posts/borrador.md
new file mode 100644
index 0000000..e61b58b
--- /dev/null
+++ b/examples/atlas/content/posts/borrador.md
@@ -0,0 +1,20 @@
++++
+title = "Notas sin publicar"
+template = "post.html"
+date = 2026-11-01
+draft = true
+summary = "Este post no debe aparecer en el build normal."
++++
+
+Si estás leyendo esto en el sitio publicado, algo salió mal.
+
+Este archivo existe para comprobar tres cosas:
+
+- Que `jamstack build` lo excluye.
+- Que `jamstack build --drafts` lo incluye.
+- Que el sitemap y el feed respetan la misma decisión.
+
+## Borradores
+
+Un borrador es una página con `draft = true` en el front matter. No se renderiza, no
+entra en los índices y no se publica. Es la forma de escribir sin que el mundo lo vea.
diff --git a/examples/atlas/content/posts/diseno-sin-ruido.md b/examples/atlas/content/posts/diseno-sin-ruido.md
new file mode 100644
index 0000000..9055f83
--- /dev/null
+++ b/examples/atlas/content/posts/diseno-sin-ruido.md
@@ -0,0 +1,28 @@
++++
+title = "Diseñar sin ruido"
+template = "post.html"
+date = 2026-10-21
+summary = "Menos decisiones visuales, más decisiones de contenido."
++++
+
+La mayoría de los sitios no fallan por falta de ideas visuales. Fallan porque cada
+elemento compite por la misma atención.
+
+## Tres reglas
+
+1. **Una columna.** El texto se lee de arriba abajo; no necesita una barra lateral que
+ repita lo que ya está en la página.
+2. **Dos colores.** Uno para el texto, otro para el acento. Todo lo demás es escala de
+ grises.
+3. **Un movimiento.** Si nada se mueve, el sitio se siente quieto, no roto.
+
+## Lo que se quita
+
+Quitar es más difícil que añadir porque hay que decidir qué no importa. Un enlace que no
+lleva a ninguna parte, una animación que distrae, una fuente que tarda 300 ms en
+descargarse: todo eso es ruido.
+
+> El diseño no es lo que se ve. Es lo que se entiende.
+
+Atlas aplica la misma idea al código: una plantilla base, tres parciales y un CSS de
+doscientos bloques. Nada más.
diff --git a/examples/atlas/content/posts/tres-dependencias.md b/examples/atlas/content/posts/tres-dependencias.md
new file mode 100644
index 0000000..8d51e9b
--- /dev/null
+++ b/examples/atlas/content/posts/tres-dependencias.md
@@ -0,0 +1,27 @@
++++
+title = "Tres dependencias"
+template = "post.html"
+date = 2026-09-30
+summary = "Click, Jinja y MarkdownIt: el presupuesto completo del motor."
++++
+
+Un generador de sitios estáticos tiene un trabajo acotado: leer archivos, renderizar
+plantillas y escribir HTML. No necesita un framework web, ni un ORM, ni un bundler.
+
+## El presupuesto
+
+- **Click** para la línea de comandos.
+- **Jinja** para las plantillas.
+- **MarkdownIt** para el contenido.
+
+Eso es todo. El resto es biblioteca estándar: `tomllib`, `http.server`, `pathlib`,
+`shutil`, `xml.etree`.
+
+## Lo que se evitó
+
+`livereload` parecía cómodo hasta que dejó de importar en Python 3.12. Un watcher de
+`mtime` con `threading` hace lo mismo que necesitamos y no arrastra un árbol de
+dependencias.
+
+No hay plugins, ni temas descargables, ni un marketplace. Cada cosa que no existe es una
+cosa que no se puede romper en una actualización.
diff --git a/examples/atlas/content/sobre.md b/examples/atlas/content/sobre.md
new file mode 100644
index 0000000..409bff4
--- /dev/null
+++ b/examples/atlas/content/sobre.md
@@ -0,0 +1,27 @@
++++
+title = "Sobre este sitio"
+template = "page.html"
++++
+
+Atlas nació como un ejercicio: ¿cuánto se puede construir con tres dependencias?
+
+## Lo que hay debajo
+
+- **Motor:** jamstack 2.0, con Jinja para las plantillas y Markdown para el contenido.
+- **Contenido:** doce archivos entre Markdown y HTML, incluyendo un borrador.
+- **Tema:** `atlas`, una copia del tema `blog` que vive dentro del proyecto.
+- **Salida:** HTML plano en `dist/`, sin runtime ni base de datos.
+
+## Lo que no hay
+
+Ni JavaScript de cliente, ni analítica, ni fuentes remotas. La página que estás leyendo
+pesa menos que una foto de un gato.
+
+> Un sitio estático no es un sitio sin movimiento: es un sitio que ya terminó de
+> calcularse antes de que llegue el visitante.
+
+## Cómo se genera
+
+Cada archivo de `content/` se convierte en una página. `index.md` se vuelve la raíz;
+`guias/index.md` se vuelve `/guias/`; y `guias/avanzado/despliegue.md` se vuelve
+`/guias/avanzado/despliegue/`. Las plantillas deciden cómo se ve todo lo demás.
diff --git a/examples/atlas/site.toml b/examples/atlas/site.toml
new file mode 100644
index 0000000..3398788
--- /dev/null
+++ b/examples/atlas/site.toml
@@ -0,0 +1,12 @@
+[site]
+title = "Atlas"
+description = "Un cuaderno de campo sobre construir sitios con Python."
+author = "Pedro Torcatt"
+base_url = "https://atlas.example.com"
+language = "es"
+
+[build]
+output = "dist"
+
+[theme]
+name = "atlas"
diff --git a/examples/atlas/static/atlas.css b/examples/atlas/static/atlas.css
new file mode 100644
index 0000000..8f28813
--- /dev/null
+++ b/examples/atlas/static/atlas.css
@@ -0,0 +1,23 @@
+/* Project override: this file replaces the theme's atlas.css. */
+
+:root {
+ --accent: #a0522d;
+ --rule: #e6dccd;
+ --background: #fdfbf7;
+}
+
+@media (prefers-color-scheme: dark) {
+ :root {
+ --accent: #e0a370;
+ --rule: #3a3129;
+ --background: #17130f;
+ }
+}
+
+.guide-grid li {
+ background: color-mix(in srgb, var(--accent) 4%, transparent);
+}
+
+.hero p.kicker {
+ color: var(--accent);
+}
diff --git a/examples/atlas/static/favicon.svg b/examples/atlas/static/favicon.svg
new file mode 100644
index 0000000..7bcac9e
--- /dev/null
+++ b/examples/atlas/static/favicon.svg
@@ -0,0 +1,4 @@
+
diff --git a/examples/atlas/static/logo.svg b/examples/atlas/static/logo.svg
new file mode 100644
index 0000000..ac20791
--- /dev/null
+++ b/examples/atlas/static/logo.svg
@@ -0,0 +1,5 @@
+
diff --git a/examples/atlas/static/robots.txt b/examples/atlas/static/robots.txt
new file mode 100644
index 0000000..e61b5be
--- /dev/null
+++ b/examples/atlas/static/robots.txt
@@ -0,0 +1,4 @@
+User-agent: *
+Allow: /
+
+Sitemap: https://atlas.example.com/sitemap.xml
diff --git a/examples/atlas/templates/colophon.html b/examples/atlas/templates/colophon.html
new file mode 100644
index 0000000..8bc840b
--- /dev/null
+++ b/examples/atlas/templates/colophon.html
@@ -0,0 +1,4 @@
+{{ site.title }} · Cuaderno de campo escrito a mano y compilado con
+jamstack.
+
+
Colofón del proyecto: montañas ocres y ninguna dependencia de más.
+
+{% endblock %}
diff --git a/examples/handbook/themes/handbook/templates/_pager.html b/examples/handbook/themes/handbook/templates/_pager.html
new file mode 100644
index 0000000..97de340
--- /dev/null
+++ b/examples/handbook/themes/handbook/templates/_pager.html
@@ -0,0 +1,39 @@
+{% set configured = site.extra.get("sidebar", {}).get("sections", []) %}
+{% set found = namespace(names=[]) %}
+{% for item in pages %}
+ {% set name = item.meta.get("section") %}
+ {% if name and name not in found.names %}
+ {% set found.names = found.names + [name] %}
+ {% endif %}
+{% endfor %}
+{% set ordered = namespace(names=[]) %}
+{% for name in configured %}
+ {% if name in found.names %}{% set ordered.names = ordered.names + [name] %}{% endif %}
+{% endfor %}
+{% for name in found.names | sort %}
+ {% if name not in ordered.names %}{% set ordered.names = ordered.names + [name] %}{% endif %}
+{% endfor %}
+{% set flat = namespace(items=[]) %}
+{% for name in ordered.names %}
+ {% set items = namespace(list=[]) %}
+ {% for item in pages %}
+ {% if item.meta.get("section") == name %}{% set items.list = items.list + [item] %}{% endif %}
+ {% endfor %}
+ {% for item in items.list | sort(attribute="meta.order") %}
+ {% set flat.items = flat.items + [item] %}
+ {% endfor %}
+{% endfor %}
+{% set current = namespace(index=-1) %}
+{% for item in flat.items %}
+ {% if page is defined and item.url == page.url %}{% set current.index = loop.index0 %}{% endif %}
+{% endfor %}
+{% if current.index >= 0 %}
+
+{% endif %}
diff --git a/examples/handbook/themes/handbook/templates/_sidebar.html b/examples/handbook/themes/handbook/templates/_sidebar.html
new file mode 100644
index 0000000..6d72469
--- /dev/null
+++ b/examples/handbook/themes/handbook/templates/_sidebar.html
@@ -0,0 +1,33 @@
+{% set configured = site.extra.get("sidebar", {}).get("sections", []) %}
+{% set found = namespace(names=[]) %}
+{% for item in pages %}
+ {% set name = item.meta.get("section") %}
+ {% if name and name not in found.names %}
+ {% set found.names = found.names + [name] %}
+ {% endif %}
+{% endfor %}
+{% set ordered = namespace(names=[]) %}
+{% for name in configured %}
+ {% if name in found.names %}{% set ordered.names = ordered.names + [name] %}{% endif %}
+{% endfor %}
+{% for name in found.names | sort %}
+ {% if name not in ordered.names %}{% set ordered.names = ordered.names + [name] %}{% endif %}
+{% endfor %}
+
diff --git a/examples/handbook/themes/handbook/templates/base.html b/examples/handbook/themes/handbook/templates/base.html
new file mode 100644
index 0000000..9011a6e
--- /dev/null
+++ b/examples/handbook/themes/handbook/templates/base.html
@@ -0,0 +1,31 @@
+
+
+
+
+
+ {% block title %}{{ site.title }}{% endblock %}
+
+
+
+
+
+ {{ site.title }}
+
+
+
+ {% include "_sidebar.html" %}
+
+ {% block content %}{% endblock %}
+ {% include "_pager.html" %}
+
+