GitBook vs Htmlpress
GitBook 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 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 — 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