At GitBook, our mission is to provide a user-friendly and collaborative solution for creating, editing, and sharing product and API documentation.

Sign up Quickstart

Discover GitBook

Task lists allow you to create a list of items with checkboxes that you can check or uncheck.

Example of a task list

• Here’s a task that hasn’t been done

  • Here’s a subtask that has been done, indented using Tab.

  • Here’s a subtask that hasn’t been done.

• Finally, an item, unindented using shift + tab.

Representation in markdown

- [ ] Here’s a task that hasn’t been done
  - [x] Here’s a subtask that has been done, indented using `tab`
  - [ ] Here’s a subtask that hasn’t been done.
- [ ] Finally, an item, unidented using `shift` + `tab`.

Stepper blocks let you break down a tutorial or guide into separate, but clearly linked steps. Each step can contain multiple different blocks, allowing you to add detailed information.

Example

Representation in Markdown

## Example

{% stepper %}
{% step %}
### Step 1 title
Step 1 text
{% endstep %}
{% step %}
### Step 2 title
Step 2 text
{% endstep %}
{% endstepper %}

Limitations

There are some limitations on which blocks you can create inside of a stepper block — for example, you cannot add expandable blocks or another stepper block. See all the blocks you can add by starting a new line within a stepper block and pressing / to bring up the insert palette.

A paragraph is the most basic content block you can use on GitBook.

Example of a paragraph

Professionally printed material in English typically does not indent the first paragraph, but indents those that follow. For example, Robert Bringhurst states that we should “set opening paragraphs flush left.”

Representation in Markdown

Because a paragraph block is just text, that’s how it’s represented in Markdown.

Professionally printed material in English typically does not indent the first paragraph, but indents those that follow. For example, Robert Bringhurst states that we should “set opening paragraphs flush left.”

A tab block is a single block with the option to add multiple tabs.

Each tab can contain multiple other blocks, of any type. So you can add code blocks, images, integration blocks and more to individual tabs in the same tab block.

Add or delete tabs

Example

Here is an example that lists instructions relevant to specific platforms:

Representation in Markdown

{% tabs %}

{% tab title="Windows" %} Here are the instructions for Windows {% endtab %}

{% tab title="OSX" %} Here are the instructions for macOS {% endtab %}

{% tab title="Linux" %} Here are the instructions for Linux {% endtab %}

{% endtabs %}

Page link blocks are the best way create relations between different pages within your content. Page links stand out on the page as they fill their own block — compared to a hyperlink added to some text.

Example of page link block

Representation in Markdown

{% content-ref url="./" %} . {% endcontent-ref %}

Example of Math & TeX block

Representation in Markdown

# Math and TeX block

$$f(x) = x * e^{2 pi i \xi x}$$

Columns are a great way to create different layouts for your documentation. You can add many different types of blocks inside a column, and adjust the width of each side to customize it to the design you need.

Representation in Markdown

## Example

{% columns %}
{% column width="50%" %}
### Create a seamless experience between your docs and product

Integrate your documentation right into your product experience, or give users a personalized experience that gives them what they need faster.

<a href="https://www.gitbook.com/#alpha-waitlist" class="button primary">Learn more</a>
{% endcolumn %}

{% column %}
<figure><img src="../../.gitbook/assets/GitBook vision post.png" alt="An image of GitBook icons demonstrating side by side column functionality"><figcaption></figcaption></figure>
{% endcolumn %}
{% endcolumns %}

One reason to do this is so that your docs URL is formatted in a consistent way with your other site URLs. Using a subdirectory may also be beneficial for SEO.

To configure a subdirectory, you'll need to set things up in your website's backend, then finalize the process in your GitBook site settings.

When you submit a pull request (PR) to a GitHub branch that has been synced to a GitBook space, you can preview the content before merging. This allows you to check the impact of changes before merging them.

You can use this feature to have a final layer of checks before merging a PR, allowing you to see your changes in a non-production environment before merging it into your synced branch.

How to access preview links

For every PR create using a target branch synced with a GitBook space, you’ll see a status added to the PR with a unique preview URL. Clicking the Details link on the status will take you to the preview URL for your content. You can then make sure the content is as expected before merging the PR.

Security considerations

For security reasons, by default GitBook doesn’t currently generate previews for PRs opened from forks of your repository. Because the content of the PR preview is accessible under your own domain, whether on .gitbook.io or your custom domain, a user could generate malicious content in a fork of your public repository and have it served under your name.

We allow users to explicitly configure this through an option in the Git Sync settings.

Overview

Git Sync allows technical teams to synchronize GitHub or GitLab repositories with GitBook and turn Markdown files into beautiful, user-friendly docs. Edit directly in GitBook’s powerful editor while keeping content synchronized with your codebase on GitHub or GitLab.

Git Sync is bi-directional, so changes you make directly in GitBook’s editor are automatically synced, as are any commits made on GitHub or GitLab. This allows developers to commit directly from GitHub or GitLab and technical writers, instructional designers and product managers to edit, discuss and feedback changes directly in GitBook.

To add an embedbed URL, simply paste the link of the content you want to embed and hit Enter.

Videos

Codepen

Spotify

Representation in Markdown

{% embed url="URL_HERE" %}

Quotes are useful when you want to include something from another source.

Example of a quote

"No human ever steps in the same river twice, for it’s not the same river and they are not the same human." — Heraclitus

Representation in Markdown

> "No human ever steps in the same river twice, for it’s not the same river and they are not the same human." — _Heraclitus_

Getting started

You’ll need a GitBook account to start publishing documentation.

Create a docs site

When you first sign up, you’ll have a chance to create a docs site from the docs site wizard. You can launch the wizard again to create a new site at any point by clicking the + button next to the Docs sites header in the sidebar.

The docs site wizard will take you through the flow of creating your first site. You’ll need to give your site a name, choose if you want to start from scratch with an empty site or add our sample content, and whether or not you want to publish your docs right away.

Edit your content

Check out these resources if you’d like to learn more about the editing experience in GitBook:

Customize your site

Not only can you edit the content of your site, you can also customize many settings related to the look and feel of your site when it’s published.

You can read more about customizing your docs in the resources below:

Publish your documentation

Finally, you’re ready to publish your site into the world. If you haven’t already published your site from the wizard, you can publish your site from your site’s dashboard at any time.

After publishing your site, you’ll get a link that you’re able to share with anyone!

By default, when exporting content from GitBook to the Git repository, GitBook will generate a commit message based on the merged change request:

Autolink GITBOOK-<num> in GitHub and GitLab

Use the following URL format, where spaceId corresponds to your space’s URL:

<https://app.gitbook.com/s/{spaceId}/~/changes/<num>/

Customize the commit message template

The template can contain the following placeholders:

• {change_request_number} unique numeric ID for the change request

• {change_request_subject} the subject of the change request when merged, or No subject if none has been provided.

The default template is:

A space is a project that lets you work on a collection of related pages. They allow you to write content, organize pages, add integrations and more.

Create a space

Duplicate a space

Duplicating a space will create a copy of the source space, in the same location (organization, collection, sub-collection, etc.).

Move a space

Delete a space

Unordered lists are great for making a series of points that do not necessarily need to be made in a particular order. They are effectively bullet point lists, with support for nesting as needed.

When typing a list in GitBook, you can exit the list and start a new empty block below by hitting Enter twice.

Example of unordered list

• Item

  • Nested item

    • Another nested item

  • Yet another nested item

• Another item

• Yet another item

Representation in Markdown

GitBook’s Quick find palette lets you search for content across all your organizations, and jump between them fast.

Use Quick find

Search results

Results from the space you’re currently in appear at the top, followed by results from other spaces from the organization you’re currently working in — as well as other organizations you are a member of.

Permissions

Quick find is compliant with your team’s permission settings, meaning that users will only be able to search the content they have permission to access.‌

Content indexing

