Gitbook Integration

The GitBook integration connects your GitBook knowledge base to the Userlane Assistant, so your users find answers from your GitBook articles without leaving the application they work in. GitBook results appear alongside your Guides and Announcements, each marked with a document icon.

Before you start

You need:

• A GitBook account that can read the published site you want to connect

• The Admin or Moderator role in Userlane

The integration can read whatever the GitBook user who creates the API token can read. We recommend creating a dedicated GitBook user for the integration, with read access to only the content you want users to search, before you generate the token.

Connect GitBook to Userlane

1. In GitBook, sign in as the user for the integration and create an API token in your account's Developer settings, following GitBook's API authentication guide. Keep the token private, as you would a password.

2. Collect three details from GitBook:

   • Published site URL: the public address of your docs site, for example https://yourworkspace.gitbook.io/your-docs/.

   • Organization ID: open any space in the GitBook app: the ID is the part of the URL after /o/, for example app.gitbook.com/o/<organization ID>/.

   • Site ID: the ID of your published site, which starts with site_. Open the site in the GitBook app: the ID is the part of the URL after /sites/.

3. In the Userlane Portal, go to Account > Global Settings > Integrations.

4. Under Available integrations, select GitBook.

5. In the Connect to GitBook window, enter:

   • Name: how the integration appears in Userlane. It defaults to GitBook.

   • GitBook published site URL

   • Organization ID

   • Site ID

   • API token

6. Select Save and Connect. The connection appears under Connected integrations. If the connection fails, an error message explains why.

Turn on GitBook search for an application

1. Optional: before you turn on search, customize or translate the search filter and preview texts. Go to Customize > Texts, then select Search under Assistant.

2. Go to Customize > Search and make sure Display Search In The Assistant is on.

3. Under Activate Knowledge Base Search, turn on GitBook. If you renamed the integration, it appears under that name.

4. Repeat steps 2 and 3 for each application where you want GitBook search.

5. Test the integration: open an application where GitBook search is on, open the Assistant, select Search, and enter a term that appears in your GitBook content. Test before you announce the feature to your users.

How it works

When a user searches in the Assistant, Userlane searches your Userlane content and your connected GitBook site together. GitBook search covers the titles and text of the published pages on the site, and returns the most relevant pages first.

Users can filter results by content type. Selecting a GitBook result opens the article in a preview window, which users can minimize and pin to the screen while they keep working. To read a long article in full, users can open the original page in GitBook in a new tab.

Good to know

• Live results: Userlane searches GitBook each time a user searches, through GitBook's search API. Userlane does not copy or index your GitBook content, so results can differ from GitBook's own search.

• Published pages only: draft changes and unpublished pages don't appear in results.

• Access to originals: opening the original page in GitBook may require users to sign in to GitBook, depending on how the site is shared.

• If results stop appearing: check that the API token is still valid and that its GitBook user can still read the site. If you replace the token, update it under Account > Global Settings > Integrations.