Nextra vs Htmlpress

Nextra es un framework de documentación para Next.js con una arquitectura de paquetes de temas. Nació sobre el Pages Router y ha evolucionado para admitir también el App Router. Los sitios de documentación eligen un tema (nextra-theme-docs para docs, nextra-theme-blog para blogs) y lo configuran.

De un vistazo

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. Una herramienta, un archivo de configuración opcional y el contenido en archivos .html.

Nextra es una capa sobre una aplicación Next.js existente. La configuración consiste en instalar nextra y un paquete de tema, conectarlos en next.config.js y definir la navegación en un archivo _meta.json (Pages Router) o meta.js (App Router) por directorio. El paquete de tema controla toda la UI; la personalización se hace mediante los hooks documentados del tema.

nextra-theme-docs es el tema de documentación que usan Vercel, SWR, Turbo y muchos otros. Es estable, está mantenido y está completo para casos de uso de documentación.

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. Nextra lee el contenido de pages/ (Pages Router) o content/ (App Router), con rutas determinadas por las rutas de archivo y por los archivos _meta.json que las acompañan.

Superficie de contenido

Nextra acepta Markdown + MDX con frontmatter y componentes de React incrustados. Admite MDX remoto mediante next-mdx-remote, KaTeX/Mermaid mediante plugins y optimización de imágenes mediante el componente <Image> de Next.

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. Los diagramas Mermaid vienen integrados, desde un bloque de código language-mermaid.

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. Nextra usa frontmatter (title, description, searchable, hide_title) más un _meta.json por directorio para la navegación; htmlpress no tiene archivo de navegación.

Matriz de funciones

Salida y despliegue

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.

Nextra hereda los modos de salida de Next.js. La configuración más habitual para documentación es la exportación estática completa (output: 'export'), que produce un directorio estático desplegable en cualquier parte. Las configuraciones con SSR apuntan a Vercel o a hostings de Node.

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.