Each result shows the first three lines of information below the section header. If your section is too big, your keyword match may not appear in the preview — but don’t worry, quick find still found a match!

When engaging with GitBook AI, you have the ability to ask questions or elaborate on specific requirements. This AI-driven tool is designed to review your documentation in real-time, providing you with quick, direct answers.

GitBook AI helps you find answers in the GitBook app

You can enable GitBook AI for your organization’s internal content, allowing you to ask questions and get semantic answers about your internal knowledge base.

Head to the Organization settings page and, in the General tab, toggle the Enable GitBook AI setting on.

Using GitBook AI search

FAQs

How long does it take for GitBook AI to index changes?

How does GitBook AI handle my data?

How do I prevent hallucinations with GitBook AI search?

If you’re seeing GitBook produce answers that are incorrect, the best method for correcting this is write explicit content around the topic so the AI does not have to guess.

How to add a specification

1. Open the OpenAPI section in the sidebar

2. Click on Add specification

3. Give your specification a name. This helps identify it, especially if you manage multiple specs

4. Choose one of the following:

   • Upload a file (e.g. openapi.yaml)

   • Enter a URL to a hosted spec

   • Use the CLI to publish the spec

Update your specification

You can update your OpenAPI specification at any time using the GitBook UI or the CLI, regardless of how it was initially added.

In GitBook Application

In the OpenAPI panel:

• If your spec is linked to a URL:

  • GitBook checks for updates automatically every 6 hours.

  • To fetch updates immediately, click Check for updates.

• If your spec was uploaded as a file:

  • Click Update to upload a new version.

• You can switch from a File to a URL source by clicking on Edit in the breadcrumb actions menu.

Using the CLI

Use the same command to update your specification:

You can also use the CLI to Check for updates by running the publish command on the same URL.

Once you’ve finished writing, editing, or importing your content, you can publish your work to the web as a docs site. Your docs will be published on the web and available to your selected audience.

Create a docs site

To create a docs site, click the plus + icon next to Docs site in the sidebar to launch the docs site wizard.

Give your site a name, choose a starting point for your content, and select whether you want to publish your site now or later.

If you already have content in a space that you would like to use, you can create a docs site directly from that space by opening the space and clicking Share in the top-right corner of the window. Then choosing Publish as a docs site from the share modal.

Publish a docs site

There are three primary options to choose from when publishing your site:

Delete or unpublish a docs site

Site editing permissions

You can view all the permissions set for users with access to the docs site from the permissions modal from the docs site’s Overview page. You’ll also see which space the user’s permission was inherited from. If you’d like to change the permission settings, open the space, then click Share. Here you can edit the permissions from a modal.

Users with Administrator or Creator permissions on any space linked to a specific docs site will have full access permissions for the site. This means that they’ll be able to control any of the publishing and customization settings.

Users with Reviewer, Editor, Commenter, or Reader permissions on any space linked to a specific site will get read-only permissions. This means they will see the docs site in your organization, but won’t be able to access any of its settings.

Upload a specification file

If your OpenAPI spec is generated during your CI process, you can upload it directly from your build environment:

Set a new souce URL or trigger a refresh

If your OpenAPI specification is hosted at a URL, GitBook automatically checks for updates. To force an update (for example, after a release), run:

To protect your docs behind a sign-in screen, you’ll need to first enable authenticated access for your site.

Enable authenticated access

Choose an authentication method

Depending on your setup, we have integrations and guides on setting up authenticated access for different tools.

Head to the relevant guide to continue setting up authenticated access for your site.

It’s common to have operations that are not fully stable yet or that need to be phased out. GitBook supports several OpenAPI extensions to help you manage these scenarios.

Marking operation as experimental, alpha, or beta

Use x-stability to communicate that an endpoint is unstable or in progress. It helps users avoid non-production-ready endpoints. Supported values: experimental, alpha, beta.

Deprecating an operation

To mark an operation as deprecated, add the deprecated: true attribute:

Optionally specify when support ends by including x-deprecated-sunset:

Hiding an operation from the API reference

To hide an operation from your API reference, add x-internal: true or x-gitbook-ignore: true attribute.

Collections are a way to group spaces together to make it easier for you to organize your content. With collections, you can:

• organize your content by similar topics or ideas

Create a collection

Click the + button next to the Spaces header in the sidebar to create a new collection. You can also create a collection or space within another collection from the collection’s main page.

Move a collection

Nested collections

You can nest collections inside each other, creating a collection -> sub-collection -> space hierarchy.

Open a collection and you can click New collection from the collection’s main page to create a sub-collection.

How to delete a collection

To create a drawing, press / on an empty line to bring up the insert palette and choose Drawing. This will open a popover with Excalidraw tools — simply close the popover when you’re done and your diagram will appear on your GitBook page.

GitBook stores drawings as special SVG files in the space. Those files have an extension of drawing.svg.

Example of a drawing block

Draw with GitBook AI

When using drawing block, you can ask GitBook AI to generate an illustration by specifying a prompt. Simply type in a prompt and hit Generate, or choose one of the suggested prompts to get started.

Once GitBook AI has finished the drawing, you can double-click to open the full drawing palette and edit it however you like.

When editing a drawing, click the Use AI to generate button to bring up GitBook AI’s prompt editor again and generate a new drawing.

The structure of your content in GitBook is organized through pages, spaces and collections. Pages live inside of spaces, and collections are groups of spaces.

Header

Search bar

Change the position and look of the search bar between prominent (centered in the header) and subtle (located in the upper right corner). Turning off the header entirely will place the search bar in the sidebar instead.

Navigation

Add header links to your site. You could use header links to point to important parts of your documentation, or link back to your main website.

You can choose what appearance you would like your link to have—normal link, primary button, or secondary button. When enabled, simply add a title and a URL for each link. We support two levels of header navigation, meaning you can have sub‑links that appear in a dropdown menu.

Announcement (Premium & Ultimate)

Toggle this option on to add an announcement banner to the top of your published site. You can add a message and optionally include a link and call to action, which will appear after your message in the banner.

You can also change the announcement style using the same options as hint blocks—Info, Warning, Danger, and Success. The color of these styles is determined by your semantic colors settings.

Pagination

Control the display of the “previous” and “next” buttons that appear at the bottom of each page in your space. You can also set this feature for specific pages.

Footer (Premium & Ultimate)

Logo

Add your logo or another image in the footer.

Copyright text

Add copyright information to your footer.

Navigation

Add links in your footer, organized into multiple sections. Similar to the header, add a title and URL for each link, and include a section title for each group of links.

Whether you’re working within the GitBook app or your visitors are reading your published content, GitBook’s search functions help to make it easy to find what you’re looking for.

You can use quick find to look for specific words or phrases, or you can ask GitBook AI a question. It’ll scan through your docs and summarize an answer in seconds, with references to help you find out more.

When an API operation includes an enum, you can add x-enumDescriptions to provide more context about each option. GitBook will display the enum values and their descriptions in a table next to the operation.

Authenticated access allows you to publish your content while requiring authentication from any visitors who want to view it. When enabled, GitBook lets your authentication provider handle who has access to the content.

Use cases

Common use cases for authenticated access include:

• Publishing sensitive product documentation that should only be accessible to paying customers, sales prospects or partners.

• Publishing internal knowledge base content that should only be accessible to employees of your company.

How it works

There are two methods you can choose from when setting up authenticated access:

1. Installing one of our authentication integrations — we currently support Okta, Azure, and Auth0. We highly recommend this option if you’re using an authentication provider we support.

2. Create and host your own server to handle the authentication. Many different technologies can be used, but it’s up to you to code and maintain the solution you choose.

Allow readers to export a PDF version of your published content

This setting determines whether or not readers of your published content can download it in PDF format. This feature is only available for Standard and Premium sites.

Export your own internal content as PDF

However you decide to configure your published docs sites, all logged-in members of an organization on a Pro or Enterprise can export a page — or an entire space — from your internal knowledge base as a PDF file.

