How to Build and Publish a Documentation Site With GitBook
GitBook is a block-based documentation editor that publishes to a hosted site with search, versioning, and a custom domain. A first site takes about 30 minutes: create an organization, create a space, add pages in the sidebar, then publish and point a domain at it.
The interesting question is not how to start. It is when the hosted editor beats a Markdown repo in a static site generator, because that trade decides whether you will still be using it in a year.
What Is GitBook and How Is It Different From Docusaurus?
GitBook is a hosted docs platform: editors write in the browser, and the site publishes automatically. Docusaurus is a React static site generator where docs are Markdown files in a repo.
The difference is ownership of the toolchain. With GitBook you cede control of the rendering and hosting; in exchange, a non-engineer can fix a typo without a pull request. With Docusaurus you own everything and every change goes through code review.
How Do I Create a Space and Structure Pages?
- Sign up and create an organization — the free plan allows one.
- Click New space → Documentation. Pick a template or blank.
- Add pages from the sidebar: each page is a block editor canvas, not a Markdown file.
- Group pages into collections to get a collapsible nav. More than three top-level groups makes the sidebar hard to scan.
- Set the space to Published and choose a subdomain.
Order matters. Editorial order in the sidebar is the site navigation, so a docs site with the getting-started page buried at position seven loses readers on arrival.
How Does Git Sync Work?
GitBook supports two-way sync with GitHub and GitLab. You connect a repo, pick a branch, and it mirrors page-per-file Markdown in both directions.
Be careful: two-way sync means a mistaken edit in GitBook pushes to main. Set the sync to one-way (read from Git, write to GitBook) if engineers own the docs. Use two-way only when writers and engineers both edit regularly, and expect merge conflicts on the same page.
What Are the Free Plan’s Real Limits?
| Limit | Free | Pro |
|---|---|---|
| Published docs sites | 1 | Unlimited |
| Custom domain | No | Yes |
| Team members | 5 | Per seat pricing |
| Git sync | 1 repo | Unlimited |
| Versioning | No | Yes |
Pro starts at $12 per user per month billed annually. Versioning is the limit that pushes real products off the free plan — shipping docs for v2 next to v1 requires it.
How Do I Put It on My Own Domain?
Upgrade to Pro first; custom domains are not on free. Then open Settings → Domain, enter your domain, and add the CNAME record GitBook shows at your DNS host. TLS is issued automatically.
Use a subdomain like docs.yourdomain.com rather than a path on the main site. Path hosting requires reverse proxy configuration on your end, and GitBook does not support it natively.
Where Does GitBook Fall Short?
Search quality is the recurring complaint. It is good for exact phrases and weak for intent-based queries, so docs with overlapping terminology send readers to the wrong page. You also cannot customize the rendering layer much — the block editor outputs what it outputs.
API documentation is decent if you use its OpenAPI import, but teams with heavily customized interactive API docs usually end up back in a generator that lets them mount a custom React component.
Who Should Use It
Use GitBook when a product marketer and a support lead need to edit docs daily and no engineer wants to babysit a build pipeline. Skip it when docs are code-adjacent — SDK references, generated API tables — where a static generator with a custom component is cheaper and more flexible.
Quick Summary
- GitBook publishes a hosted docs site from a block editor in about 30 minutes.
- Free plan allows one site, five members, and no custom domain.
- Pro at $12/user/month unlocks custom domains, versioning and unlimited git sync.
- Two-way Git sync can push accidental edits to main — choose one-way if engineers own the docs.
- Weak spot is intent-based search; ideal for non-technical editors.
