GitBook vs Htmlpress

GitBook 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

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

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 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 — htmlpress' HTML surface.
• Customization — htmlpress' config keys and escapes.
• Comparison — back to the index.