Export an individual page

1. next to the page title.

2. Select Export to PDF > Current page.

3. Wait for the page to load, then click the Print or save as PDF button in the upper right to open your browsers Print menu.

4. From here, you can save the page as a PDF or open it in your PDF viewer using the typical process for your browser.

Export an entire space

1. next to the page title and choose Export as PDF > All pages. Alternatively, open the space’s Actions menu
2. Wait for the page to load, then click the Print or save as PDF button in the upper right to open your browsers Print menu.

3. From here, you can save the page as a PDF or open it in your PDF viewer using the typical process for your browser.

GitBook supports live collaboration, meaning you’ll be able to work on the same document with multiple members at the same time.

Toggling live edit mode

When a space is in Live edits mode, the space header will show the Editor tab. When it is in Locked live edits mode, the space header will show a Read-only tab. When the Read-only tab appears in the space header, you will need to open a change request to edit the content of the page, or unlock live edits.

When is live editing not available?

You cannot unlock live editing if:

1. a space is published with the In collection, Public, or Unlisted visibility option.

Segments allow you to test the conditions you set by defining claims on a mock user.

For example, you might want to only show a page or section to beta users. By creating a segment and defining the properties associated with this group of mock users, you can mimic a segment that is specific to the users you’re targeting.

Create a segment

Here you’ll be able to define the data that will appear on a mock user. Because this is the data that’s being represented, the visitor.claims key is omitted.

Example

To create a segment for beta users following the examples in our docs, you would create a new segment, and add the following data.

When heading back to the condition editor, selecting the beta segment we created should show that the page we’re viewing would be accessible to our test user.

Detected segments

Detected segments allow you to get a sense of the type of claims you are receiving from visitors to your site.

These segments are not editable, but allow you to copy/paste claims from the segment editor to create your own user segments.

Testing segments in the preview

In addition to testing segments in the segment editor, you’ll be able to use your segments in real time in the preview when viewing changes for your site.

Use the dropdown in the upper left corner when in preview mode for your site to choose a segment to see how your site will look for your chosen segment.

GitBook can automatically generate generic code examples for each API operation. If you’d prefer to showcase custom or more detailed snippets, add x-codeSamples to your OpenAPI definition. This way, you control how your endpoints are demonstrated and can offer language or SDK-specific examples.

Key Points

• x-codeSamples is an array of code sample objects.

• Each object defines:

  • lang: The language of the code (e.g., JavaScript, Java).

  • label: A short label for the code block.

  • source: The actual code snippet.

Expandable blocks are helpful in condensing what could otherwise be a lengthy paragraph. They are also great in step-by-step guides and FAQs.

Example

Representation in Markdown

# Expandable blocks

<details>

<summary>Expandable block</summary>



</details>

Limitations

There are some limitations on which blocks you can create inside of an expandable block. You can check the full list by starting a new line in an expandable block and pressing / to bring up the insert palette.

Getting started

Authenticate with GitHub

If you’re setting up GitHub Sync for the first time and haven’t already linked a GitHub account, you’ll be prompted to do that when you begin configuring Git Sync. If you’ve already linked your account, you may still need to authenticate via GitHub.

Install the GitBook app to your GitHub account

Follow the instructions in the GitHub popover and either give GitBook specific repository permissions, or allow access to all repositories, depending on your needs.

Select a repository and branch

Select the account and repository you want to keep in sync with your GitBook content.

Once you’ve selected the correct repository, choose which branch you want commits to be pushed to and synced from.

Perform an initial sync

When syncing for the first time, you’ll have the option to sync in one of two directions:

1. GitBook -> GitHub will sync your space’s content to the selected branch. This is great if you’re starting from an empty repository and want to get your GitBook content in quickly.

2. GitHub -> GitBook will sync your space’s content from the selected branch. This is great if you have existing Markdown content in a repository and want to bring it into GitBook.

Write and commit

When you edit on GitBook, every change request merge will result in a commit to your selected GitHub branch.

When you commit to GitHub, every commit will be synced to your GitBook space as a history commit.

GitBook is a block-based editor, meaning you can add different kinds of blocks to your content — from standard text and images to interactive blocks. Your pages can include any combination of blocks you want, and there’s no limit to the number of blocks you can have on a page.

Inserting a new content block

You can insert a new content block below an existing block using your mouse:

1. Hover over the block above the place you need the new content block.

2. Click on the + icon that appears on the left to open the insert palette.

3. Select the block you want from the drop-down menu to insert it.

Alternatively, on a new line, you can press / to launch the insert palette, which lists all the available blocks. You can scroll through the list to find the one you want, or use your keyboard to search for the block you want, navigate up and down the list, and insert it with Enter.

Exiting a block

When you are done, you can continue adding new content to the page either by inserting a new block using the + button to the left of your content, or by hitting ⌘ + Enter on a Mac or Ctrl + Enter on a PC.

Selecting blocks and interacting with selected blocks

You can select a single block by pressing the Esc key with the cursor in the block. You can also select multiple blocks by highlighting content within them and hitting Esc.

Once selected, you can:

• Select more blocks by clicking on them while keeping the Shift ⇧ key pressed.

• Moving up and down to select the block above or below, using the ↑ and ↓ keys

• Copy the entire block using ⌘ + C (Mac) or Ctrl + C (Windows)

• Cut the entire block using ⌘ + X (Mac) or Ctrl + X (Windows)

• Delete the selected block or blocks using ⌫ or Del.

Full-width blocks

By making your blocks full width, you can create a clear visual hierarchy in your content, or simply give more space to content that needs it.

• Code Blocks

• Image blocks

• Tables

• Cards

• API Blocks

• Integration blocks

• Columns

Hints are a great way to bring the reader’s attention to specific elements in your documentation, such as tips, warnings, and other important information.

Examples of hint blocks

To add a heading to your hint, you need to create a heading block as the the first block in the hint.

Representation in Markdown

{% hint style="info" %}
**Info hints** are great for showing general information, or providing tips and tricks.
{% endhint %}

{% hint style="success" %}
**Success hints** are good for showing positive actions or achievements.
{% endhint %}

{% hint style="warning" %}
**Warning hints** are good for showing important information or non-critical warnings.
{% endhint %}

{% hint style="danger" %}
**Danger hints** are good for highlighting destructive actions or raising attention to critical information.
{% endhint %}

{% hint style="info" %}

## This is a H2 heading

This is a line

This is an inline <img src="../../.gitbook/assets/command_icon_light.svg" alt="The Apple computer command icon" data-size="line"> image

- This is a second <mark style="color:orange;background-color:purple;">line using an unordered list and color</mark>
{% endhint %}

You can upload files to your GitBook space and add them to your page for people to view or download.

You can show some files, such as images and OpenAPI files, on the page itself for people to see without clicking anything. For others, such as PDFs, users will have to click to view or download it.

You can also optionally add a caption below any file you insert into your page to add more information if needed.

Example of a file

Uploading a file

You can manage uploaded files in the Files side panel of your space. You can find the Files panel at the top of your space’s table of contents.

To upload a file, drag and drop it into the Drop your file or browse section, or select it and use your system file dialog to select the file you want to upload.

Renaming a file

Deleting a file

Replacing a file

If you have a file that simply needs updating to a new version, you can replace it. This will swap out the old file and put the new file in its place. Any blocks that previously referred to the old file will then refer to the new file.

This can be helpful if, for example, you’ve had a major product redesign and need to update outdated UI screenshots that appear on multiple pages. Replacing the original file would update the screenshot everywhere in your space, saving you time and effort.

You can use GitBook AI to create content on any empty line on your page. It can create all kinds of content — formatted in Markdown — including code samples, templates, page summaries and more.

Write with GitBook AI

Press Space on any empty line, or type / and choose Write with AI to enter GitBook AI’s writing mode.

You can instantly start typing any prompt you want. GitBook AI will analyze the prompt and generate content based on it. For example:

