# GitBook vs Htmlpress

> Hosted SaaS with a block editor and Git Sync vs file-based, self-hosted static HTML.

[GitBook](https://www.gitbook.com) is a commercial hosted documentation platform. Authoring happens in a browser-based block editor (Notion-flavored), content lives in GitBook's database, and publishing is to GitBook-hosted sites under `gitbook.io` or a custom domain. A Git Sync feature can mirror that database to and from a GitHub/GitLab repository as Markdown, but the source of truth is GitBook itself, not the repo.

The older open-source `gitbook-cli` static generator was deprecated in 2018 and is unrelated to today's product; this page covers the current hosted platform.

## At a glance

| Axis               | Htmlpress                                             | GitBook                                                           |
| ------------------ | ----------------------------------------------------- | ----------------------------------------------------------------- |
| Language / runtime | Rust (single binary, no runtime)                      | Hosted SaaS (no local runtime)                                    |
| UI framework       | None (plain HTML + CSS, `htmlpress-*` web components) | Proprietary (rendered by GitBook)                                 |
| Build tool         | htmlpress binary                                      | None (no user-side build)                                         |
| Content format     | HTML and Markdown pages                               | Block model in editor; GitBook-flavored Markdown via Git          |
| License            | MIT, self-hosted                                      | Proprietary; free tier + paid plans; self-host on Enterprise only |
| Output model       | Prerendered static                                    | Hosted on GitBook infrastructure                                  |

## Architecture

htmlpress is one Rust binary, installed from npm (`gethtmlpress`), PyPI or crates.io. It wraps each HTML page in one layout with a navigation and a theme; there is no bundler, no UI framework and no plugin API. Every built-in file — the layout, the styles, the scripts and each component — can be escaped: a file at the same path under `.htmlpress/` replaces it. Pages are files in your repository and are prerendered to static HTML at build time.

GitBook is a multi-tenant SaaS. Content is authored in a block-based WYSIWYG editor: each paragraph, heading, code block, hint, or embed is a typed block stored in GitBook's database. The runtime is GitBook's own — there is no build step the user runs and no static site they deploy. Hosting, search indexing, CDN, redirects, and analytics are all managed by the platform.

Git Sync is an optional integration that maps a GitBook space to a branch of a GitHub or GitLab repository. Content round-trips between the editor and a directory of `.md` files written in GitBook's extended Markdown flavor (hints with `{% hint %}`, tabs, content refs, OpenAPI blocks, etc.). It is two-way: edits in the editor push commits to the repo; commits pushed to the branch update the editor. The repo is a mirror, not a source — GitBook's schema is the canonical model.

Content layout is unconstrained on the htmlpress side: it scans by glob (`include`/`exclude` in `htmlpress.yaml`, every `.html` file by default), and a page's URL follows its file path below the glob's base, so `docs/**/*.html` serves `docs/guide.html` at `/guide/`. There's no required `docs/` folder. The navigation is built from the folders and each page's `<meta name="order">`; a folder's `index.html` names its group. GitBook content is organized into a hierarchy fixed by the product — **Organizations → Collections → Spaces → Pages** — with site URLs derived from that tree. The Git Sync mirror reflects this hierarchy as nested directories.

## Content surface

htmlpress pages are plain semantic HTML, styled by the theme from the elements themselves. Richer blocks are `htmlpress-*` custom elements (`htmlpress-callout`, `htmlpress-tabs`, `htmlpress-filetree`, `htmlpress-cards`, …), whose CSS and JS are linked only on pages that use the tag. A project adds its own tag with `.htmlpress/components/<name>/<name>.html`, which replaces the tag at build time. htmlpress has no frontmatter: a page's metadata is its own `<head>` — `<title>`, `<meta name="description">`, `<meta name="order">`, `<meta name="layout">` and `<meta name="image">`; other `<head>` tags are kept.

GitBook's surface is the editor's block palette: paragraphs, headings, lists, tables, hints (info/warning/danger/success), tabs, expandable blocks, code blocks with tab groups, files, images, drawings, math (KaTeX), embeds (Figma, Loom, etc.), API method blocks, OpenAPI references, and content refs (transclusion across spaces). Custom components are not user-extensible — the block set is what GitBook ships. The Git Sync flavor of Markdown encodes blocks not in CommonMark via Liquid-like tags such as `{% hint style="info" %}…{% endhint %}` and `{% tabs %}…{% endtabs %}`.

OpenAPI is a first-class input: GitBook can import an OpenAPI spec and render API reference pages from it, which is closer to Mintlify's surface than to htmlpress'.

## Feature matrix

| Capability                  | Htmlpress                                                   | GitBook                                                                            |
| --------------------------- | ----------------------------------------------------------- | ---------------------------------------------------------------------------------- |
| Versioning                  | Partial (a section or a deploy per version)                 | Yes (space variants / version groups)                                              |
| Internationalization (i18n) | Yes (translations, language picker, 7 bundled UI languages) | Yes (per-language variants of a space)                                             |
| Search                      | Yes (built-in, client-side)                                 | Yes (hosted, with GitBook AI / "Lens" Q\&A on paid tiers)                          |
| Blog                        | No                                                          | No                                                                                 |
| Changelog                   | No                                                          | No (Change Requests are an editorial workflow, not a published section)            |
| Sitemap                     | Yes (with `site` set)                                       | Yes (generated by the platform)                                                    |
| RSS                         | No                                                          | No                                                                                 |
| Themes                      | Escapes in `.htmlpress/` + `--htmlpress-*` tokens           | Customization through site settings (colors, fonts, layout); no template overrides |
| Plugins                     | No (project components in `.htmlpress/components/`)         | Proprietary integrations (Intercom, Segment, GA, etc.)                             |
| Custom routes               | Any `.html` file; extra layouts in `.htmlpress/layouts/`    | No (URLs follow the space → page hierarchy)                                        |
| API reference from OpenAPI  | No                                                          | Yes (built-in)                                                                     |
| Standalone toolchain        | Single Rust binary (npm, PyPI or crates.io)                 | None on user side; SaaS                                                            |

## Output & deployment

htmlpress writes every page to static HTML in `.htmlpress/build/`, along with `robots.txt`, a `sitemap.xml` when `site` is set, a Markdown copy of each page, `llms.txt` and the agent skills under `.well-known/agent-skills/`. The `base` key serves the site under a sub-path. See [Deployment](/deployment/) for host guides.

GitBook does not emit a deployable artifact. The site is hosted at `<space>.gitbook.io` by default, or attached to a custom domain via DNS. CDN, TLS, redirects, access control, and analytics are configured in the GitBook dashboard. Self-hosting is restricted to the Enterprise tier and is not available on the standard plans. The artifact closest to "your content" is whatever the Git Sync mirror writes into the connected repository, which is content only — not a buildable site.

## See also

- [Authoring](/authoring/) — htmlpress' HTML surface.
- [Customization](/customization/) — htmlpress' config keys and escapes.
- [Comparison](/comparison/) — back to the index.