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

+ + 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.

diff --git a/examples/atlas/themes/atlas/static/atlas.css b/examples/atlas/themes/atlas/static/atlas.css new file mode 100644 index 0000000..2e26d69 --- /dev/null +++ b/examples/atlas/themes/atlas/static/atlas.css @@ -0,0 +1 @@ +/* Project-level styles. Override this file from the site's static/ directory. */ diff --git a/examples/atlas/themes/atlas/static/favicon.svg b/examples/atlas/themes/atlas/static/favicon.svg new file mode 100644 index 0000000..0dd1c2e --- /dev/null +++ b/examples/atlas/themes/atlas/static/favicon.svg @@ -0,0 +1,5 @@ + + + + + diff --git a/examples/atlas/themes/atlas/static/logo.svg b/examples/atlas/themes/atlas/static/logo.svg new file mode 100644 index 0000000..0dd1c2e --- /dev/null +++ b/examples/atlas/themes/atlas/static/logo.svg @@ -0,0 +1,5 @@ + + + + + diff --git a/examples/atlas/themes/atlas/static/skin.css b/examples/atlas/themes/atlas/static/skin.css new file mode 100644 index 0000000..e336339 --- /dev/null +++ b/examples/atlas/themes/atlas/static/skin.css @@ -0,0 +1,130 @@ +.brand { + display: inline-flex; + align-items: center; + gap: 0.6rem; + text-decoration: none; +} + +.mark { + display: block; +} + +.nav { + display: flex; + flex-wrap: wrap; + justify-content: center; + gap: 1.25rem; + margin-top: 1.5rem; + font-family: ui-sans-serif, system-ui, sans-serif; + font-size: 0.78rem; + letter-spacing: 0.14em; + text-transform: uppercase; +} + +.nav a { + color: var(--muted); + text-decoration: none; +} + +.nav a:hover { + color: var(--accent); +} + +.hero { + margin-bottom: 2.5rem; +} + +.hero p.kicker { + margin: 0 0 0.75rem; + color: var(--muted); + font-family: ui-sans-serif, system-ui, sans-serif; + font-size: 0.75rem; + letter-spacing: 0.14em; + text-transform: uppercase; +} + +.section-title { + margin: 2.75rem 0 1rem; + padding-bottom: 0.4rem; + border-bottom: 1px solid var(--rule); + color: var(--muted); + font-family: ui-sans-serif, system-ui, sans-serif; + font-size: 0.78rem; + letter-spacing: 0.14em; + text-transform: uppercase; +} + +.meta { + display: flex; + gap: 0.75rem; + align-items: baseline; + margin: 0.6rem 0 0; +} + +.reading-time { + color: var(--muted); + font-size: 0.8rem; + letter-spacing: 0.06em; + text-transform: uppercase; +} + +.guide-list { + margin: 0; + padding: 0; + list-style: none; +} + +.guide-list li { + padding: 0.35rem 0; +} + +.guide-list a { + text-decoration: none; +} + +.guide-list a:hover { + text-decoration: underline; +} + +.guide-grid { + display: grid; + grid-template-columns: 1fr 1fr; + gap: 1rem; + margin: 2.5rem 0 0; + padding: 0; + list-style: none; +} + +.guide-grid li { + padding: 1rem; + border: 1px solid var(--rule); + border-radius: 6px; +} + +.guide-grid a { + font-weight: 600; + text-decoration: none; +} + +.guide-grid p { + margin: 0.35rem 0 0; + color: var(--muted); + font-size: 0.9rem; +} + +.note { + margin: 1.5rem 0; + padding: 1rem 1.25rem; + border-left: 3px solid var(--accent); + background: color-mix(in srgb, var(--accent) 6%, transparent); +} + +.colophon-note { + margin-top: 0.35rem; +} + +@media (max-width: 40rem) { + .guide-grid { + grid-template-columns: 1fr; + } +} diff --git a/examples/atlas/themes/atlas/static/style.css b/examples/atlas/themes/atlas/static/style.css new file mode 100644 index 0000000..0ecd995 --- /dev/null +++ b/examples/atlas/themes/atlas/static/style.css @@ -0,0 +1,186 @@ +:root { + color-scheme: light dark; + --text: #1f1c19; + --muted: #756e66; + --background: #fbf9f6; + --accent: #0f5e59; + --rule: #e3ddd4; +} + +@media (prefers-color-scheme: dark) { + :root { + --text: #ece7e0; + --muted: #a49c92; + --background: #16130f; + --accent: #7cc4bd; + --rule: #322c25; + } +} + +* { + box-sizing: border-box; +} + +body { + margin: 0; + background: var(--background); + color: var(--text); + font: 1.125rem/1.75 "Iowan Old Style", "Palatino Linotype", Palatino, Georgia, serif; + text-rendering: optimizeLegibility; +} + +.masthead, +.content, +.colophon { + max-width: 40rem; + margin: 0 auto; + padding: 0 1.25rem; +} + +.masthead { + padding-top: 4rem; + padding-bottom: 2.5rem; + text-align: center; +} + +.logo { + color: var(--text); + font-size: 1.75rem; + font-weight: 600; + letter-spacing: -0.02em; + text-decoration: none; +} + +.tagline { + margin: 0.5rem 0 0; + color: var(--muted); + font-size: 0.95rem; + font-style: italic; +} + +.content { + padding-bottom: 4rem; +} + +a { + color: var(--accent); +} + +h1, +h2, +h3 { + line-height: 1.2; + letter-spacing: -0.02em; +} + +h1 { + margin: 0 0 0.5rem; + font-size: 2.25rem; +} + +time { + color: var(--muted); + font-size: 0.8rem; + letter-spacing: 0.06em; + text-transform: uppercase; +} + +.post-list { + margin: 0; + padding: 0; + list-style: none; +} + +.post-list li { + padding: 1.75rem 0; + border-top: 1px solid var(--rule); +} + +.post-list li:first-child { + border-top: none; +} + +.post-title { + display: block; + color: var(--text); + font-size: 1.4rem; + font-weight: 600; + text-decoration: none; +} + +.post-title:hover { + color: var(--accent); +} + +.summary { + margin: 0.4rem 0 0; + color: var(--muted); + font-size: 0.95rem; +} + +.post-header { + padding-bottom: 1.5rem; + border-bottom: 1px solid var(--rule); +} + +.prose { + padding-top: 1.5rem; +} + +.prose p { + margin: 0 0 1.25em; +} + +.prose blockquote { + margin: 1.5rem 0; + padding-left: 1.25rem; + border-left: 2px solid var(--rule); + color: var(--muted); + font-style: italic; +} + +pre, +code { + font-family: ui-monospace, "SF Mono", Menlo, monospace; + font-size: 0.85em; +} + +pre { + padding: 1rem; + overflow-x: auto; + background: color-mix(in srgb, var(--text) 6%, transparent); + border-radius: 6px; +} + +code { + padding: 0.1em 0.3em; + background: color-mix(in srgb, var(--text) 7%, transparent); + border-radius: 3px; +} + +pre code { + padding: 0; + background: none; +} + +img { + max-width: 100%; + height: auto; +} + +.back { + margin-top: 3rem; + font-size: 0.9rem; +} + +.empty { + color: var(--muted); +} + +.colophon { + padding-top: 1.25rem; + padding-bottom: 3rem; + border-top: 1px solid var(--rule); + color: var(--muted); + font-size: 0.85rem; +} diff --git a/examples/atlas/themes/atlas/templates/404.html b/examples/atlas/themes/atlas/templates/404.html new file mode 100644 index 0000000..83347f9 --- /dev/null +++ b/examples/atlas/themes/atlas/templates/404.html @@ -0,0 +1,15 @@ +{% extends "base.html" %} + +{% block title %}Página no encontrada · {{ site.title }}{% endblock %} + +{% block content %} +
+
+

Página no encontrada

+
+
+

No hay nada en esta dirección. Puede que el enlace esté viejo o que la página nunca haya existido.

+

Volver a Inicio · Ver las guías

+
+
+{% endblock %} diff --git a/examples/atlas/themes/atlas/templates/base.html b/examples/atlas/themes/atlas/templates/base.html new file mode 100644 index 0000000..366bd73 --- /dev/null +++ b/examples/atlas/themes/atlas/templates/base.html @@ -0,0 +1,34 @@ + + + + + + {% block title %}{{ site.title }}{% endblock %} + {% if site.description %}{% endif %} + + + + + + +
+ + + + +

{{ site.description }}

+ +
+
+ {% block content %}{% endblock %} +
+ + + diff --git a/examples/atlas/themes/atlas/templates/colophon.html b/examples/atlas/themes/atlas/templates/colophon.html new file mode 100644 index 0000000..547875b --- /dev/null +++ b/examples/atlas/themes/atlas/templates/colophon.html @@ -0,0 +1,2 @@ +

{{ site.title }} · Hecho con jamstack 2.0.

+

Colofón del tema. El proyecto lo pisa con templates/colophon.html.

diff --git a/examples/atlas/themes/atlas/templates/guide-index.html b/examples/atlas/themes/atlas/templates/guide-index.html new file mode 100644 index 0000000..eb26e3d --- /dev/null +++ b/examples/atlas/themes/atlas/templates/guide-index.html @@ -0,0 +1,21 @@ +{% extends "base.html" %} + +{% block title %}{{ page.title }} · {{ site.title }}{% endblock %} + +{% block content %} +
+
+

{{ page.title }}

+
+
{{ page.content }}
+
+ + +{% endblock %} diff --git a/examples/atlas/themes/atlas/templates/guide.html b/examples/atlas/themes/atlas/templates/guide.html new file mode 100644 index 0000000..196dd49 --- /dev/null +++ b/examples/atlas/themes/atlas/templates/guide.html @@ -0,0 +1,5 @@ +{% extends "post.html" %} + +{% block post_footer %} +

← Todas las guías

+{% endblock %} diff --git a/examples/atlas/themes/atlas/templates/index.html b/examples/atlas/themes/atlas/templates/index.html new file mode 100644 index 0000000..ca2b909 --- /dev/null +++ b/examples/atlas/themes/atlas/templates/index.html @@ -0,0 +1,30 @@ +{% extends "base.html" %} + +{% block content %} + {% if page.content %} +
{{ page.content }}
+ {% endif %} + + {% set posts = pages | selectattr("date") | list %} +

Últimos posts

+ {% if posts %} +
    + {% for item in posts[:3] %} +
  1. + {{ item.title }} + + {% if item.meta.get("summary") %}

    {{ item.meta.get("summary") }}

    {% endif %} +
  2. + {% endfor %} +
+ {% else %} +

Todavía no hay posts.

+ {% endif %} + +

Guías

+ +{% endblock %} diff --git a/examples/atlas/themes/atlas/templates/page.html b/examples/atlas/themes/atlas/templates/page.html new file mode 100644 index 0000000..bb6b264 --- /dev/null +++ b/examples/atlas/themes/atlas/templates/page.html @@ -0,0 +1,5 @@ +{% extends "post.html" %} + +{% block post_footer %} +

← Inicio

+{% endblock %} diff --git a/examples/atlas/themes/atlas/templates/post.html b/examples/atlas/themes/atlas/templates/post.html new file mode 100644 index 0000000..4f49305 --- /dev/null +++ b/examples/atlas/themes/atlas/templates/post.html @@ -0,0 +1,19 @@ +{% extends "base.html" %} + +{% block title %}{{ page.title }} · {{ site.title }}{% endblock %} + +{% block content %} +
+
+

{{ page.title }}

+

+ {% if page.date %}{% endif %} + {% set words = page.content | striptags | wordcount %} + {% set minutes = [(words / 200) | round(0, "ceil") | int, 1] | max %} + {{ minutes }} min de lectura +

+
+
{{ page.content }}
+ {% block post_footer %}{% endblock %} +
+{% endblock %} diff --git a/examples/atlas/themes/atlas/theme.toml b/examples/atlas/themes/atlas/theme.toml new file mode 100644 index 0000000..22c2dbd --- /dev/null +++ b/examples/atlas/themes/atlas/theme.toml @@ -0,0 +1,2 @@ +name = "atlas" +description = "A field-notes theme with a guide index, reading time and a project override." diff --git a/examples/blog/.gitignore b/examples/blog/.gitignore new file mode 100644 index 0000000..849ddff --- /dev/null +++ b/examples/blog/.gitignore @@ -0,0 +1 @@ +dist/ diff --git a/examples/blog/content/index.md b/examples/blog/content/index.md new file mode 100644 index 0000000..b0028d6 --- /dev/null +++ b/examples/blog/content/index.md @@ -0,0 +1,5 @@ ++++ +title = "Welcome" ++++ + +This is your new site. Edit `content/index.md` and run `jamstack build`. diff --git a/examples/blog/content/posts/hello-world.md b/examples/blog/content/posts/hello-world.md new file mode 100644 index 0000000..b39ad81 --- /dev/null +++ b/examples/blog/content/posts/hello-world.md @@ -0,0 +1,9 @@ ++++ +title = "Hello, world" +date = 2026-11-06 +template = "post" +summary = "The first post on your new site." ++++ + +This is your first post. Edit `content/posts/hello-world.md` and run +`jamstack build` to see the changes. diff --git a/examples/blog/site.toml b/examples/blog/site.toml new file mode 100644 index 0000000..686e0c7 --- /dev/null +++ b/examples/blog/site.toml @@ -0,0 +1,12 @@ +[site] +title = "Blog" +description = "" +# Absolute public URL. Required to generate sitemap.xml and feed.xml. +base_url = "" +language = "en" + +[build] +output = "dist" + +[theme] +name = "blog" diff --git a/examples/handbook/.gitignore b/examples/handbook/.gitignore new file mode 100644 index 0000000..849ddff --- /dev/null +++ b/examples/handbook/.gitignore @@ -0,0 +1 @@ +dist/ diff --git a/examples/handbook/content/getting-started/index.md b/examples/handbook/content/getting-started/index.md new file mode 100644 index 0000000..567a3af --- /dev/null +++ b/examples/handbook/content/getting-started/index.md @@ -0,0 +1,22 @@ ++++ +title = "Introduction" +section = "getting-started" +order = 1 +nav_title = "Introduction" ++++ + +This example is a documentation site: three sections, a persistent sidebar and +pages that are mostly prose. + +The sidebar is built from front matter. Each page declares a `section` and an +`order`; the theme groups pages by section and sorts them by that number. + +The section order comes from `site.toml`, not from the filesystem: + +```toml +[extra.sidebar] +sections = ["getting-started", "guides", "reference"] +``` + +Any section missing from that list is appended alphabetically, so the site still +works if someone adds a page with a new section. diff --git a/examples/handbook/content/getting-started/install.md b/examples/handbook/content/getting-started/install.md new file mode 100644 index 0000000..0a0d7f2 --- /dev/null +++ b/examples/handbook/content/getting-started/install.md @@ -0,0 +1,24 @@ ++++ +title = "Installation" +section = "getting-started" +order = 2 ++++ + +Install the package and create a site: + +```bash +pip install jamstack +jamstack init my-docs --theme minimal +cd my-docs +jamstack build +``` + +To try this example exactly as it is: + +```bash +jamstack build examples/handbook +jamstack serve examples/handbook --port 8000 +``` + +The second command rebuilds when a file changes. It is the same engine, only +the theme and the content differ. diff --git a/examples/handbook/content/guides/content.md b/examples/handbook/content/guides/content.md new file mode 100644 index 0000000..9459c52 --- /dev/null +++ b/examples/handbook/content/guides/content.md @@ -0,0 +1,20 @@ ++++ +title = "Writing content" +section = "guides" +order = 1 ++++ + +Pages are Markdown or HTML. Front matter is TOML between `+++` lines: + +```toml ++++ +title = "Writing content" +section = "guides" +order = 1 ++++ +``` + +Keys the engine understands are `title`, `date`, `template`, `draft`, `summary` +and `url`. Everything else is kept as-is and is available to the theme as +`page.meta`, which is how this example reads `section`, `order` and +`nav_title`. diff --git a/examples/handbook/content/guides/deploy.md b/examples/handbook/content/guides/deploy.md new file mode 100644 index 0000000..7e5e9bc --- /dev/null +++ b/examples/handbook/content/guides/deploy.md @@ -0,0 +1,15 @@ ++++ +title = "Deploying" +section = "guides" +order = 3 ++++ + +The build writes a self-contained directory, so any static host works. + +1. Run `jamstack build --clean`. +2. Upload `dist/` to your host. +3. Point the domain at it. + +Set `base_url` in `site.toml` to get an absolute `sitemap.xml` and `feed.xml`. +The `404.html` generated from the theme is used by hosts that support custom +error pages, and by `jamstack serve`. diff --git a/examples/handbook/content/guides/themes.md b/examples/handbook/content/guides/themes.md new file mode 100644 index 0000000..51c04b7 --- /dev/null +++ b/examples/handbook/content/guides/themes.md @@ -0,0 +1,15 @@ ++++ +title = "Themes" +section = "guides" +order = 2 ++++ + +A theme is a directory with a `theme.toml`, a `templates/` directory and an +optional `static/` directory. + +The theme in this example lives in `themes/handbook`, so it is local to the +project. The engine looks there first and falls back to the bundled themes. + +Templates in `templates/` at the project root override the theme ones. Static +files work the same way: the theme is copied first, then the project overwrites +what it needs. diff --git a/examples/handbook/content/index.md b/examples/handbook/content/index.md new file mode 100644 index 0000000..367afe1 --- /dev/null +++ b/examples/handbook/content/index.md @@ -0,0 +1,9 @@ ++++ +title = "Handbook" ++++ + +A small documentation site that shows how far the 2.0 engine goes without +touching the core: a local theme, a configurable sidebar, footer links from +`[extra]`, previous and next navigation, and clean URLs. + +Start with the introduction, then read the guides in order. diff --git a/examples/handbook/content/reference/cli.md b/examples/handbook/content/reference/cli.md new file mode 100644 index 0000000..a0ff3ba --- /dev/null +++ b/examples/handbook/content/reference/cli.md @@ -0,0 +1,15 @@ ++++ +title = "Command line" +section = "reference" +order = 2 ++++ + +Four commands cover the whole workflow: + +- `jamstack init PATH --theme NAME` creates a site. +- `jamstack build` renders `content/` into `dist/`. +- `jamstack serve` builds, serves and rebuilds on changes. +- `jamstack themes` lists bundled and local themes. + +`build` accepts `--clean` to remove stale files and `--drafts` to include pages +marked `draft = true`. diff --git a/examples/handbook/content/reference/config.md b/examples/handbook/content/reference/config.md new file mode 100644 index 0000000..b6f452c --- /dev/null +++ b/examples/handbook/content/reference/config.md @@ -0,0 +1,18 @@ ++++ +title = "Configuration" +section = "reference" +order = 1 ++++ + +`site.toml` has three fixed tables and one free-form table. + +| Table | Purpose | +| --- | --- | +| `[site]` | Title, description, author, base URL and language | +| `[build]` | Output directory | +| `[theme]` | Theme name | +| `[extra]` | Anything the theme needs | + +`[extra]` is not interpreted by the engine. This site reads footer text and +links from it, but the engine only guarantees that it is a table and exposes it +as `site.extra`. diff --git a/examples/handbook/content/reference/roadmap.md b/examples/handbook/content/reference/roadmap.md new file mode 100644 index 0000000..96fd5a9 --- /dev/null +++ b/examples/handbook/content/reference/roadmap.md @@ -0,0 +1,8 @@ ++++ +title = "Roadmap" +section = "reference" +order = 3 +draft = true ++++ + +This page is a draft. It only appears with `jamstack build --drafts`. diff --git a/examples/handbook/site.toml b/examples/handbook/site.toml new file mode 100644 index 0000000..18de130 --- /dev/null +++ b/examples/handbook/site.toml @@ -0,0 +1,23 @@ +[site] +title = "Handbook" +description = "A documentation site built with jamstack." +author = "jamstack" +base_url = "https://handbook.example.com" +language = "en" + +[build] +output = "dist" + +[theme] +name = "handbook" + +[extra] +footer_text = "Built with jamstack. Content licensed CC BY 4.0." +footer_note = "This example exercises the free-form [extra] table." + +[extra.links] +GitHub = "https://github.com/jamstackpy/jamstack" +PyPI = "https://pypi.org/project/jamstack/" + +[extra.sidebar] +sections = ["getting-started", "guides", "reference"] diff --git a/examples/handbook/themes/handbook/static/style.css b/examples/handbook/themes/handbook/static/style.css new file mode 100644 index 0000000..5ecd116 --- /dev/null +++ b/examples/handbook/themes/handbook/static/style.css @@ -0,0 +1,147 @@ +:root { + --bg: #fbfaf7; + --fg: #1f2328; + --muted: #6b7280; + --line: #e3e0d8; + --accent: #0f5e59; + --sidebar: 15rem; +} + +@media (prefers-color-scheme: dark) { + :root { + --bg: #14181d; + --fg: #e6e6e6; + --muted: #9aa4af; + --line: #2a3038; + --accent: #7fd1c9; + } +} + +* { box-sizing: border-box; } + +body { + margin: 0; + background: var(--bg); + color: var(--fg); + font: 16px/1.65 ui-sans-serif, system-ui, -apple-system, "Segoe UI", sans-serif; +} + +a { color: var(--accent); } + +.topbar { + display: flex; + align-items: center; + justify-content: space-between; + gap: 1rem; + max-width: 72rem; + margin: 0 auto; + padding: 1rem 1.5rem; + border-bottom: 1px solid var(--line); +} + +.brand { + font-weight: 700; + text-decoration: none; + color: var(--fg); +} + +.topnav { display: flex; gap: 1rem; font-size: 0.9rem; } +.topnav a { text-decoration: none; } + +.layout { + display: grid; + grid-template-columns: var(--sidebar) minmax(0, 1fr); + gap: 3rem; + max-width: 72rem; + margin: 0 auto; + padding: 2rem 1.5rem; +} + +.sidebar { + position: sticky; + top: 1rem; + align-self: start; + font-size: 0.92rem; +} + +.sidebar-section { margin-bottom: 1.5rem; } +.sidebar-section h2 { + margin: 0 0 0.4rem; + font-size: 0.72rem; + letter-spacing: 0.08em; + text-transform: uppercase; + color: var(--muted); +} +.sidebar ul { list-style: none; margin: 0; padding: 0; } +.sidebar li a { + display: block; + padding: 0.25rem 0.6rem; + border-radius: 6px; + text-decoration: none; + color: var(--fg); +} +.sidebar li a:hover { background: var(--line); } +.sidebar li.active a { + background: var(--accent); + color: var(--bg); +} + +.content { min-width: 0; } + +.prose { max-width: 46rem; } +.prose h1 { margin-top: 0; font-size: 2rem; letter-spacing: -0.02em; } +.prose h2 { margin-top: 2rem; font-size: 1.3rem; } +.prose code { + padding: 0.1em 0.35em; + border-radius: 4px; + background: var(--line); + font-size: 0.9em; +} +.prose pre { + overflow-x: auto; + padding: 1rem; + border: 1px solid var(--line); + border-radius: 8px; +} +.prose pre code { padding: 0; background: none; } +.prose table { width: 100%; border-collapse: collapse; } +.prose th, .prose td { + padding: 0.5rem 0.75rem; + border-bottom: 1px solid var(--line); + text-align: left; +} + +.kicker { + margin: 0; + font: 600 0.72rem/1 ui-monospace, monospace; + letter-spacing: 0.12em; + text-transform: uppercase; + color: var(--muted); +} + +.pager { + display: flex; + justify-content: space-between; + gap: 1rem; + max-width: 46rem; + margin-top: 3rem; + padding-top: 1rem; + border-top: 1px solid var(--line); +} +.pager a { text-decoration: none; } +.pager .next { margin-left: auto; text-align: right; } + +.footer { + max-width: 72rem; + margin: 0 auto; + padding: 1.5rem; + border-top: 1px solid var(--line); + font-size: 0.85rem; +} +.footer p { margin: 0.2rem 0; } +.muted { color: var(--muted); } + +@media (max-width: 48rem) { + .layout { grid-template-columns: 1fr; gap: 1.5rem; } + .sidebar { position: static; } +} diff --git a/examples/handbook/themes/handbook/templates/404.html b/examples/handbook/themes/handbook/templates/404.html new file mode 100644 index 0000000..7a46720 --- /dev/null +++ b/examples/handbook/themes/handbook/templates/404.html @@ -0,0 +1,8 @@ +{% extends "base.html" %} +{% block title %}Page not found · {{ site.title }}{% endblock %} +{% block content %} +
+

Page not found

+

That page does not exist. Back to the handbook.

+
+{% 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" %} +
+
+ + + diff --git a/examples/handbook/themes/handbook/templates/index.html b/examples/handbook/themes/handbook/templates/index.html new file mode 100644 index 0000000..8e8761d --- /dev/null +++ b/examples/handbook/themes/handbook/templates/index.html @@ -0,0 +1,8 @@ +{% extends "base.html" %} +{% block content %} +
+

Documentation

+

{{ page.title }}

+ {{ page.content }} +
+{% endblock %} diff --git a/examples/handbook/themes/handbook/templates/page.html b/examples/handbook/themes/handbook/templates/page.html new file mode 100644 index 0000000..15349e8 --- /dev/null +++ b/examples/handbook/themes/handbook/templates/page.html @@ -0,0 +1,8 @@ +{% extends "base.html" %} +{% block title %}{{ page.title }} · {{ site.title }}{% endblock %} +{% block content %} +
+

{{ page.title }}

+ {{ page.content }} +
+{% endblock %} diff --git a/examples/handbook/themes/handbook/theme.toml b/examples/handbook/themes/handbook/theme.toml new file mode 100644 index 0000000..0d09b79 --- /dev/null +++ b/examples/handbook/themes/handbook/theme.toml @@ -0,0 +1,2 @@ +name = "handbook" +description = "A documentation layout with a configurable sidebar and footer links." diff --git a/examples/minimal/.gitignore b/examples/minimal/.gitignore new file mode 100644 index 0000000..849ddff --- /dev/null +++ b/examples/minimal/.gitignore @@ -0,0 +1 @@ +dist/ diff --git a/examples/minimal/content/index.md b/examples/minimal/content/index.md new file mode 100644 index 0000000..b0028d6 --- /dev/null +++ b/examples/minimal/content/index.md @@ -0,0 +1,5 @@ ++++ +title = "Welcome" ++++ + +This is your new site. Edit `content/index.md` and run `jamstack build`. diff --git a/examples/minimal/site.toml b/examples/minimal/site.toml new file mode 100644 index 0000000..5e46c4f --- /dev/null +++ b/examples/minimal/site.toml @@ -0,0 +1,12 @@ +[site] +title = "Minimal" +description = "" +# Absolute public URL. Required to generate sitemap.xml and feed.xml. +base_url = "" +language = "en" + +[build] +output = "dist" + +[theme] +name = "minimal"