Write me a two-paragraph overview of why documentation is important for product teams.

Alternatively, you can also choose from one of the suggested prompts or prompt starters:

Continue writing

If you click this option, GitBook AI will analyze the content on your current page and then generate more content based on that.

Explain…

Click this and then tell GitBook AI what you want it to explain. This isn’t limited by content on your page, so you can ask it to explain anything at all.

Summarize

As you can imagine, this option will summarize all the content on your page — great for writing a TL;DR at the bottom of a detailed document, or adding a quick summary at the top for people just checking in.

Explain this

This will break down the complex information on your page and explain it in simpler language — including explaining acronyms and other jargon. This is perfect if the page you’re reading involves a lot of complex information, or you want to add an explainer for less technical folks.

Translate

This mode will translate your current page into one of a set number of languages. If you want to translate into a language that’s not on the list, simply type it into the prompt box.

FAQs

General

Audience

Domain and URL

Redirects

Features

AI & MCP

Structure

Plan

Manually writing REST API documentation can be a time-consuming process. Fortunately, GitBook streamlines this task by allowing you to import OpenAPI documents, which detail your API’s structure and functionality.

The OpenAPI Specification (OAS) is a framework that developers use to document REST APIs. Written in JSON or YAML, it outlines all your endpoints, parameters, schemas, and authentication schemes.

Once imported into GitBook, these documents are transformed into interactive and testable API blocks that visually represent your API methods—whether the specification is provided as a file or loaded from a URL.

Test it (powered by Scalar)

GitBook's OpenAPI block also supports a "test it" functionality, which allows your users to test your API methods with data and parameters filled in from the editor.

Ordered lists, also called numbered lists, help you prioritize items or create a list of steps.

Example of ordered list

1. Item 1

   1. Nested item 1.1

      1. Nested item 1.1.1

   2. Nested item 1.2

2. Item 2

3. Item 3

Representation in Markdown

1. Item 1
   1. Nested item 1.1
      1. Nested item 1.1.1
   2. Nested item 1.2
2. Item 2
3. Item 3

Adding an inline image to an ordered list

Adding images inside of ordered lists is possible in GitBook

If you want to add an image within an ordered list, add it using the insert menu, then on the row below the image type 3. then hit Space, and the ordered list will continue.

1. Item 1

2. Item 2

1. Item 3

2. Item 4

Redirects are commonly used when you are migrating your documentation from one provider to another — like when you just moved docs to GitBook. Broken links can impact SEO so we recommend setting up redirects where needed.

Managing redirects on your site

To get started, view your site’s dashboard in GitBook and open the Settings tab, then click Domain & redirects.

Creating redirects

If you want to add another redirect to the same page, you can toggle the Add another redirect option on before you hit Add. When you add your redirect, the modal will remain open with the destination content set to the previous selection so you can add another URL slug immediately.

Editing redirects

To delete a redirect, press the Delete redirect button and confirm.

About automatic redirects

Every time a URL is loaded, GitBook resolves it through the following steps:

1. Site content is resolved to its canonical URL by following any of the automatically created redirects.

You can share you content privately with customers or partners without needing to invite them to your organization by using share links.

Publish with share links

Next, click on Create link to create a share link. You can review and name your share links, customize your domain and copy the link.

Once the link is active, a private token is generated within your URL, which is unique to your space. Sharing this link will give non-GitBook users access to your content in read mode only, with an interface that looks like any other published content.

You can generate as many links as you need from Audience settings.

Access and permissions

The content will be accessible to anyone following the link. Your team members can access your content from the Docs sites section of the sidebar, or by navigating to the space directly.

Revoke a link

You can disable or regenerate your shareable by revoking it. You can see and revoke any previously generated link by opening the visibility menu and clicking through to link and domain settings.

Once you revoke a link, anyone with that outdated link to your content will no longer have access.

Localize user interface

You can select from a list of languages to localize the user interface of your published content. This applies translations to the non-custom areas of the interface.

This setting will not auto-translate your actual content, but it can help match the interface to the language you’re writing in.

Edit on GitHub/GitLab

If your space is connected to a Git repository, you can optionally show a link for your users to contribute to your documentation from your linked repository.

External Links

This setting controls the behaviour when your site users click an external link. By default, they will open in the same tab, but you can switch this to open in a new tab if that's your preference.

Page actions

Page actions adds a page-level dropdown to every page of your docs, allowing users to perform quick actions on a page's content — ideal for using your docs content as context within an AI prompt.

You can disable this option from the Configure tab if you do not wish to show page options in your published docs.

Open in AI providers

Displays an action to open ChatGPT or Claude with the page content.

Copy/View as Markdown

Displays an action to copy or view the page as Markdown.

Privacy Policy

GitBook allows you to automatically generate pages related to the endpoints you have in your OpenAPI spec. These pages will contain OpenAPI operation blocks, allowing you and your visitors to test your endpoints and explore them further based on the information found in the spec.

Automatically create OpenAPI pages from your spec

Add an individual OpenAPI block

Alternatively, you can add OpenAPI operations or schemas from your spec individually to pages throughout your docs.

With site sections, you can centralize all your documentation and create a seamless experience for your users.

Site sections are perfect for organizing your documentation — whether you’re managing separate products, or catering to both end-users and developers with content tailored to each.

Adding a section to your docs site

From your docs site’s dashboard, open the Settings tab in the site header, then click Structure. Here you can see all the content of your site.

To add a site section, click the New section button underneath the table and choose a space to link as a section. The new section is then added to the table and will be available to visitors as a tab at the top of your site.

Create a site section group

You can group site sections together under a single heading. Site section groups will appear as a drop-down in your site’s nav. Site sections in a group can also include an optional description, which appears below the section title in the drop-down menu.

To create a group, click the arrow next to the New section button and choose New section group. Give your new group a name, then click Add section in the modal to add sections to your group. You can add existing sections of your site to the new group, or select another space you want to add using the menu.

Editing a section

Site sections within a group can also optionally display a description, which will appear in the drop-down menu of your site’s nav bar when the section group is hovered. See the image at the top of this page to see an example of how this can look in your published documentation.

Reordering sections

You can also use the keyboard to select and move content: select a section with the space bar, then use the arrow keys to move it up or down. Hit the space bar again to confirm the new position.

Setting a default section

If you have multiple sections in your site, one section will be marked as the default. This section is shown when visitors arrive on your site, and is served from your site’s root URL. Other sections each have a slug that is appended to the root URL.

Remove a section

To remove a section from a site, open the Settings tab from your docs site dashboard, then click Structure to find the content you want to remove.

You can pass visitor data to your docs through URL query parameters. Below is an overview of the method:

Query parameters

To pass data to GitBook through URL parameters, you’ll need to pass the data in the URL in the format visitor.<prop>.

For example:

https://docs.acme.org/?visitor.language=fr&visitor.country=fr

Visiting this URL would pass in the following claims when the site loads:

{
  "language": "fr",
  "country": "fr"
}

To setup your GitBook site with authenticated access using OIDC, the process looks as follows:

OIDC stands for OpenID Connect, and it's an identity layer built on top of OAuth. Many identity providers abide by OIDC, and GitBook's OIDC integration for authenticated access allows you to publish your space behind authenticated access, and access to the content is controlled by your Identity Provider

Create a new application with your identity provider

There are some things that you need to set up on your Identity Provider in order to get the integration to work.

You need to create a new app inside your Identity Provider. Its type should be "Web Application." In Google, you create these under "API and Services", "Credentials", and then under "OAuth 2.0 Client IDs."\

Click on Create Credentials, select OAuth Client ID, select Web Application as the type, name it appropriately, and under Authorized Redirect URIs, enter the Callback URL you got from GitBook.

Click Create. Make a note of the Client ID and Client Secret. We will need these to finish configuring of our integration in GitBook.

Install and configure the OIDC integration

