# Docusaurus vs Htmlpress

> Comparativa técnica lado a lado de un framework de documentación con React + MDX y un generador de sitios en HTML simple.

[Docusaurus](https://docusaurus.io) es un framework de documentación de código abierto mantenido por Meta. Renderiza contenido React + MDX mediante un pipeline de compilación basado en Webpack, incluye versionado e internacionalización de primera clase y cuenta con un gran ecosistema de plugins.

## De un vistazo

| Aspecto                    | Htmlpress                                                  | Docusaurus              |
| -------------------------- | ---------------------------------------------------------- | ----------------------- |
| Lenguaje / runtime         | Rust (un único binario, sin runtime)                       | TypeScript / Node 18+   |
| Framework de UI            | Ninguno (HTML + CSS simples, web components `htmlpress-*`) | React 18                |
| Herramienta de compilación | binario htmlpress                                          | Webpack                 |
| Formato de contenido       | Páginas HTML y Markdown                                    | Markdown + MDX          |
| Licencia                   | MIT, autoalojado                                           | MIT, autoalojado        |
| Modelo de salida           | Estático prerenderizado                                    | Estático prerenderizado |

## Arquitectura

htmlpress es un único binario de Rust, instalado 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.

Docusaurus está construido sobre Webpack. El runtime es React Router + un núcleo de Docusaurus que gestiona los temas, los plugins y las fuentes de contenido. Los plugins son de primera clase: cada función integrada (docs, blog, páginas, búsqueda) es en sí misma un plugin, y terceros amplían el sistema de la misma manera.

En htmlpress la estructura del contenido es libre: 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 se exige 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. El plugin de docs de Docusaurus espera un directorio `docs/` (configurable mediante `path`, pero basado en carpetas en lugar de globs).

## Superficie de contenido

Docusaurus acepta Markdown y MDX con frontmatter y te permite incrustar componentes de React dentro de archivos `.md`/`.mdx`. htmlpress acepta páginas `.html`, un documento completo o un fragmento suelto, y páginas `.md` con frontmatter, cuyas directivas `:::nombre` son sus componentes; ni MDX ni React.

Las páginas de htmlpress son HTML semántico simple, 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. Docusaurus usa componentes MDX más una extensión `admonition` para los callouts.

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. Docusaurus usa `id`, `slug`, `sidebar_position`, `sidebar_label` y `tags`.

## Matriz de funciones

| Capacidad                   | Htmlpress                                                               | Docusaurus                                |
| --------------------------- | ----------------------------------------------------------------------- | ----------------------------------------- |
| Versionado                  | Parcial (una sección o un despliegue por versión)                       | Sí (integrado)                            |
| Internacionalización (i18n) | Sí (traducciones, selector de idioma, 7 idiomas de interfaz incluidos)  | Sí (integrada)                            |
| Búsqueda                    | Sí (integrada, en el cliente)                                           | Integración con Algolia DocSearch         |
| Blog                        | No                                                                      | Sí (plugin integrado)                     |
| Changelog                   | No                                                                      | No (plugins de la comunidad)              |
| Sitemap                     | Sí (con `site` definido)                                                | Sí                                        |
| RSS                         | No                                                                      | Sí (para el plugin de blog)               |
| Temas                       | Escapes en `.htmlpress/` + tokens `--htmlpress-*`                       | Paquetes de temas (`@docusaurus/theme-*`) |
| Plugins                     | No (componentes del proyecto en `.htmlpress/components/`)               | API de plugins de primera clase           |
| Rutas personalizadas        | Cualquier archivo `.html`; layouts adicionales en `.htmlpress/layouts/` | Rutas definidas por plugins               |

## 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 de agente en `.well-known/agent-skills/`. La clave `base` sirve el sitio bajo una subruta. Consulta [Despliegue](/es/deployment/) para ver las guías de hosts.

Docusaurus también prerenderiza a HTML estático, con salida en `build/`. La salida estática funciona en cualquiera de los mismos hosts (GitHub Pages, Cloudflare, Vercel, Netlify, hosting estático). La i18n integrada de Docusaurus genera árboles de salida separados por idioma.

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