Starlight vs Htmlpress
Starlight 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 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 — la superficie HTML de htmlpress.
- Personalización — las claves de configuración y los escapes de htmlpress.
- Comparativa — volver al índice.
Hecho con ❤ y Htmlpress