Navigate to integrations within the GitBook app, select authenticated access as the category, and install the OIDC integration. Install the OIDC integration on your chosen docs site.

Once you've installed it on your site, go to configuration and make a note of the Callback URL right above the Save button. We may need it to set up the Identity Provider.

Open up the OIDC integration's configuration screen for the space you installed the integration on.

It should look like the following image

For Client ID and Client Secret, paste in the values you got for your identity provider.

Now, you will need to find the Authorization Endpoint and Access Token Endpoint for your Identity Provider. For Google, these are https://accounts.google.com/o/oauth2/v2/auth and https://oauth2.googleapis.com/token respectively.

For OAuth Scope, its value will be again be different depending on your Identity Provider. In case of Google, you can enter openid.

Hit Save.

Now, in GitBook, close the integrations modal and click on the Manage site button. Navigate to Audience, select Authenticated access, and choose OIDC as the backend. Then, click Update audience. Go to the site’s screen and click Publish. The site is now published behind authenticated access controlled by your Auth0 application. To try it out, click on Visit. You will be asked to sign in with OIDC, which confirms that your site is published behind authenticated access using Auth0.

GitBook offers out-of-the box solutions to protect your docs. Integrations for Auth0, Okta, Azure AD, and AWS Cognito allow you install an integration to enforce a log-in screen before being able to access your published site.

Depending on which authenticated access method you’re using, you’ll still need to configure a few more things depending on which integration you’re using in order to send the right data to GitBook.

Head to the relevant guide for full instructions on setting up adaptive content with authenticated access.

Sharing a space or collection

To share a space or collection, click the share button in the top-right corner. This will open the share modal.

Inside the share modal, you’ll see different sharing options along the top.

You can see everyone who access, and their level of access, in the share modal. You can also make changes to these settings here.

Invite members

Invite a person or team from your organization

Some people in your team may not have access to a specific space in your GitBook organization due to their role or specific permissions settings. To invite someone who’s already a member of your organization, simply type their name, choose their role for this space, and hit Invite.

Invite someone from outside your organization

To invite someone from outside your organization, simply add their email address, choose their role, and hit Invite. When you choose their role, you can also choose to leave the Invite as an organization member toggle switched on to make them a full member of your organization, with access to all your team’s content when they’re logged in.

Invite guests via link

If you don’t want to use email to invite someone to your content, or want to invite a number of people as guests quickly, you can create a secret link. You can also set the role of guests that join using the link, so you have control over who can do what to your content.

When a user visits your site, you may already know things about them - who they are, which plan they're subscribed to, which features they have access to.

Adaptive content helps to build a tailored documentation experience based on who is reading.

Launch the demo site

How it works

Adaptive content works in 1 of 2 ways:

1. Passing data from your app to GitBook

2. Passing data from authenticated access

When a user visits your sites, we call the data they bring with them their "claims"—basically data that helps to identify a user. These claims are controllable by you - the site author - and can be used through the GitBook editor to show or hide different pages, variants, and sections in your docs.

GitBook’s editor allows you to create formatted content using Markdown.

Markdown is a popular markup syntax that’s widely known for its simplicity. GitBook supports it as a keyboard-friendly way to write rich and structured text.

Text formatting

GitBook supports all the classic inline Markdown formatting:

Titles

• Heading 1: # A first-level title

• Heading 2: ## A second-level title

• Heading 3: ### A third-level title

Code blocks

```⏎ creates a new code block.

```py⏎ creates a new code block with Python syntax highlighting.

Lists

GitBook automatically detects and creates ordered and unordered lists as you type.

• Begin a line with - or * to start an unordered bullet list.

• Begin a line with 1. to start a numbered list.

• Begin a line with - [ ] to start a task list.

Quotes

Begin a line with > to create a block quote. If you select an entire paragraph from start to end, typing > will wrap the content in a block quote.

This is a block quote.

Dividers

Type --- then hit Enter to create a divider on your page.

This is an example of a divider.

If you repeat the same name, phrase or version number multiple times within your content, you can create a variable to help keep all those instances in sync and accurate — which is useful if you ever need to update them, or they’re complex and often mistyped.

You can create variables that are scoped to a single page, or a single space.

Create a new variable

You can use the toggle at the top to view and create variables scoped either to the current page you’re on, or all pages within the current space.

Clicking Create a variable will launch a modal where you can give your variable a name and a value.

Click Add variable to save your variable.

Use variables in your content

Variables defined under your page are accessible under the page.vars object. Similarly, variables defined across your entire space are accessible under the space.vars object.

Update a variable

You can update a variable at any point when within a change request. Updating its value will update the value across any expression blocks referencing it. The changed variable will go live to any published site once the change request is merged.

You can publish multiple versions of the same documentation as part of a single docs site. These variants will be available to the end users via the space switcher in the top-left corner of the published site.

Add multiple languages or versions

A site with multiple variants is useful if you need to group together the content of your spaces — such as if you’re documenting multiple versions of an API (v1, v2, v3, etc.), or documenting your content in different languages.

Adding a variant to your docs site

From your docs site’s dashboard, open the Settings tab in the site header, then click Structure. Here you can see all the content of your site.

To add a variant, click the Add variant button in the section you'd like to add to, then choose a space to link. The new variant is then added to the list of variants within the chosen section and will be available to visitors in the variant dropdown on your site.

Changing a variant

Reordering variants

You can also use the keyboard to select and move content: select a section or variant with the space bar, then use the arrow keys to move it up or down. Hit the space bar again to confirm the new position.

Setting a default variant

If you have multiple variants within a section, one variant will be marked as the default. This variant is shown when visitors arrive on your site (or when they visit a section). Other variants each have a slug that is appended to the site's URL.

Remove a variant from a site

To remove a variant from a site, open the Settings tab from your docs site dashboard, then click Structure to find the content you want to remove.

Headings help give your documents structure — and using keywords in headings will also help search engines understand that structure, which can help your page rank higher in search results.

Anchor links

When you add a heading to a page, it creates an anchor link. You can then link directly to these specific sections, to point people to relevant information.

Link to an anchor

You can see anchor links in public content, or private content in read-only mode, by hovering over the title and clicking the # that appears next to it. This will update the URL in your browser’s top bar, so you can copy it to use elsewhere.

Edit an anchor

By default, the anchor link will be identical to the text in your header. If you plan to link to that URL outside of GitBook, changing the header in future will break the anchor link. The link will then take visitors to the top of the page, rather than the anchor location.

Representation in Markdown

GitBook generates SEO optimized pages, meaning page titles in GitBook are automatically represented in markdown as a first level heading:

Heading examples

My heading 1

My heading 2

My heading 3

You can customize the appearance of your published documentation, match the user interface to the language of your content, and more.

You can apply customizations to your entire docs site as a site-wide theme, or to individual variants and site sections.

Customizing sites with multiple sections

If you have a docs site with with multiple sections, you can control the customization of each one individually.

Select the whole site or a specific site section using the drop-down menu at the top of the Customization panel.

• Site-wide settings – These automatically apply to all linked spaces.

• Section specific settings – If you’re using site sections, you’re can set section specific customization that will override the default site-wise setting.

What counts as ‘Advanced customization’?

Every GitBook user can take advantage of basic customization options on their docs site. Premium or Ultimate site plan users can also use advanced customization features to further tweak their docs to match their brand.

Advanced customization options include:

• Custom logo – Add a logo that replaces the emoji and title at the top of your docs site.

• Icons - Change the weight and style of page icons in your docs site.

• Custom font – Change the font of your docs to one of the built-in options.

• Footer – Add a custom logo, copyright text and navigation to a footer at the bottom of your documentation.

• Bold and Gradient themes – Change the background color for your header, or add a gradient background to your entire site with these new themes.

What cannot be customized?

3. It’s not possible to remove the small “Powered by GitBook” link that appears in published documentation.

Publish as public

To publish your docs publicly on the web head to the docs site you want to publish, click Publish button, and choose the Public option.

