Skip to main content
This feature is available on Ultimate site plans.
When a user visits your site, you may already know things about them — such as who they are, which plan they’re subscribed to, and which features they have access to. Adaptive content helps to build a tailored documentation experience based on who is reading.

​
How it works

Adaptive content works in one of two 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.
Adaptive content is slightly different from authenticated access, although they can work together. While authenticated access allows you to protect your docs through a login, adaptive content customizes published material based on various authentication methods — including authenticated access or those from your own app.

​
What you can adapt

You can adapt and personalize many parts of your docs, including:
  • Hiding or showing pages
  • Hiding or showing site variants
  • Hiding or showing site sections
  • Hiding or showing header links
  • Adding personalized content to inline expressions

​
Working with the condition editor

The condition editor is where you’ll set the conditions for showing or hiding a page, variant, or section. After opening the condition editor, you’ll be able to write your condition as an expression that will run against data coming from visitors to your site.

​
Example

The data you pass through your users to GitBook is attached to an object called visitor.claims. Let’s take a look at an example if we want to write a conditional statement to only show a page for users who are part of a beta program: 
visitor.claims.isBetaUser == true
The expression above means that any user who matches this claim (i.e. isBetaUser is true in the user’s claim), will be able to see and access the page. Any user who does not match this claim (including visitors without any claims set), will not be able to see or access the page. The condition editor also comes built in with autocomplete, which suggests claims or attributes that have been found on previous visitors to your site, helping you craft the conditional statement for your pages, variants, or sections.

​
Conditional pages

To launch the condition editor for a page, head to the actions menu next to a page, and click Add condition. You can also launch the condition editor from a page’s options. You can see which pages in your space have conditions set if the page has a page condition icon next to it.

​
Conditional variants

To launch the condition editor for a variant, head to the actions menu next to a variant, and click Add condition. You can see which variants in your docs have conditions set if the variant has a page condition icon next to it.

​
Conditional sections

To launch the condition editor for a section, head to the actions menu next to a section, and click Add condition. You can see which sections in your docs have conditions set if the section has a page condition icon next to it.

​
Conditional page header links

To launch the condition editor for a page header link, head to the actions menu next to a header link, and click Add condition.

​
Inline expressions

In addition to controlling the visibility of content, you can also use claims inline using expressions, just like page and space variables. To reference a claim inline using an expression, type / in the editor, then select Expression. Claims will be accessible in the expression editor as properties on visitor.

​
Testing with segments

Segments represent mock user data that you can configure to test your conditions. For example, you could set up a segment that represents a developer on your enterprise plan, or a sign-in user on a free plan, and then see which pages would be visible to them.

​
Working with Git Sync

Conditions set in GitBook are synced through Git Sync and appear in the synced Markdown pages. This means blocks and pages with conditions set on their visibility are still visible in your synced repo. Data passed through claims is never visible in Markdown, and is securely passed to GitBook.

Build docs developers (and LLMs) love

Get started for freeTalk to us