# Nextra vs Htmlpress

> Un generador de sitios independiente en HTML plano frente a Next.js con el modelo de paquetes de temas.

[Nextra](https://nextra.site) 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

| Aspecto                    | Htmlpress                                                | Nextra                            |
| -------------------------- | -------------------------------------------------------- | --------------------------------- |
| Lenguaje / runtime         | Rust (binario único, sin runtime)                        | TypeScript / Node 18+             |
| Framework de UI            | Ninguno (HTML + CSS plano, web components `htmlpress-*`) | React 18/19 (Next.js)             |
| Herramienta de compilación | Binario de htmlpress                                     | Next.js (Turbopack/Webpack)       |
| Formato de contenido       | Páginas HTML y Markdown                                  | Markdown + MDX                    |
| Licencia                   | MIT, autoalojado                                         | MIT, autoalojado                  |
| Modelo de salida           | Estático prerenderizado                                  | Estático o SSR (modos de Next.js) |

## 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

| Capacidad                   | Htmlpress                                                               | Nextra                                                                |
| --------------------------- | ----------------------------------------------------------------------- | --------------------------------------------------------------------- |
| Versionado                  | Parcial (una sección o un despliegue por versión)                       | No (soluciones de la comunidad)                                       |
| Internacionalización (i18n) | Sí (traducciones, selector de idioma, 7 idiomas de interfaz incluidos)  | Sí (mediante i18n de Next + hooks de Nextra)                          |
| Búsqueda                    | Sí (integrada, en el cliente)                                           | Sí (FlexSearch integrado, Algolia/Pagefind opcional)                  |
| Blog                        | No                                                                      | Sí (`nextra-theme-blog`)                                              |
| Registro de cambios         | No                                                                      | No (plugins de la comunidad)                                          |
| Sitemap                     | Sí (con `site` definido)                                                | Mediante `sitemap.ts` de Next.js                                      |
| RSS                         | No                                                                      | Sí (tema de blog); mediante rutas de Next para docs                   |
| Temas                       | Escapes en `.htmlpress/` + tokens `--htmlpress-*`                       | Paquetes de temas; personalización mediante la configuración del tema |
| Rutas personalizadas        | Cualquier archivo `.html`; layouts adicionales en `.htmlpress/layouts/` | Cualquier página/ruta de Next                                         |
| CLI independiente           | Sí (`htmlpress build`)                                                  | No (comandos de Next.js)                                              |

## 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](/es/deployment/) 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](/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.