Publish without search engine indexing

By default, your site will be indexed by search engines. You can alternatively choose to disable this — meaning the docs are still available to everyone on the web, but they won’t be indexed by search engines such as Google.

They will still be accessible to anyone with a the link to your documentation. Docs sites that aren’t indexed can be particularly helpful if you want to publish a beta version of your docs, or do large-scale user testing without impacting your SEO with potentially duplicate content.

Page-level search indexing controls

You can also control search indexing at the individual page level. GitBook provides two types of search indexing controls:

Internal search indexing

Controls whether pages are indexed in GitBook's internal search engine and Ask AI feature. This affects:

• Content search within your GitBook space

• Ask AI's ability to reference the page content

External search indexing (Web crawlers)

Controls whether search engines and web crawlers (Google, ChatGPT, etc.) can index your pages. This affects:

• SEO and discoverability through search engines

• Web crawler access to your content

Hierarchical inheritance behavior

Search indexing settings follow a hierarchical inheritance pattern:

• Parent page controls: When you disable search indexing on a parent page, it automatically disables indexing for ALL sub-pages beneath it.

• Children cannot override: Sub-pages cannot re-enable search indexing if their parent page has it disabled.

• Cascading effect: This creates a cascading effect down the entire page hierarchy - disabling indexing on a top-level page will disable it for the entire section.

This hierarchical behavior ensures consistent indexing policies across related content sections and prevents accidental exposure of content that should remain private within a section.

GitBook supports monorepos. A monorepo is a repository that contains more than one logical project (e.g. an iOS client and a web application).

GitBook can synchronize multiple directories from the same repository with multiple spaces. When enabling Git Sync on a space, you can configure a "Project directory". It will be used to lookup the .gitbook.yaml file for the directory to synchronize with this space.

Example of a repository structure:

In this example, 3 spaces can be created on GitBook and configured with different Root directories:

• packages/styleguide

• packages/app

• packages/api

Updating the Project directory

In some cases, you might have started with a typical repository synchronizing with only one space, but then decided to transition into a monorepo with multiple spaces synchronizing with it; or might have to rename the Project directory.

Changing the Project directory on an existing Git Sync can have an unexpected impact on the content, the change will only be propagated during the next synchronization (edit made on GitBook or new commit in the Git repository).

If the next operation is an import from the Git repository:

GitBook will expect to find the pages and files in the Project directory. If the files have not already been moved into the repository’s Project directory, the result of the synchronization would be an empty space with no content.

We recommend having the next operation to be a commit moving all GitBook-related files (markdown files, README/SUMMARY, and assets) in the repository to their correct new location, in the Project directory.

If the next operation is an export from GitBook to the Git repository:

GitBook will generate or update new files in the new Project directory. Files synchronized with GitBook will be moved to the new Project directory (with the best attempt); it might cause side effects if other parts of your system depend on these files.

You can use cards to create a visually pleasing page layout, combining text and images in a grid. They’re ideal for building landing pages or displaying any other content in a non-linear way.

Example of a card

Adding links

Adding images

This will open the Select file modal. Here you can drag and drop a new image into this, or use an image file you’ve previously uploaded to your space.

Choosing the right image size

GitBook will automatically crop landscape images to a 16:9 ratio on desktop and mobile. If the images you upload are portrait or have a 1:1 ratio, they will be cropped to 16:9 on desktop and display as square or portrait on mobile.

To keep things consistent across desktop and mobile, we recommend uploading all the images for your cards in a 16:9 format (e.g. 1920px x 1080px).

If you want your cards to adapt their layout depending on the screen size, we’d recommend uploading images with a 1:1 ratio, and the content of your image centered.

Changing the size of cards

Getting started

In the space you want to sync with your GitLab repo, head to the space menu in the top right, and select Synchronize with Git. From the provider list, select GitLab Sync, and click Configure.

Generate and enter your API access token

You can generate an API access token in your GitLab user settings.

Ensure that you enable the following access for your token:

• api

• read_repository

• write_repository

If the tokens you create also have a specific role attached to them, also make sure that it has a Maintainer or Admin role.

Then you can paste the token into the API access token field when configuring your GitLab integration.

Select a repository and branch

Select the repository you want to keep in sync with your GitBook content.

Once you’ve selected the correct repository, choose which branch you want commits to be pushed to and synced from.

Perform an initial sync

When syncing for the first time, you’ll have the option to sync in one of two directions:

1. GitBook -> GitLab will sync your space’s content to the selected branch. This is great if you’re starting from an empty repository and want to get your GitBook content in quickly.

2. GitLab -> GitBook will sync your space’s content from the selected branch. This is great if you have existing markdown content in a repository and want to bring it into GitBook.

Write and commit

When you edit on GitBook, every change request merge will result in a commit to your selected GitLab branch.

When you commit to GitLab, every commit will be synced to your GitBook space as a history commit.

You can easily monitor all the changes people have made to your content using to the Version history side panel.

Version history

In the Version history of a space, you can see a list of all the actions that changed the content within it. These include:

View historical versions of content

Show changes

To enable or disable this, use the Show changes toggle at the bottom of the Version history side panel.

With show changes enabled, content that has changed will be highlighted by an icon on the left of its content block.

Viewing historical published versions

If you're investigating the version history of a published space, you can also view previews of what the previous versions looked like in the published context (i.e. what the end user would see).

You can do this by:

Roll back to a previous version

Rolling back allows you to revert a space’s content to the way it was at a previous point in time. This is helpful if you’ve accidentally made a breaking change or deleted content and need to quickly get back to a previous version of the space.

GitBook does more than just render your OpenAPI spec. It lets you customize your API reference for better clarity, navigation, and branding.

Split operations across multiple pages

To keep your documentation organized, GitBook can split your API operations into separate pages. Each page is generated from a tag in your OpenAPI spec. To group operations into a page, assign the same tag to each operation:

Reorder pages in your table of contents

The order of pages in GitBook matches the order of tags in your OpenAPI tags array:

Nest pages into groups

To build multi-level navigation, use x-parent (or parent) in tags to define hierarchy:

The above example will create a table of contents that looks like:

If a page has no description, GitBook will automatically show a card-based layout for its sub-pages.

Customize page titles, icons, and descriptions

Build rich descriptions with GitBook Blocks

Highlight schemas

You can highlight a schema in a GitBook description by using GitBook markdown. Here is an example that highlights the “Pet” schema from the “petstore” specification:

To setup your GitBook site with authenticated access using Okta, the process looks as follows:

Create a new Okta application

First, sign in to Okta platform (the admin version) and create a new app integration (or use an existing one) by clicking the Applications button in the left sidebar.

Click Create App Integration and select OIDC - OpenID Connect as the Sign-In method. And then select Web Application as the application type.

Name it appropriately and don't edit any other setting on that page. For assignments, choose the appropriate checkbox. Click Save.

On the next screen, copy Client ID and Client Secret. Copy the Okta Domain right below your email address by clicking the dropdown in the top right.

We will need these values to configure the Okta Integration.

Install and configure the Okta integration

Install the integration on your site.

Upon installation on site, you will see a screen asking you enter the Client ID, Okta Domain, and Client Secret.

