# Starlight vs Htmlpress

> Páginas HTML planas en un binario frente a las islas de Astro para docs.

[Starlight](https://starlight.astro.build) es el tema oficial de documentación de Astro, mantenido por el equipo de Astro. Usa la arquitectura de islas de Astro (cero JavaScript por defecto, componentes interactivos opcionales) y admite contenido MDX.

## De un vistazo

| Aspecto                    | Htmlpress                                                | Starlight                                                                       |
| -------------------------- | -------------------------------------------------------- | ------------------------------------------------------------------------------- |
| Lenguaje / runtime         | Rust (binario único, sin runtime)                        | TypeScript / Node 18+                                                           |
| Framework de UI            | Ninguno (HTML + CSS plano, web components `htmlpress-*`) | Componentes de Astro (HTML primero), islas opcionales de React/Vue/Svelte/Solid |
| Herramienta de compilación | Binario de htmlpress                                     | Astro (Vite por debajo)                                                         |
| Formato de contenido       | Páginas HTML y Markdown                                  | Markdown + MDX + MDoc                                                           |
| Licencia                   | MIT, autoalojado                                         | MIT, autoalojado                                                                |
| Modelo de salida           | Estático prerenderizado                                  | Estático prerenderizado (con SSR posible mediante adaptadores)                  |

## Arquitectura

htmlpress es un único binario de Rust que se instala desde npm (`gethtmlpress`), PyPI o crates.io. Envuelve cada página HTML en un layout con una navegación y un tema; no hay bundler, ni framework de UI, ni API de plugins. Cada archivo integrado (el layout, los estilos, los scripts y cada componente) se puede escapar: un archivo en la misma ruta bajo `.htmlpress/` lo reemplaza.

Las páginas de htmlpress se renderizan a HTML en tiempo de compilación y no hidratan nada: los componentes interactivos `htmlpress-*` son elementos personalizados con un pequeño script vanilla cada uno, enlazado solo en las páginas que los usan.

Starlight usa el modelo de islas de Astro: las páginas se renderizan a HTML en tiempo de compilación con cero JavaScript por defecto. Los componentes interactivos son "islas" explícitas que se hidratan bajo demanda. El tema por defecto de Starlight se compone sobre todo de componentes de Astro (sin JS en el cliente); recurrir a React/Vue/Svelte es opcional. El modelo de componentes de Astro es su propia sintaxis `.astro` (HTML + frontmatter en JS, analizado estáticamente).

En htmlpress la disposición del contenido no tiene restricciones: escanea por glob (`include`/`exclude` en `htmlpress.yaml`, todos los archivos `.html` por defecto), y la URL de una página sigue su ruta de archivo bajo la base del glob, así que `docs/**/*.html` sirve `docs/guide.html` en `/guide/`. No hace falta una carpeta `docs/`. La navegación se construye a partir de las carpetas y del `<meta name="order">` de cada página; el `index.html` de una carpeta da nombre a su grupo. Starlight exige el contenido en `src/content/docs/` (el directorio de content collections de Astro), con rutas derivadas de las rutas de archivo bajo esa raíz.

## Superficie de contenido

Starlight acepta Markdown + MDX con frontmatter y, además, MDoc (Markdoc) para contenido estructurado y validado con etiquetas personalizadas. Los componentes en archivos `.mdx` son componentes de Astro por defecto; los componentes de frameworks (React, etc.) necesitan directivas `client:*` explícitas para hidratarse.

Las páginas de htmlpress son HTML semántico plano, al que el tema da estilo a partir de los propios elementos. Los bloques más ricos son elementos personalizados `htmlpress-*` (`htmlpress-callout`, `htmlpress-tabs`, `htmlpress-filetree`, `htmlpress-cards`, …), cuyo CSS y JS se enlazan solo en las páginas que usan la etiqueta. Un proyecto añade su propia etiqueta con `.htmlpress/components/<name>/<name>.html`, que reemplaza la etiqueta en tiempo de compilación.

htmlpress no tiene frontmatter: los metadatos de una página son su propio `<head>` — `<title>`, `<meta name="description">`, `<meta name="order">`, `<meta name="layout">` y `<meta name="image">`; las demás etiquetas de `<head>` se conservan. Starlight usa frontmatter: `title`, `description`, `sidebar`, `tableOfContents`, `editUrl`, `lastUpdated`.

## Matriz de funciones

| Capacidad                   | Htmlpress                                                               | Starlight                                            |
| --------------------------- | ----------------------------------------------------------------------- | ---------------------------------------------------- |
| Versionado                  | Parcial (una sección o un despliegue por versión)                       | No (plugins de la comunidad)                         |
| Internacionalización (i18n) | Sí (traducciones, selector de idioma, 7 idiomas de interfaz incluidos)  | Sí (integrada)                                       |
| Búsqueda                    | Sí (integrada, en el cliente)                                           | Sí (Pagefind, integrada)                             |
| Cero JS por defecto         | No (pequeños scripts vanilla, sin framework)                            | Sí (arquitectura de islas)                           |
| Blog                        | No                                                                      | No (usa las content collections de Astro)            |
| Registro de cambios         | No                                                                      | No                                                   |
| Sitemap                     | Sí (con `site` definido)                                                | Sí                                                   |
| RSS                         | No                                                                      | Mediante la integración `@astrojs/rss`               |
| Temas                       | Escapes en `.htmlpress/` + tokens `--htmlpress-*`                       | Overrides de componentes mediante slots de Starlight |
| Plugins                     | No (componentes del proyecto en `.htmlpress/components/`)               | Integraciones de Astro + plugins de Starlight        |
| Rutas personalizadas        | Cualquier archivo `.html`; layouts adicionales en `.htmlpress/layouts/` | Páginas de Astro junto al contenido de Starlight     |

## Salida y despliegue

Ambos producen un directorio de HTML estático + recursos. Starlight emite en `dist/` por defecto; htmlpress emite en `.htmlpress/build/`.

htmlpress escribe cada página como HTML estático en `.htmlpress/build/`, junto con `robots.txt`, un `sitemap.xml` cuando `site` está definido, una copia en Markdown de cada página, `llms.txt` y las skills para agentes en `.well-known/agent-skills/`. La clave `base` sirve el sitio bajo una subruta. Consulta [Despliegue](/es/deployment/) para ver guías por hosting.

Starlight hereda el sistema de adaptadores de Astro, que admite SSR en Cloudflare, Netlify, Vercel, Node y Deno. htmlpress no tiene modo servidor: la compilación es solo estática.

## Ver también

- [Redacción](/es/authoring/) — la superficie HTML de htmlpress.
- [Personalización](/es/customization/) — las claves de configuración y los escapes de htmlpress.
- [Comparativa](/es/comparison/) — volver al índice.