# GitBook vs Htmlpress

> SaaS alojado con editor de bloques y Git Sync frente a HTML estático autoalojado basado en archivos.

[GitBook](https://www.gitbook.com) es una plataforma comercial de documentación alojada. La redacción se hace en un editor de bloques en el navegador (al estilo de Notion), el contenido vive en la base de datos de GitBook y se publica en sitios alojados por GitBook bajo `gitbook.io` o un dominio propio. La función Git Sync puede reflejar esa base de datos hacia y desde un repositorio de GitHub/GitLab como Markdown, pero la fuente de verdad es GitBook, no el repositorio.

El antiguo generador estático de código abierto `gitbook-cli` quedó obsoleto en 2018 y no tiene relación con el producto actual; esta página trata de la plataforma alojada actual.

## De un vistazo

| Aspecto                    | Htmlpress                                                | GitBook                                                                         |
| -------------------------- | -------------------------------------------------------- | ------------------------------------------------------------------------------- |
| Lenguaje / runtime         | Rust (binario único, sin runtime)                        | SaaS alojado (sin runtime local)                                                |
| Framework de UI            | Ninguno (HTML + CSS plano, web components `htmlpress-*`) | Propietario (renderizado por GitBook)                                           |
| Herramienta de compilación | Binario de htmlpress                                     | Ninguna (sin compilación por parte del usuario)                                 |
| Formato de contenido       | Páginas HTML y Markdown                                  | Modelo de bloques en el editor; Markdown con sabor GitBook vía Git              |
| Licencia                   | MIT, autoalojado                                         | Propietaria; plan gratuito + planes de pago; autoalojamiento solo en Enterprise |
| Modelo de salida           | Estático prerenderizado                                  | Alojado en la infraestructura de GitBook                                        |

## 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 son archivos de tu repositorio y se prerenderizan a HTML estático en tiempo de compilación.

GitBook es un SaaS multiinquilino. El contenido se redacta en un editor WYSIWYG basado en bloques: cada párrafo, encabezado, bloque de código, hint o embed es un bloque tipado almacenado en la base de datos de GitBook. El runtime es el propio de GitBook: no hay paso de compilación que ejecute el usuario ni sitio estático que despliegue. El hosting, la indexación para búsqueda, la CDN, las redirecciones y la analítica los gestiona la plataforma.

Git Sync es una integración opcional que asocia un espacio de GitBook a una rama de un repositorio de GitHub o GitLab. El contenido va y viene entre el editor y un directorio de archivos `.md` escritos en el Markdown extendido de GitBook (hints con `{% hint %}`, pestañas, content refs, bloques de OpenAPI, etc.). Es bidireccional: las ediciones en el editor envían commits al repositorio, y los commits enviados a la rama actualizan el editor. El repositorio es un espejo, no una fuente: el esquema de GitBook es el modelo canónico.

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. El contenido de GitBook se organiza en una jerarquía fijada por el producto — **Organizations → Collections → Spaces → Pages** — con URLs del sitio derivadas de ese árbol. El espejo de Git Sync refleja esta jerarquía como directorios anidados.

## Superficie de contenido

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.

La superficie de GitBook es la paleta de bloques del editor: párrafos, encabezados, listas, tablas, hints (info/warning/danger/success), pestañas, bloques desplegables, bloques de código con grupos de pestañas, archivos, imágenes, dibujos, matemáticas (KaTeX), embeds (Figma, Loom, etc.), bloques de métodos de API, referencias OpenAPI y content refs (transclusión entre espacios). Los componentes personalizados no son extensibles por el usuario: el conjunto de bloques es el que trae GitBook. El sabor de Markdown de Git Sync codifica los bloques que no están en CommonMark mediante etiquetas al estilo Liquid, como `{% hint style="info" %}…{% endhint %}` y `{% tabs %}…{% endtabs %}`.

OpenAPI es una entrada de primera clase: GitBook puede importar una especificación OpenAPI y renderizar a partir de ella páginas de referencia de API, lo que se acerca más a la superficie de Mintlify que a la de htmlpress.

## Matriz de funciones

| Capacidad                       | Htmlpress                                                               | GitBook                                                                                             |
| ------------------------------- | ----------------------------------------------------------------------- | --------------------------------------------------------------------------------------------------- |
| Versionado                      | Parcial (una sección o un despliegue por versión)                       | Sí (variantes de espacio / grupos de versiones)                                                     |
| Internacionalización (i18n)     | Sí (traducciones, selector de idioma, 7 idiomas de interfaz incluidos)  | Sí (variantes por idioma de un espacio)                                                             |
| Búsqueda                        | Sí (integrada, en el cliente)                                           | Sí (alojada, con preguntas y respuestas de GitBook AI / "Lens" en planes de pago)                   |
| Blog                            | No                                                                      | No                                                                                                  |
| Registro de cambios             | No                                                                      | No (los Change Requests son un flujo editorial, no una sección publicada)                           |
| Sitemap                         | Sí (con `site` definido)                                                | Sí (generado por la plataforma)                                                                     |
| RSS                             | No                                                                      | No                                                                                                  |
| Temas                           | Escapes en `.htmlpress/` + tokens `--htmlpress-*`                       | Personalización desde los ajustes del sitio (colores, fuentes, layout); sin overrides de plantillas |
| Plugins                         | No (componentes del proyecto en `.htmlpress/components/`)               | Integraciones propietarias (Intercom, Segment, GA, etc.)                                            |
| Rutas personalizadas            | Cualquier archivo `.html`; layouts adicionales en `.htmlpress/layouts/` | No (las URLs siguen la jerarquía espacio → página)                                                  |
| Referencia de API desde OpenAPI | No                                                                      | Sí (integrada)                                                                                      |
| Toolchain independiente         | Un único binario de Rust (npm, PyPI o crates.io)                        | Ninguna por parte del usuario; SaaS                                                                 |

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

GitBook no emite un artefacto desplegable. El sitio se aloja en `<space>.gitbook.io` por defecto, o se asocia a un dominio propio mediante DNS. La CDN, TLS, las redirecciones, el control de acceso y la analítica se configuran en el panel de GitBook. El autoalojamiento está restringido al plan Enterprise y no está disponible en los planes estándar. Lo más parecido a "tu contenido" es lo que el espejo de Git Sync escribe en el repositorio conectado, que es solo contenido, no un sitio compilable.

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