eleventy-starter — Eleventy Starter Template

SHA-256: bb892adad206e8118468e6effcb05ed2ad45b90c46d884d5d727327f80a945a0

2026-10-02T11:12:53.697Z

# Eleventy Starter

Starter template con Eleventy + Tailwind CSS v4 listo para proyectos rápidos.

## 🚀 Demo

https://eleventy-starter-osva.netlify.app/

## Preview

![preview](./screenshot.png)

## ✨ Features

- Eleventy v3 + Nunjucks
- Tailwind CSS v4 utility-first
- Sistema de tokens CSS (primitivos + semánticos)
- Componentes accesibles (JS vanilla)
- Ready para deploy (Netlify, Vercel, etc.)

![HTML5](https://img.shields.io/badge/HTML5-E34F26?style=flat-square&logo=html5&logoColor=white)
![Nunjucks](https://img.shields.io/badge/Nunjucks-1C4913?style=flat-square&logo=nunjucks&logoColor=white)
![Tailwind CSS](https://img.shields.io/badge/Tailwind%20CSS%20v4-06B6D4?style=flat-square&logo=tailwindcss&logoColor=white)
![JavaScript](https://img.shields.io/badge/JavaScript-F7DF1E?style=flat-square&logo=javascript&logoColor=black)
![Eleventy](https://img.shields.io/badge/Eleventy%20v3-222222?style=flat-square&logo=eleventy&logoColor=white)
![pnpm](https://img.shields.io/badge/pnpm-F69220?style=flat-square&logo=pnpm&logoColor=white)
![Git](https://img.shields.io/badge/Git-F05032?style=flat-square&logo=git&logoColor=white)
![GitHub](https://img.shields.io/badge/GitHub-181717?style=flat-square&logo=github&logoColor=white)

Starter template para proyectos HTML estáticos. Nunjucks como motor de templates, Tailwind CSS v4 con arquitectura modular de tokens y JS vanilla para componentes accesibles.

El equipo de desarrollo consume los archivos compilados en `dist/`. El autor trabaja en `src/`.

---

## Inicio rápido

Clona el template y empieza a trabajar en segundos:

```bash
# Clonar el repositorio
git clone https://github.com/Osvalam86/eleventy-starter.git mi-proyecto
cd mi-proyecto

# Instalar dependencias
pnpm install

# Iniciar servidor de desarrollo
pnpm run dev
```

Abrir [http://localhost:8080](http://localhost:8080).

---

## Scripts

| Comando             | Descripción                                               |
| ------------------- | --------------------------------------------------------- |
| `pnpm run dev`      | Servidor de desarrollo con hot-reload en `localhost:8080` |
| `pnpm run build`    | Genera el sitio estático en `dist/` (CSS minificado)      |
| `pnpm run clean`    | Elimina la carpeta `dist/`                                |
| `pnpm format`       | Formatea todos los archivos `src/` con Prettier           |
| `pnpm format:check` | Verifica formato sin modificar archivos (útil en CI)      |

El script `dev` corre Eleventy y Tailwind CLI en paralelo. El script `build` los ejecuta en secuencia: CSS primero, luego HTML.

---

## Estructura de carpetas

```
eleventy-starter/
├── .eleventy.js                  # Configuración de Eleventy
├── .eleventyignore               # Archivos que Eleventy debe ignorar
├── .prettierignore
├── prettier.config.js            # Prettier + prettier-plugin-tailwindcss
├── .vscode/
│   └── settings.json             # formatOnSave automático con Prettier
├── package.json
│
├── src/
│   ├── _data/
│   │   ├── site.json             # Metadata global (nombre, url, idioma, copyright)
│   │   └── nav.json              # Items de navegación
│   │
│   ├── _includes/
│   │   ├── layouts/
│   │   │   ├── base.njk          # Shell HTML completo (head, body, scripts)
│   │   │   └── page.njk          # Layout estándar (extiende base.njk)
│   │   ├── partials/
│   │   │   ├── header.njk        # Barra de navegación
│   │   │   └── footer.njk        # Pie de página
│   │   └── components/
│   │       ├── button.njk        # Macro: Button(props)
│   │       ├── card.njk          # Macro: Card(props)
│   │       └── dialog.njk        # Macro: Dialog(props) con {% call %}
│   │
│   ├── assets/
│   │   ├── css/
│   │   │   ├── input.css         # Entry point de Tailwind CSS
│   │   │   ├── primitive.css     # Tokens crudos en :root
│   │   │   ├── theme.css         # Tokens semánticos en @theme
│   │   │   ├── base.css          # Estilos base del body y tipografía (CSS puro)
│   │   │   └── utilities/
│   │   │       ├── focus.css
│   │   │       └── scrollbar.css
│   │   ├── images/               # Imágenes (copiadas tal cual a dist/)
│   │   └── fonts/                # Fuentes (copiadas tal cual a dist/)
│   │
│   ├── js/
│   │   ├── main.js               # Entry point — importa e inicializa componentes
│   │   └── components/
│   │       ├── dialog.js
│   │       ├── dropdown.js
│   │       ├── menu.js
│   │       └── tabs.js
│   │
│   └── pages/
│       ├── index.njk             → dist/index.html
│       ├── index.11tydata.json   # Data de la home (layout, título, contenido)
│       ├── about/
│       │   ├── index.njk         → dist/about/index.html
│       │   └── index.11tydata.json
│       └── components/
│           ├── index.njk         → dist/components/index.html
│           └── index.11tydata.json
│
└── dist/                         # BUILD OUTPUT — no incluido en git
    ├── index.html
    ├── css/styles.css
    └── js/main.js
```

---

## Arquitectura CSS

El sistema de tokens usa dos capas separadas para evitar acoplamiento entre valores crudos y su uso semántico.

### Capa 1 — `primitive.css`

Define los valores crudos en `:root`. No genera utilidades de Tailwind. Sirve como fuente única de verdad para colores, escalas y valores base del proyecto.

```css
/* src/assets/css/primitive.css */
:root {
  --color-primary-50: #eef2ff;
  --color-primary-100: #e0e7ff;
}
```

### Capa 2 — `theme.css`

Define los tokens semánticos dentro de `@theme`. Tailwind v4 lee este bloque y genera automáticamente todas las utilidades: `text-brand-500`, `bg-brand-100`, `border-brand-700`, etc.

```css
/* src/assets/css/theme.css */
@theme {
  /* Colores de marca */
  --color-brand-50: var(--color-primary-50);
  --color-brand-100: var(--color-primary-100);
  --color-brand-900: var(--color-primary-900);

  /* Tipografía */
  --font-sans: "Inter", ui-sans-serif, system-ui, sans-serif;
  --font-mono: "JetBrains Mono", ui-monospace, monospace;
}
```

**Para adaptar el starter a un nuevo proyecto:** modifica los valores en `primitive.css` y actualiza las referencias en `theme.css`. El resto del código no cambia.

### Estilos en componentes

Los estilos viven directamente en cada macro `.njk`, sin archivos CSS separados ni `@apply`. Las variantes se resuelven con mapas Nunjucks que devuelven las clases Tailwind correspondientes:

```njk
{# button.njk #}
{%- set sizeMap = {
  "sm": "px-3 py-1.5 text-xs",
  "md": "px-4 py-2 text-sm",
  "lg": "px-6 py-3 text-base"
} -%}
{%- set variantMap = {
  "primary": "bg-brand-500 text-white hover:bg-brand-600",
  "secondary": "border border-gray-300 bg-white text-gray-700 hover:bg-gray-50",
  "ghost": "text-gray-600 hover:bg-gray-100 hover:text-gray-900"
} -%}
```

Para los elementos que no usan macro (badges inline, campos de formulario), las clases se escriben directamente en el HTML del template que los consume.

---

## Crear páginas

Cada página vive en su propia subcarpeta dentro de `src/pages/` y se compone de dos archivos:

- `index.njk` — el template HTML/Nunjucks, sin front matter
- `index.11tydata.json` — el data file con metadata y contenido de la página

```
src/pages/
└── mi-pagina/
    ├── index.njk
    └── index.11tydata.json     → aplica solo a index.njk de esta carpeta
```

**`index.11tydata.json`** — controla el layout, la ruta y el contenido:

```json
{
  "layout": "page.njk",
  "permalink": "/mi-pagina/index.html",
  "title": "Mi página",
  "pageTitle": "Título visible en el H1",
  "pageSubtitle": "Subtítulo opcional debajo del H1.",
  "sections": [{ "heading": "Sección uno", "body": "Texto de la sección." }]
}
```

**`index.njk`** — solo markup, consume las variables del data file:

```njk
<div class="space-y-10">
  {% for section in sections %}
    <section>
      <h2 class="text-base font-semibold text-gray-900">{{ section.heading }}</h2>
      <p class="text-sm text-gray-500">{{ section.body }}</p>
    </section>
  {% endfor %}
</div>
```

> Este patrón usa el [Data Cascade de Eleventy](https://www.11ty.dev/docs/data-cascade/): el `.11tydata.json` aplica únicamente al template con el mismo nombre, sin contaminar el namespace global de `_data/`.

---

## Macros de componentes

Importa el macro al inicio de la página y llámalo con un objeto de props.

### Button

Genera `<button>` o `<a>` según si se pasa `href`.

```njk
{% from "components/button.njk" import Button %}

{# Botón estándar #}
{{ Button({ label: "Guardar", variant: "primary" }) }}

{# Enlace con tamaño grande #}
{{ Button({ label: "Ver más", variant: "secondary", size: "lg", href: "/about/" }) }}

{# Con atributos HTML adicionales #}
{{ Button({ label: "Abrir", variant: "ghost", attrs: 'data-component="dialog-trigger" data-target="mi-dialog"' }) }}
```

| Prop       | Tipo    | Default     | Opciones                                  |
| ---------- | ------- | ----------- | ----------------------------------------- |
| `label`    | string  | —           | Texto del botón (requerido)               |
| `variant`  | string  | `"primary"` | `"primary"` \| `"secondary"` \| `"ghost"` |
| `size`     | string  | `"md"`      | `"sm"` \| `"md"` \| `"lg"`                |
| `href`     | string  | —           | Convierte el elemento en `<a>`            |
| `type`     | string  | `"button"`  | `"button"` \| `"submit"` \| `"reset"`     |
| `disabled` | boolean | —           | Deshabilita el elemento                   |
| `attrs`    | string  | —           | Atributos HTML adicionales como string    |

### Card

Tarjeta de contenido con badge opcional y variante de enlace.

```njk
{% from "components/card.njk" import Card %}

{# Tarjeta estática #}
{{ Card({ title: "Título", description: "Descripción de la tarjeta." }) }}

{# Con badge #}
{{ Card({ title: "Artículo", description: "Texto.", badge: "Nuevo" }) }}

{# Toda la tarjeta como enlace #}
{{ Card({ title: "Ver más", description: "Texto.", href: "/articulo/", badge: "Link" }) }}

{# Sin efecto hover #}
{{ Card({ title: "Estático", description: "Sin hover.", hover: false }) }}
```

| Prop          | Tipo    | Default | Descripción                                 |
| ------------- | ------- | ------- | ------------------------------------------- |
| `title`       | string  | —       | Título de la tarjeta (requerido)            |
| `description` | string  | —       | Texto descriptivo                           |
| `badge`       | string  | —       | Badge encima del título                     |
| `href`        | string  | —       | Convierte la tarjeta en enlace              |
| `hover`       | boolean | `true`  | Agrega `hover:shadow-md` al pasar el cursor |
| `class`       | string  | —       | Clases CSS adicionales                      |

### Dialog

Usa `{% call %}` para pasar el contenido del cuerpo al macro.

```njk
{% from "components/button.njk" import Button %}
{% from "components/dialog.njk" import Dialog %}

{# Trigger — puede estar en cualquier parte de la página #}
{{ Button({
  label: "Abrir",
  variant: "secondary",
  attrs: 'data-component="dialog-trigger" data-target="mi-dialog"'
}) }}

{# Panel del dialog #}
{% call Dialog({ id: "mi-dialog", title: "Confirmar acción", size: "sm" }) %}
  <p class="text-sm text-gray-600 mb-6">Esta acción no se puede deshacer.</p>
  <div class="flex justify-end gap-3">
    {{ Button({ label: "Cancelar",  variant: "ghost",   attrs: 'data-component="dialog-close"' }) }}
    {{ Button({ label: "Confirmar", variant: "primary" }) }}
  </div>
{% endcall %}
```

| Prop          | Tipo   | Default | Descripción                                                                   |
| ------------- | ------ | ------- | ----------------------------------------------------------------------------- |
| `id`          | string | —       | ID único del dialog (requerido, debe coincidir con `data-target` del trigger) |
| `title`       | string | —       | Título en el header                                                           |
| `description` | string | —       | Subtítulo opcional en el header                                               |
| `size`        | string | `"md"`  | `"sm"` \| `"md"` \| `"lg"` \| `"xl"`                                          |
| `class`       | string | —       | Clases adicionales al panel                                                   |

El dialog gestiona foco, `aria-modal`, cierre con `Escape` y click en backdrop de forma automática vía `dialog.js`.

---

## Agregar componentes JS

Cada componente exporta una función `init(root)`. El atributo `data-component` conecta el comportamiento con el HTML sin acoplarse a clases CSS.

**1. Crear el módulo en `src/js/components/`:**

```javascript
// src/js/components/tooltip.js
export function initTooltips(root) {
  root.querySelectorAll('[data-component="tooltip"]').forEach((el) => {
    // lógica del componente
  });
}
```

**2. Importar e inicializar en `src/js/main.js`:**

```javascript
import { initTooltips } from "./components/tooltip.js";

document.addEventListener("DOMContentLoaded", () => {
  initTooltips(document);
});
```

**3. Usar en el template con `data-component`:**

```html
<span data-component="tooltip" data-tip="Texto del tooltip"> Hover aquí </span>
```

---

## Adaptar para un nuevo proyecto

Al usar este starter como base, sigue este checklist antes de empezar a maquetar.

### 1. Renombrar el repositorio y el paquete

Si clonas el repo manualmente (sin usar "Use this template" en GitHub):

```bash
# Clonar con el nombre del nuevo proyecto
git clone https://github.com/Osvalam86/eleventy-starter.git mi-nuevo-proyecto
cd mi-nuevo-proyecto

# Desconectar del repositorio de origen y apuntar al nuevo remote
git remote remove origin
git remote add origin https://github.com/TU_USUARIO/mi-nuevo-proyecto.git
```

Actualizar el nombre del paquete en `package.json`:

```json
{
  "name": "mi-nuevo-proyecto"
}
```

### 2. Actualizar los datos del sitio

Editar `src/_data/site.json` con los datos reales del proyecto:

```json
{
  "name": "Nombre del Proyecto",
  "description": "Descripción del proyecto.",
  "url": "https://mi-proyecto.com",
  "lang": "es",
  "copyright": "Todos los derechos reservados."
}
```

Editar `src/_data/nav.json` con la navegación real. Elimina o agrega items según la estructura de páginas del proyecto:

```json
{
  "primary": [
    { "label": "Inicio", "url": "/" },
    { "label": "Servicios", "url": "/servicios/" }
  ],
  "footer": [{ "label": "Privacidad", "url": "/privacidad/" }]
}
```

### 3. Reemplazar la paleta de colores

Abrir `src/assets/css/primitive.css` y sustituir los valores hex de `--color-primary-*` con la paleta del proyecto. Figma exporta colores en hex directamente — pégalos aquí:

```css
:root {
  --color-primary-50: #fdf4ff; /* ← reemplazar con la paleta del proyecto */
  --color-primary-100: #fae8ff;
  --color-primary-200: #f5d0fe;
  --color-primary-300: #f0abfc;
  --color-primary-400: #e879f9;
  --color-primary-500: #d946ef; /* ← color principal */
  --color-primary-600: #c026d3;
  --color-primary-700: #a21caf;
  --color-primary-800: #86198f;
  --color-primary-900: #701a75;
}
```

`theme.css` no necesita cambios — las referencias `var(--color-primary-*)` apuntan automáticamente a los nuevos valores. Las utilidades de Tailwind (`text-brand-500`, `bg-brand-100`, etc.) se regeneran solas.

### 4. Actualizar las fuentes

En `src/assets/css/theme.css`, cambiar las fuentes del proyecto:

```css
@theme {
  --font-sans: "Tu Fuente", ui-sans-serif, system-ui, sans-serif;
  --font-mono: ui-monospace, monospace;
}
```

Si usas Google Fonts, añadir el `<link>` en `src/_includes/layouts/base.njk` dentro del `<head>`.

### 5. Limpiar las páginas de demo

Eliminar o vaciar el contenido de las páginas de ejemplo. Cada página se compone de su `index.njk` y su `index.11tydata.json`:

- `src/pages/index.*` — reemplazar con la home real
- `src/pages/about/` — adaptar o eliminar la carpeta completa
- `src/pages/components/` — mantener como referencia interna o eliminar si no es necesario

### Lo que NO hay que cambiar

- La estructura de carpetas `src/` — Eleventy y Tailwind dependen de ella
- Los archivos en `src/_includes/` — los macros y layouts son reutilizables tal cual
- Los archivos en `src/js/` — los componentes JS funcionan sin configuración adicional
- `src/assets/css/theme.css` — solo cambiar si se necesitan tokens semánticos nuevos

---

## Prettier

El proyecto incluye [Prettier](https://prettier.io/) con [`prettier-plugin-tailwindcss`](https://github.com/tailwindlabs/prettier-plugin-tailwindcss) para ordenar clases Tailwind automáticamente.

La configuración está en `prettier.config.js`. El plugin necesita saber dónde está el CSS de entrada de Tailwind v4 (no hay `tailwind.config.js`), por eso se declara `tailwindStylesheet`.

**Uso en el día a día:**

Si usas VSCode, el formato se aplica automáticamente al guardar (configurado en `.vscode/settings.json`). Para formatear todo el proyecto manualmente:

```bash
# Formatea y reescribe
pnpm format

# Solo verifica sin modificar (útil en CI)
pnpm format:check
```

> `src/_includes/layouts/` está excluido del formateo en `.prettierignore` porque los layouts usan comentarios Nunjucks `{# #}` que el parser HTML de Prettier no soporta. El resto de `.njk`, `.js` y `.css` se formatea sin problemas.

---

## Deploy

El output en `dist/` son archivos HTML, CSS y JS estáticos — se pueden servir desde cualquier hosting estático.

```bash
# Generar build de producción
pnpm run build
```

El contenido de `dist/` está listo para subir. Plataformas compatibles: **Netlify**, **Vercel**, **GitHub Pages**, **Cloudflare Pages** y cualquier servidor estático (Apache, nginx).

### Demo en producción: https://eleventy-starter-osva.netlify.app/

---

## Licencia

MIT © Osvaldo Ocampo

---

## Autor

[![GitHub](https://img.shields.io/badge/GitHub-Osvalam86-181717?style=flat-square&logo=github&logoColor=white)](https://github.com/Osvalam86)
[![Medium](https://img.shields.io/badge/[email protected]?style=flat-square&logo=medium&logoColor=white)](https://medium.com/@osvaldo.ocampo)