Learn how to use GitBook to create public or private documentation for your project — and how to add customizations, check analytics, and more
Last updated
Was this helpful?
Was this helpful?
In this guide, we’ll walk you through the process of publishing documentation in GitBook. You can do this by creating a docs site in your GitBook organization, then linking content from your spaces.
It’s a super-simple process that lets you control all the aspects of your published documentation in one place — including customization options, audience settings, and more. And best of all, all you need to get started is a space in GitBook with some content!
Ready to publish your docs? Let’s start by creating a docs site and trying some customization options. There are a couple of different ways to do this, but they all ultimately have the same outcome.
First, You can hit the plus + icon next to the Docs sites section header in the sidebar to open the site creation flow. This will guide you through the process of creating and naming your site so you can add your content or just see what a published site will look.
If you haven’t already, now is a good time to name your docs site so it’s easy to find later — you can do that at the top of the site’s main dashboard. We’d recommend something descriptive to make it identifiable with a glance later.
You can link more than one space to a single docs site if you like, and there are two ways to do this — with site sections and site variants.
[screenshot showing site sections]
[screenshot showing variants]
To start customizing your docs site, open its dashboard and click Customize below the title. By default, you’ll begin editing the settings for your entire site — so if you’ve linked multiple spaces to a single site, these changes will apply to all of them.
You can also select individual linked spaces if you want to control settings at a more granular level. For example, if you’ve linked spaces that refer to different products or releases, you may want to customize each one in a different way to match individual brands.
All the changes you make in the customization menu will appear in the preview on the right-hand side, so you can see how your choices look in context.
It’s worth noting that our advanced customization options are only available if you have a Premium or Ultimate site, so if you want the full suite of controls you may need to upgrade.
In Page Options you can select one of our preset options, or manually toggle different controls on and off to create a custom layout.
Once you’ve got your site looking the way you want, you can also take a quick look over your site’s settings. Click Settings in the top-right corner of your site dashboard to see your options.
Here you’ll see various sections on the left-hand side. In the General tab, you can change your site title and slug, add a social preview image, and unpublish or delete your site.
Finally, the Plan tab lets you upgrade or downgrade your site to a different plan. So if you want to try out site sections, AI answers or any other features that aren’t included in your plan, this is the place to go.
Once you’ve created your site and added some content, you can go right ahead an publish.
By default, your site will be set to publish publicly — you can change this in the Audience section of your site’s Settings page.
Once you’ve set your chosen audience — or if you’re happy to publish publicly — all you have to do is hit Publish and your site will be live! Of course, you can continue editing your site’s customization and settings when it’s live, as well as editing the content and linking more spaces if you wish.
As you might imagine, this publishes your site publicly, so it will be visible to everyone on the web.
By default, your public site will also be indexed by search engines. If you don’t want your site to be indexed or appear in search results — such as if you’re publishing beta documentation or a version update — you can disable that in the menu.
With share links, you can create unique, private links to your docs to send to specific user groups. You can revoke a link at any time, so if a specific group no longer needs access to your docs it’s easy to remove them. Only people with an active link will be able to access your docs site, which won’t be indexed by search engines.
Once set up, visitors to your docs will be prompted to log in using their established credentials. Only people authorized in your backend will be able to access your docs. This is ideal if you want to control exactly who can view your documentation.
For now, let’s stick with our built-in tools.
First up you can see Traffic, which shows you how many views your pages have had in the last seven days, four weeks and 12 months. You’ll also see a trend indicator to give you an idea of how that data compares to the previous time period.
In the Insights area you can also see your visitors’ most common search queries, which is great if you’re trying to find and fix gaps in your content.
We can’t wait to see what you create!
That's a quick overview of how to set up, customize and publish your first docs site in GitBook. With so many options available, you’ll be able to make every page you publish feel like your own.
If you choose not to add sample content during the flow, you’ll create an empty docs site. Before you publish, you’ll need to link one or more spaces to your site — these act as your site’s content.
Alternatively, if you know which space you want to publish, you can simply navigate to it, click Share in the top-right corner, then choose the Publish to the web tab from the menu. In this menu, you can create a new docs site or link to an existing docs site in your organization. If the space is already linked to one or more docs sites, you’ll see those listed here instead.
Site sections are designed for adding different kinds of content to your site alongside your docs — such as API docs, a changelog, release notes, or anything else you need. The different sections will appear as tabs at the top of your site.
Variants help you show different versions of the same documentation — for example, if you want to translate your docs into other languages, or include different docs for release versions of the same product. Visitors will be able to switch between these different variants using a drop-down at the top of your published site’s sidebar.
To add another space to your site, open the Settings tab from the button in the top-right and click on the Structure tab. Here you can see all your linked spaces, organize your content into sections and variants, choose the default content for your site by dragging to change the space order, and link more content to your site by clicking Add section or Add variant.
While you could publish at this stage without making any further changes, let’s quickly run through some of your other options. That said, if you just want to publish without making any further changes, head down to the Publishing section below to get your docs site live in seconds!
Still here? Great — let’s dive into the ways in which you can customize your docs site to add branding or just make it your own. There are a ton of options to try, so we won’t explain every single one here. Read our docs to find out more about customization options.
You can also change some customizations at a content level — including adding header images and controlling the layout of your pages. To see these options, head back to your space and roll your cursor over the title at the top of the page.
The Audience tab holds your audience settings, and you can head to the Domain and redirects section to set up a custom domain for your docs site — giving it a personal or branded touch — and create manual redirects, which is handy if you’ve just imported your docs from another platform
In the Features tab you’ll find a toggle that lets you enable or disable AI search — available on Premium and Ultimate sites — for your published docs. This will let you readers ask GitBook AI questions about your documentation right from the search bar, and get a summarized answer based on your content in seconds.
You can also toggle PDF export on and off with a click if you have a Premium or Ultimate site. With this enabled, your docs site visitors will able to download a PDF of a single page — or the whole published space — from a button on your docs site.
Below that, you can enable page ratings, which lets users leave feedback on the content of a page and aggregates the responses to help you see how your pages rank with readers.
In the Structure section you can organize all the content on your site. Here, you can can add variants to individual spaces, and also add site sections if you have an ultimate site. Head back up to the section above to find out more.
Note: Some of these publishing options are only available on Premium or Ultimate sites, so if you want some of the more advanced options you may need to upgrade.
Take things one step further with visitor authentication. You’ll need to set up the authorization backend using either one of our auth integrations, or with your own custom setup.
Now that your docs site is live, let’s take a quick look at your site analytics. GitBook offers some simple insights out of the box, and if you want more detail about your site and its performance, we have several integrations that can help — including Google Analytics, Fathom and more.
If you’ve enabled page ratings for your docs site — which you can do in the Features section of your site’s Settings page — you’ll be able to view the best- and worst-rated pages on your site in the Feedback card. You can use this information to focus on areas that need improvement, and try to imitate the most successful pages. Find out more about how page ratings are calculated in our documentation.
We love seeing your GitBook docs, so feel free to share them with us on X (formly Twitter). And if you have any questions or ideas, you can join our GitBook community, or reach out to our support team — they’d be happy to help!