GitBook's open source renderer: self-hosting the frontend of a published doc site

What the GitBook open source repository actually contains

The README is direct about scope: "This repository contains the open source code used to render GitBook's published content." That sentence rules out most of what people expect from the GitBook name. There is no editor here, no content API, no hosting control panel. What you get is the frontend that turns an already published GitBook space into HTML in a browser.

The audience follows from that. If your team writes in GitBook and is happy with the hosted output, this repository has nothing for you. It matters to engineers who want to change how published content looks, or who want to embed documentation inside their own application rather than link out to a gitbook.io URL. The README lists exactly those two reasons on the pro side of self-hosting.

The repository is a TypeScript monorepo, built on Next.js according to the contributing section, with packages under packages/ and a Bun lockfile at the root. The root package.json marks the workspace private and lists Turbo among the dev dependencies, which is consistent with a multi-package layout rather than a single deployable application. Last push was on 2026-09-18, three days before this article, so the codebase is moving, but the README also states plainly that forked and self-hosted instances get no guarantee of support, maintenance, or updates.

How the local renderer fetches and renders a published space

The mechanism is unusual and worth understanding before you install anything. You do not point the dev server at a local folder of Markdown. You point it at a live published GitBook site, and the renderer fetches that content and renders it locally.

The README gives the URL pattern for this. A published space is opened through your local instance by prefixing it with http://localhost:3000/url, and the two examples given are gitbook.com/docs and open-source.gitbook.io/midjourney. So the running dev server acts as a rendering proxy: the source of truth stays on GitBook's side, and your local code decides how it appears.

That design explains the deployment warning. If the renderer depends on the shape of content served by the platform, then platform changes can break a fork. The README says self-hosting puts "the responsibility of maintaining and merging future updates on you." It is not a hypothetical risk; it is the stated consequence of the architecture.

It also explains why the repository ships translation files under packages/gitbook/src/intl/translations, which the README invites contributions to. UI strings live with the renderer because the renderer owns the interface around the content, not the content itself.

Installing GitBook locally and opening your first published space

The README states two prerequisites: Node.js version 22.3 or higher, and Bun version 1.2.15 or higher, with the note that the project uses a text-based lockfile unsupported below that Bun version. The package.json engines field pins node to ^22.3.0, and packageManager is set to [email protected], so the two sources agree on the floor.

Start by cloning the repository:

git clone https://github.com/gitbookIO/gitbook.git

The README's setup step 1 adds a condition that is easy to skim past: clone into a public GitHub repository. If you plan to distribute the code, the README says to keep the source public to comply with GNU GPLv3, and to clone into a private repository you need a commercial license.

Next, switch to the Node version the project expects. The repository has an .nvmrc file, and the README says running nvm use will change your local version to the correct one.

nvm use

Install dependencies with Bun, then start the development server:

bun install
bun dev

The root package.json shows dev as turbo run dev with a concurrency of 20, so this starts the workspace tasks rather than a single process. Once it is up, open a published GitBook space through the local URL prefix:

# open in your browser
http://localhost:3000/url/gitbook.com/docs

What you should see is that published site rendered by your local code. The README states that any published GitBook site can be accessed this way and that code changes are reflected in the browser. The repository also defines typecheck, lint, format and unit scripts through Turbo, so a full local run is not limited to the dev server.

The self-hosting trade-off the README does not soften

The deployment section carries a warning block, and it is the most important paragraph in the file. It says self-hosting is possible but not recommended unless you are certain it fits your need, that maintaining and merging future updates becomes your responsibility, and that support, maintenance and updates for forked and self-hosted instances are not guaranteed.

The con side is spelled out too: you become responsible for the reliability of your published site and for keeping the renderer current with platform changes. That is a real operational burden, not a disclaimer. A rendering layer that follows a hosted platform will drift whenever the platform changes what it serves.

There is a second limitation that has nothing to do with operations. Because the renderer consumes published GitBook content, it is the wrong tool if you want to author in Markdown in your own repository and build a site from those files. There is no build-from-source-content path described in the README. For that workflow you want a static site generator, not this.

A third constraint sits in the fonts section: GitBook Open uses fontawesome, and for self-hosting and local development, for licensing reasons, only the free version's icons should be used. If your design depends on Pro icons, that is a licensing boundary, not a configuration option.

Docusaurus or GitBook: different places for the source of truth

The comparison people reach for is Docusaurus, and the difference is structural rather than cosmetic. Docusaurus builds a site from Markdown files that live in your repository. The content and the renderer ship together, and deploying means running a build over files you control.

GitbookIO/gitbook inverts that. The content lives in a published GitBook space, and the renderer fetches it. You control presentation and embedding; GitBook controls the content and the platform that serves it. That is why the README can offer custom look and feel as a benefit while simultaneously warning that self-hosters must merge platform updates.

Which one is right depends on where you want your writing to live. If your docs are Markdown in git and reviewed through pull requests, Docusaurus matches that model without a hosted dependency. If your writers work in GitBook and you only need to change the frontend or embed the result, this repository is the piece that fits, and Docusaurus would mean migrating the content first.

One practical note for either path: the README says all pull requests against this repository are tested against visual and performance testing to prevent regressions. That tells you the upstream project guards its rendering output carefully, which is also a hint about how sensitive the renderer is to change.

Licence, distribution and what upgrading a fork costs

The repository is distributed under GNU GPLv3. The README states the consequence for distribution: if you plan to distribute the code, you must make the source code public to comply with the licence, and cloning into a private repository requires a commercial license, with a link to the pricing page. That is a distribution question, not a usage question, and it is the first thing to settle with your legal team before you build a product around a fork.

Upgrade cost is stated rather than estimated. The README says self-hosting puts the responsibility of maintaining and merging future updates on you, and that forked and self-hosted instances get no guaranteed support or updates. There is no documented rollback path in the README, and no compatibility matrix telling you which renderer version matches which platform behaviour. If you fork, plan to track the main branch yourself.

The repository does ship release tooling that hints at how upstream manages versions: a .changeset directory, a changeset script, and a changeset-version script that runs changeset version, formats, and updates dependencies. Recent releases are scoped to individual packages such as @gitbook/react-openapi and @gitbook/react-math rather than the repository as a whole, so version drift between packages is something a fork has to absorb.

Editorial conclusion

Adopt this repository if you need to change how published GitBook content looks or how it embeds in your own application, and you accept that the README places maintenance and merge work on you. Do not adopt it as a replacement for the GitBook editor or as a general static site generator; the repository contains only the rendering portion. Before committing, confirm which Node and Bun versions your environment can run, and confirm with GitBook whether your distribution plan needs the commercial license the README points to for private repositories. Then open a published space through http://localhost:3000/url and see whether the renderer output matches what you expect.

Frequently asked questions

Official sources

1. GitbookIO/gitbook on GitHub
2. License: GPL-3.0
3. Project website
4. README
5. Releases