For Client ID, Okta Domain (remove https://prefix, if any) and Client Secret, paste in the value you copied from Okta Dashboard.

Click Save.

Copy the URL displayed in the modal and enter it as a Sign-In redirect URI in Okta (as shown in the below screenshot). Hit Save.

Now, in GitBook, close the integrations modal and click on the Manage site button. Navigate to Audience, select Authenticated access, and choose Okta as the backend. Then, click Update audience. Go to the site’s screen and click Publish. The site is now published behind authenticated access controlled by your Auth0 application. To try it out, click on Visit. You will be asked to sign in with Okta, which confirms that your site is published behind authenticated access using Auth0.

Configure Okta for adaptive content

We’re building features that make it easier for Large Language Models (LLMs) to ingest and work with your documentation content.

As LLMs become increasingly important for information retrieval and knowledge assistance, ensuring your documentation is LLM-friendly can significantly improve how these models understand and represent your products or services.

LLM-optimized documentation ensures that AI systems like ChatGPT, Claude, Cursor, and Copilot can retrieve and provide accurate, contextual responses about your product or API.

.md pages

With GitBook, all of the pages of your docs site are automatically available as markdown files. If you add the .md extension to any page, you will see the content of that page rendered in markdown which you can pass to an LLM for more efficient processing than an HTML file.

llms.txt

The llms.txt file serves as an index for your documentation site, providing a comprehensive list of all available markdown-formatted pages. With this file, you make it easier for LLMs to efficiently discover and process your documentation content.

llms-full.txt

Where the llms.txt file contains an index of all the page URLs and titles of of your documentation site, the llms-full.txt contains the full content of your documentation site in one file that can be passed to LLMs as context.

LLMs can use this index to navigate directly to the markdown versions of your pages, allowing them to incorporate your documentation into their context without needing to parse HTML.

Tips for optimizing your docs for LLMs

Now that your GitBook site automatically generates .md pages, llms.txt, and llms-full.txt files, these best practices will help LLMs effectively understand and work with your content.

By using these optimizations, you may also improve your documentation’s performance in AI-powered search engines and generative engine optimization (GEO).

The best part? These guidelines will generally make your docs easier for people to read as well.

Use clear, hierarchical structure

Break up your content with good headings (H1, H2, H3) and don’t just write giant walls of text. Bullet points, numbered lists and shorter paragraphs make everything easier to read.

Write concise, jargon-free content

Keep it simple and skip complex technical terms unless you really need them. LLMs do much better when you say what you mean without adding fluff.

Include practical examples

Show, don’t just tell. Code snippets, API examples, and real scenarios help LLMs — and your users — understand how things actually work in practice.

Keep content current and accurate

Nobody likes outdated docs. Regular updates mean LLMs won’t give people wrong information about your latest features and updates.

Test with AI tools

Actually try asking ChatGPT or Claude questions about your docs to see how well they understand your content. You might be surprised by what works and what doesn’t.

To setup your GitBook site with authenticated access using AWS Cognito, the process looks as follows:

Create a new AWS Cognito application

Go to your desired User Pool in Cognito, and click on App integration. Make a note of the Cognito domain, we will need it to configure the integration.

Scroll to the bottom and click "Create app client". For the app type, select "Confidential client." Scroll down to Hosted UI settings. In allowed Callback URLs, enter the Callback URL you got from GitBook upon installing the integration on a space.

Scroll further down to "OAuth 2.0 grant types"- make sure "Authorization code grant" is selected.

For "OpenID connect scopes", make sure OpenID is selected.

Scroll down and click "Create app client".

Click on the created app client and make a note of the Client ID and Client Secret.

Install and configure the AWS Cognito integration

Navigate to integrations within the GitBook app, select authenticated access as the category, and install the AWS Cognito integration.

Once you've installed it on your site, go to configuration and make a note of the Callback URL right above the Save button. We will need it to set up Cognito.

Open up the Cognito integration's configuration screen for the space you installed the integration on.

It should look like the following image:

For Client ID, Cognito Domain, and Client Secret, paste in the values you got from Cognito.

Hit Save.

Now, in GitBook, close the integrations modal and click on the Manage site button. Navigate to Audience, select Authenticated access, and choose Cognito as the backend. Then, click Update audience. Go to the site’s screen and click Publish. The site is now published behind authenticated access controlled by your Auth0 application. To try it out, click on Visit. You will be asked to sign in with Cognito, which confirms that your site is published behind authenticated access using Auth0.

Configure AWS Cognito for adaptive content

To leverage Adaptive Content with authenticated access in GitBook, you’ll need to configure your Amazon Cognito user pool to include custom claims in the ID token.

Here’s an example of what that could look like:

Once added, these key-value pairs are included in the authentication token and passed to GitBook, allowing your site to dynamically adapt its content based on the authenticated user’s profile.

Insights give you information on the content you've published and how it performs. It's split up between different sections — Traffic, Pages & feedback, Search, Ask AI, Links, and OpenAPI.

You can see a top-level overview of your insights on the Overview tab of your site’s dashboard, with a globe that shows views in the last hour by location.

Click the Insights tab in the site header to find more detailed insights for your site.

Filters & groups

You can add filters or group your data to view it in specific ways. For example, you could look at search data within a specific site section, or filter your traffic data by country, device, browser and more.

By combining filters and groups, you can drill down in to precise analytics data to track the events that you are important to you.

Types of data

The Insights tab is split into six sections, each focused on a specific data type.

Traffic

GitBook tracks page views to help you understand the popularity and reach of your content. Each time a user visits a page on your docs site, it is counted as a page view.

Page views are critical for assessing the effectiveness of your content strategy and optimizing your documentation based on user interest. It’s split up between different views and profiles, including countries, languages, browsers, and more.

Pages & Feedback

If you want to use or analyze this data further outside of GitBook, click Download CSV to download a .csv file to your device.

You can also see a list of comments left from visitors who rate your pages, to get actionable insights on how your docs can be improved.

Broken URLs

Broken URLs shows any incoming links from external sources that are resulting in a ‘Page not found’ error. These may be mistyped URLs, outdated links with no redirects, or spam links.

Search

You can measure and improve your documentation by checking which keywords are used the most by users searching your documentation. This view allows you to see what keywords are performing the best, and which ones you could improve on.

The information here can be helpful for informing your content architecture, making certain parts of your documentation easier to find without search, or adding additional content to existing pages based on what your visitors are searching for.

Ask AI

By looking at these queries, you can refine your documentation structure, enhance discoverability, and provide more relevant information to your audience.

Links

GitBook tracks links to help you understand how users interact with external resources in your documentation. This feature provides insights into external links, their domains, and their placement within your docs, such as in the header, footer, or sidebar. Analyzing link usage can help you optimize navigation, improve content accessibility, and refine your documentation strategy based on user engagement.

OpenAPI

It tracks interactions such as endpoint views, parameter searches, and request explorations, helping you understand which parts of your API are most accessed and where users may need more clarity. These insights enable you to refine your documentation, improve developer experience, and ensure your API content is effectively meeting user needs.

You can add code to your GitBook pages using code blocks.

A code block may be useful for:

• Sharing configurations

• Adding code snippets

• Sharing code files

• Showing usage examples of command line utilities

• Showing how to call API endpoints

• And much more!

Example of a code block

‌import * as React from 'react';
import ReactDOM from 'react-dom';
import App from './App';

ReactDOM.render(<App />, window.document.getElementById('root'));

Code block options

Set syntax…

You can set the syntax in your code block to any of the supported languages. This will enable syntax highlighting in that language, too.

// Some code

With line numbers

This will toggle line numbers for your code on and off.

Showing line numbers is useful when the code represents the contents of a file as a whole, or when you have long code blocks with lots of lines. Hiding line numbers is useful for snippets, usage instructions for command line or terminal expressions and similar scenarios.

With caption

This will toggle a caption that sits at the top of the block, above your lines of code.

Wrap code

This will toggle code wrapping on and off, so long lines of code will wrap to all be visible on the page at once.

Wrapping lines is useful when your code is long and you want to avoid having the viewer scroll back and forth to read it. If you toggle Wrap code on, you may also want to show line numbers — this will make it easier to read the code and understand where new lines start.

Code block actions

As well as the options above, you can also change the language the code block displays, and copy your code instantly.

Copy the code

Hover over a code block and a number of icons will appear. Click the middle icon to copy the contents of the code block to your clipboard.

Representation in Markdown

{% code title="index.js" overflow="wrap" lineNumbers="true" %}

```javascript
‌import * as React from 'react';
import ReactDOM from 'react-dom';
import App from './App';

ReactDOM.render(<App />, window.document.getElementById('root'));
```

{% endcode %}

If you’d like to configure Git Sync further, you can add a .gitbook.yaml file at the root of your repository to tell GitBook how to parse your Git repository.

root: ./

​structure:
  readme: README.md
  summary: SUMMARY.md​

redirects:
  previous/page: new-folder/page.md

Root

The path to lookup for your documentation defaults to the root directory of the repository. Here’s how you can tell GitBook to look into a ./docs folder:

root: ./docs/

​Structure‌

The structure accepts two properties:‌

• readme: Your documentation’s first page. Its default value is ./README.md

• summary: Your documentation’s table of contents. Its default value is ./SUMMARY.md

The value of those properties is a path to the corresponding files. The path is relative to the “root” option. For example, here’s how you can tell GitBook to look into a ./product folder for the first page and summary:

structure:
  readme: ./product/README.md
  summary: ./product/SUMMARY.md

Summary‌

The summary file is a Markdown file (.md) that should have the following structure:

‌# Summary​

## Use headings to create page groups like this one​

* [First page’s title](page1/README.md)
    * [Some child page](page1/page1-1.md)
    * [Some other child page](part1/page1-2.md)

* [Second page’s title](page2/README.md)
    * [Some child page](page2/page2-1.md)
    * [Some other child page](part2/page2-2.md)

## A second-page group​

* [Another page](another-page.md)

Providing a custom summary file is optional. By default, GitBook will look for a file named SUMMARY.md in your root folder if specified in your config file, or at the root of the repository otherwise.

If you don’t specify a summary, and GitBook does not find a SUMMARY.md file at the root of your docs, GitBook will infer the table of contents from the folder structure and the Markdown files below.‌

​Redirects

Redirects allow you to define redirects in your .gitbook.yaml configuration file. The path is relative to the “root” option. For example, here’s how you can tell GitBook to redirect users accessing a past url /help to a new url /support

root: ./

redirects:
  help: support.md

To start customizing your documentation experience for your readers, you'll need to enable adaptive content and decide how your visitor data is passed to GitBook. This lets your site's content dynamically adapt based on who's viewing it.

Enable adaptive content

Before you’re able to pass user data to GitBook, you’ll need to configure your site to use adaptive content.

Set your visitor schema

After enabling adaptive content, you’ll need to define a schema for the types of claims you expect GitBook to receive when a user visits your site.

The visitor schema should reflect how these claims are structured when sent to GitBook.

For example, if you expect a visitor to potentially be a beta user in your product, you would set a visitor schema similar to:

{
  "type": "object",
  "properties": {
    "isBetaUser": {
      "type": "boolean",
      "description": "Whether the visitor is a Beta user."
    }
  },
  "additionalProperties": false
}

{
  "type": "object",
  "properties": {
    "language": {
          "type": "string",
          "description": "The language of the visitor",
          "enum": [
            "en",
            "fr",
            "it"
          ]
  },
  "additionalProperties": false
}

{
  "type": "object",
  "properties": {
    "isBetaUser": {
      "type": "boolean",
      "description": "Whether the visitor is a Beta user."
    },
  },
  "additionalProperties": false
}

{
  // Top level claims
  "type": "object",
  "properties": {
    // Nested claims
    "access": {
      "type": "object",
      "description": "User’s access to product feature",
      "properties": {
        "isAlphaUser": {
          "type": "boolean",
          "description": "Whether the visitor is a Alpha user."
        },
        "isBetaUser": {
          "type": "boolean",
          "description": "Whether the visitor is a Beta user."
        },
      },
      "additionalProperties": false
    }
  },
  "additionalProperties": false
}

Set an unsigned claim

Unsigned claims are a specific type of claim that identifies claims coming through that might not be signed by a client application. It is required to set claims in your visitor schema as unsigned if you are passing claims through URL parameters, unsigned cookies, and feature flags.

If you intend to work with unsigned claims, you will need to declare the claims you are expecting in the schema under an “unsigned” prop alongside your signed claims.

{
  "type": "object",
  "properties": {
    "isBetaUser": {
      "type": "boolean",
      "description": "Whether the visitor is a Beta user."
    },
    // Add unsigned claims
    "unsigned": {
      "type": "object",
      "description": "Unsigned claims of the site visitor.",
      "properties": {
        "language": {
          "type": "string",
          "description": "The language of the visitor",
          "enum": [
            "en",
            "fr",
            "it"
          ]
        }
      },
      "additionalProperties": false
    }
  },
  "additionalProperties": false
}

Pass visitor data to GitBook

GitBook provides different ways to pass visitor data to adapt your site's content. After defining your schema, you’ll need to decide how you want to pass your visitor data to GitBook.

Choose your site’s search experience

GitBook sites offer different search experiences depending on what you want for your users:

• Keyword search – A standard search experience based on keywords. Automatically enabled on all sites.

• GitBook AI search – Users get short answers to questions directly from the search box.

• GitBook Assistant – Users get an advanced, interactive chat experience with GitBook’s AI agent.

To choose your site’s search experience, open your site’s dashboard, navigate to the Settings page and choose AI & MCP from the menu on the left. Here you can choose your preferred experience.

Searching published documentation

​Users can open the Ask or search… bar by pressing ⌘ + K on Mac or Ctrl + K on PC.

Your users can search for keywords within your docs site and jump quickly to specific pages or page sections across your entire site.

GitBook AI search

GitBook AI search offers basic AI-powered answers in the Search and find… bar of your site. It’s trained on the content of your docs site, but cannot pull in information from external sources.

Using GitBook AI search

If you have enabled GitBook AI search from your site’s settings page, your users can access it by asking a question directly in the Ask or search… bar at the top of the page.

They can open this by clicking it directly, or by pressing ⌘ + K on a Mac or Ctrl + K on a PC.

As well as a summarized answer, below your users will also see an expandable section that shows the sources that GitBook AI used to create its answer, plus related questions you can click as a follow-up.

GitBook Assistant

GitBook Assistant gives your users fast, accurate answers about your documentation using natural language. It’s embedded right into your docs site, so users can ask questions, request more information about the page they’re on, or get other contextual help.

The Assistant uses agentic retrieval to understand the context of the query based on the user’s current page, previously-read pages, and previous conversations they’ve had.

GitBook Assistant is trained on your documentation, but you can also add external sources to expand it’s context and knowledge and give better answers.

Using GitBook Assistant

Users can access GitBook Assistant in three ways:

• Press ⌘ + J on Mac or Ctrl + J on PC

• Type a question into the Ask or search… bar and choose the ‘Ask…’ option at the top of the menu.

Extend GitBook Assistant with MCP servers

You can also choose to add external data sources to GitBook Assistant to give it more context and data to pull answers from. You can do this by connecting Assistant to MCP servers for external platforms, such as:

• Your community (Slack, Discord, GitHub Communities etc)

• Support tools (Intercom etc)

• Your future product roadmap (GitHub, Linear etc)

• Docs for external integrations with products

To add an MCP server to GitBook Assistant, follow these steps:

FAQs

Integrating GitBook AI with your product

With our API, you can embed GitBook AI into your product or website! This opens up lots of possibilities, including in-app helpers and website chat bots that can respond to questions based on the content in your documentation.

To format your text, simply select the words you want and choose one of the formats from the context menu — or format your text using a keyboard shortcut or through Markdown syntax.

Bold

Keyboard shortcut: ⌘ + B

Italic

Keyboard shortcut : ⌘ + I

Strikethrough

Keyboard shortcut: ⇧ + ⌘ + S

Code

Keyboard shortcut: ⌘ + E

Link

Keyboard shortcut: ⌘ + K

Color and background color

Click the color icon in the context menu, and choose a color for the text or its background.

This text is orange.

This text background is orange.

Table of contents

Create a new page

Can’t see the option to create a new page?

Organizing your content

There are three ways to organize your content in the table of contents:

Pages