Skip to content
Merged
Show file tree
Hide file tree
Changes from all commits
Commits
File filter

Filter by extension

Filter by extension


Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
10 changes: 10 additions & 0 deletions .github/workflows/ci.yml
Original file line number Diff line number Diff line change
Expand Up @@ -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
25 changes: 25 additions & 0 deletions examples/README.md
Original file line number Diff line number Diff line change
@@ -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
```
1 change: 1 addition & 0 deletions examples/atlas/.gitignore
Original file line number Diff line number Diff line change
@@ -0,0 +1 @@
dist/
21 changes: 21 additions & 0 deletions examples/atlas/content/contacto.html
Original file line number Diff line number Diff line change
@@ -0,0 +1,21 @@
+++
title = "Contacto"
template = "page.html"
+++

<p>
Puedes escribir a <a href="mailto:hola@atlas.example.com">hola@atlas.example.com</a>.
Este archivo es HTML con Jinja, no Markdown: se renderiza con el mismo contexto que
cualquier plantilla.
</p>

<h2>Guías publicadas</h2>

<ul class="guide-list">
{% for item in pages if item.template == "guide.html" %}
<li>
<a href="{{ item.url }}">{{ item.title }}</a>
{% if item.meta.get("summary") %}<span>{{ item.meta.get("summary") }}</span>{% endif %}
</li>
{% endfor %}
</ul>
43 changes: 43 additions & 0 deletions examples/atlas/content/guias/avanzado/despliegue.md
Original file line number Diff line number Diff line change
@@ -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.
40 changes: 40 additions & 0 deletions examples/atlas/content/guias/avanzado/plantillas-jinja.md
Original file line number Diff line number Diff line change
@@ -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" %}
<a href="{{ item.url }}">{{ item.title }}</a>
{% 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 %}
<span class="reading-time">{{ minutes }} min de lectura</span>
```

## 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.
51 changes: 51 additions & 0 deletions examples/atlas/content/guias/escribir-markdown.md
Original file line number Diff line number Diff line change
@@ -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.
10 changes: 10 additions & 0 deletions examples/atlas/content/guias/index.md
Original file line number Diff line number Diff line change
@@ -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*.
41 changes: 41 additions & 0 deletions examples/atlas/content/guias/personalizar-temas.md
Original file line number Diff line number Diff line change
@@ -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/<nombre>/` 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.
18 changes: 18 additions & 0 deletions examples/atlas/content/index.md
Original file line number Diff line number Diff line change
@@ -0,0 +1,18 @@
+++
title = "Atlas"
+++

<p class="kicker">Cuaderno de campo · Python y Jinja</p>

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.

<div class="note">
<strong>Nota de campo.</strong> El tema vive en <code>themes/atlas</code>, pero el
proyecto lo pisa con <code>templates/colophon.html</code> y <code>static/atlas.css</code>.
Si el colofón del pie menciona las montañas, ganó el proyecto.
</div>
24 changes: 24 additions & 0 deletions examples/atlas/content/posts/bienvenida.md
Original file line number Diff line number Diff line change
@@ -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.
20 changes: 20 additions & 0 deletions examples/atlas/content/posts/borrador.md
Original file line number Diff line number Diff line change
@@ -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.
28 changes: 28 additions & 0 deletions examples/atlas/content/posts/diseno-sin-ruido.md
Original file line number Diff line number Diff line change
@@ -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.
27 changes: 27 additions & 0 deletions examples/atlas/content/posts/tres-dependencias.md
Original file line number Diff line number Diff line change
@@ -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.
Loading