Sep 17, 2024
GitBook & Moderne: CI/CD for your docs
Sep 17, 2024
GitBook & Moderne: CI/CD for your docs
How to create and publish documentation in GitBook [updated for 2024]
Tutorials & tips
Tutorials & tips
Tutorials & tips
27 Aug 2024
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 with some content!
How to create a docs site
Ready to publish your docs? Let’s start by creating a docs site and trying out 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 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.
If you haven’t already, now is a good idea 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.
Adding more content to your site
You can link more than one space to a single docs site if you like — which is useful if you want to translate your docs into other languages, or include different docs for different product versions. Visitors will be able to switch between these different docs using a drop-down at the top of your published site.
To do this, open the Settings tab from the button in the top-right and scroll down to the Content section. Here you can see all your linked spaces, choose the default content for your site by dragging to change the space order, and link more content to your site by clicking Add content.
Customize your site
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.
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 as part of our Pro and Enterprise plans, so if you want the full suite of controls you may need to upgrade.
Change page 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.
In Page Options you can select one of our preset options, or manually toggle different controls on and off to create a custom layout.
Change your site’s settings
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 can change your audience settings, or set up a custom domain for your docs site, giving it a personal or branded touch. You can also edit the slug to make it fit more neatly with that custom domain you just set up.
Further down, you’ll find a toggle that lets you enable or disable AI search — available to Pro and Enterprise users — 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’re on a Pro or Enterprise plan. 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.
Finally, you can add a social preview for your docs site — which will show up when you share a link to your docs site on social channels and other platforms. Plus, you can manage and add more content to your site here, as we mentioned above.
This tab also holds the controls for unpublishing and deleting your site, so click carefully!
Audience settings and publishing
Once you’ve created your site and added some content, you can go right ahead an publish.
As part of the publishing process, you’ll need to choose your audience using the publishing modal or Audience settings menu. Here, you can select a few different options depending on who you want to access your docs.
Once you’ve set your chosen audience, 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.
Note: Some of these publishing options are only available for organizations on our Pro or Enterprise plans, so if you want some of the more advanced options you may need to upgrade.
Public
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 select unlisted from the menu.
Share links
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.
Visitor authentication
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.
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.
Check the built-in site analytics
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.
For now, let’s stick with our built-in tools.
If you’ve enabled page ratings for your docs site, you’ll be able to view the best- and worst-rated pages on your site in the User ratings tab. 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.
In the Insights tab 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.
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!
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 with some content!
How to create a docs site
Ready to publish your docs? Let’s start by creating a docs site and trying out 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 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.
If you haven’t already, now is a good idea 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.
Adding more content to your site
You can link more than one space to a single docs site if you like — which is useful if you want to translate your docs into other languages, or include different docs for different product versions. Visitors will be able to switch between these different docs using a drop-down at the top of your published site.
To do this, open the Settings tab from the button in the top-right and scroll down to the Content section. Here you can see all your linked spaces, choose the default content for your site by dragging to change the space order, and link more content to your site by clicking Add content.
Customize your site
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.
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 as part of our Pro and Enterprise plans, so if you want the full suite of controls you may need to upgrade.
Change page 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.
In Page Options you can select one of our preset options, or manually toggle different controls on and off to create a custom layout.
Change your site’s settings
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 can change your audience settings, or set up a custom domain for your docs site, giving it a personal or branded touch. You can also edit the slug to make it fit more neatly with that custom domain you just set up.
Further down, you’ll find a toggle that lets you enable or disable AI search — available to Pro and Enterprise users — 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’re on a Pro or Enterprise plan. 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.
Finally, you can add a social preview for your docs site — which will show up when you share a link to your docs site on social channels and other platforms. Plus, you can manage and add more content to your site here, as we mentioned above.
This tab also holds the controls for unpublishing and deleting your site, so click carefully!
Audience settings and publishing
Once you’ve created your site and added some content, you can go right ahead an publish.
As part of the publishing process, you’ll need to choose your audience using the publishing modal or Audience settings menu. Here, you can select a few different options depending on who you want to access your docs.
Once you’ve set your chosen audience, 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.
Note: Some of these publishing options are only available for organizations on our Pro or Enterprise plans, so if you want some of the more advanced options you may need to upgrade.
Public
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 select unlisted from the menu.
Share links
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.
Visitor authentication
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.
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.
Check the built-in site analytics
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.
For now, let’s stick with our built-in tools.
If you’ve enabled page ratings for your docs site, you’ll be able to view the best- and worst-rated pages on your site in the User ratings tab. 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.
In the Insights tab 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.
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!
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 with some content!
How to create a docs site
Ready to publish your docs? Let’s start by creating a docs site and trying out 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 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.
If you haven’t already, now is a good idea 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.
Adding more content to your site
You can link more than one space to a single docs site if you like — which is useful if you want to translate your docs into other languages, or include different docs for different product versions. Visitors will be able to switch between these different docs using a drop-down at the top of your published site.
To do this, open the Settings tab from the button in the top-right and scroll down to the Content section. Here you can see all your linked spaces, choose the default content for your site by dragging to change the space order, and link more content to your site by clicking Add content.
Customize your site
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.
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 as part of our Pro and Enterprise plans, so if you want the full suite of controls you may need to upgrade.
Change page 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.
In Page Options you can select one of our preset options, or manually toggle different controls on and off to create a custom layout.
Change your site’s settings
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 can change your audience settings, or set up a custom domain for your docs site, giving it a personal or branded touch. You can also edit the slug to make it fit more neatly with that custom domain you just set up.
Further down, you’ll find a toggle that lets you enable or disable AI search — available to Pro and Enterprise users — 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’re on a Pro or Enterprise plan. 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.
Finally, you can add a social preview for your docs site — which will show up when you share a link to your docs site on social channels and other platforms. Plus, you can manage and add more content to your site here, as we mentioned above.
This tab also holds the controls for unpublishing and deleting your site, so click carefully!
Audience settings and publishing
Once you’ve created your site and added some content, you can go right ahead an publish.
As part of the publishing process, you’ll need to choose your audience using the publishing modal or Audience settings menu. Here, you can select a few different options depending on who you want to access your docs.
Once you’ve set your chosen audience, 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.
Note: Some of these publishing options are only available for organizations on our Pro or Enterprise plans, so if you want some of the more advanced options you may need to upgrade.
Public
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 select unlisted from the menu.
Share links
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.
Visitor authentication
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.
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.
Check the built-in site analytics
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.
For now, let’s stick with our built-in tools.
If you’ve enabled page ratings for your docs site, you’ll be able to view the best- and worst-rated pages on your site in the User ratings tab. 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.
In the Insights tab 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.
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!
Get the GitBook newsletter
Get the latest product news, useful resources and more in your inbox. 130k+ people read it every month.
Similar posts
New in GitBook: Our published documentation is now open source, so you can contribute
27 Mar 2024
Steve Ashby
New in GitBook: Published content gets a new look, multi-space search and better performance
4 Mar 2024
Steve Ashby
New in GitBook: Write with AI, turn snippets into docs, and more
2 Feb 2024
Steve Ashby
Get started for free
Play around with GitBook and set up your docs for free. Add your team and pay when you’re ready.
Get started for free
Play around with GitBook and set up your docs for free. Add your team and pay when you’re ready.
