Script tag

Learn how to add the Docs Embed widget to any website or web app using a single script tag

The simplest way to add Docs Embed to your website or app is with a standalone script that you include in your HTML. Each GitBook docs site provides a ready-to-use embed script that loads the widget automatically and connects it to your docs. This page tells you how to do that.

No SDK, build step, or framework integration is required. Just include the script and the widget appears on your page.

Get started

Copy your embed script URL

Navigate to your docs site in the GitBook app, navigate to the Settings tab and then to AI & MCP and copy the embed script URL.

You can also build it manually:

https://YOUR_DOCS_DOMAIN/~gitbook/embed/script.js

Replace your YOUR_DOCS_DOMAIN with your real docs site’s domain.

Add the script to your HTML

Add the following tag in your page HTML. Put it inside <head> or just before </body>.

<script src="https://YOUR_DOCS_DOMAIN/~gitbook/embed/script.js"></script>
<script>window.GitBook('show');</script>

If your docs require authentication

If your docs are behind auth, the script must include a signed JWT token.

Append it as a query parameter:

<script src="https://YOUR_DOCS_DOMAIN/~gitbook/embed/script.js?jwt_token=YOUR_TOKEN"></script>

Verify

Reload your page.

The widget should appear in the bottom right corner.

Optionally configure the embed

You can customize the widget before displaying it. Call configure after loading the script and before calling window.GitBook('show').

<script src="https://YOUR_DOCS_DOMAIN/~gitbook/embed/script.js"></script>
<script>
  window.GitBook('configure', {
    button: {
      label: 'Ask',
      icon: 'assistant' // assistant | sparkle | help | book
    },
    trademark: false,
    tabs: ['assistant', 'search', 'docs'],
    actions: [
      {
        icon: 'circle-question',
        label: 'Contact support',
        onClick: () => window.open('https://support.example.com', '_blank')
      }
    ],
    greeting: {
      title: 'Welcome',
      subtitle: 'How can I help?'
    },
    assistantName: 'Support Copilot',
    closeButton: true,
    suggestions: [
      'What is GitBook?',
      'How do I get started?'
    ]
  });

  window.GitBook('show');
</script>

Using this method, you can customize the:

Button label and icon
Visible tabs inside the widget
Custom action buttons
Greeting title and subtitle
Assistant name shown in the UI
Close button inside the Assistant
Suggested prompts shown to users.

Search is enabled by default. If you set tabs, list every tab you want to keep.

Set the color scheme

By default, the embed follows the iframe's CSS color-scheme. This lets it inherit your app theme or the browser preference automatically.

If you want to force a mode, initialize the embed and pass colorScheme in frameOptions:

<script src="https://YOUR_DOCS_DOMAIN/~gitbook/embed/script.js"></script>
<script>
  window.GitBook(
    'init',
    { siteURL: 'https://YOUR_DOCS_DOMAIN' },
    { colorScheme: 'dark' }
  );

  window.GitBook('show');
</script>

Use this pattern when you need frame-level options such as colorScheme or visitor.

You can control visibility and state at runtime through the API.

<script>
  // Make the widget visible
  window.GitBook('show');

  // Remove the widget from the page
  window.GitBook('hide');

  // Open the widget panel
  window.GitBook('open');

  // Close the widget panel
  window.GitBook('close');

  // Toggle open or closed
  window.GitBook('toggle');
</script>

This is useful when you want to connect the widget to your own UI triggers.

Navigate and interact programmatically

You can drive the widget from your code to navigate, switch tabs, or send messages.

<script>
  // Open a specific docs page inside the widget
  window.GitBook('navigateToPage', '/getting-started');

  // Switch to the assistant tab
  window.GitBook('navigateToAssistant');

  // Send a user message to the assistant
  window.GitBook('postUserMessage', 'How do I get started?');

  // Clear the current chat history
  window.GitBook('clearChat');
</script>

Typical uses for this functionality include:

Adding a deep link to a docs page from your app
Pre-filling a question
Resetting the conversation between flows

Load the embed script dynamically

If you only want to load the widget conditionally, or you need to attach an auth token at runtime, inject the script programmatically.

<script>
  function loadGitBookEmbed() {
    var token = "" // Fill it with your JWT token if your site requires an auth
    var script = document.createElement('script');
    script.src = 'https://YOUR_DOCS_DOMAIN/~gitbook/embed/script.js'
      + token ? '?jwt_token=' + encodeURIComponent(token) : ';
    script.async = true;
    script.onload = function () {
      window.GitBook('show');
    };
    document.head.appendChild(script);
  }

  loadGitBookEmbed();
</script>

Use this pattern when the widget should load only after user action or feature flags

API Reference

Initialization

GitBook('init', options: { siteURL: string }, frameOptions?: { visitor?: {...}, colorScheme?: 'light' | 'dark' }) - Initialize widget with site URL and optional frame options

GitBook('show') - Show widget button
GitBook('hide') - Hide widget button
GitBook('open') - Open widget window
GitBook('close') - Close widget window
GitBook('toggle') - Toggle widget window

GitBook('navigateToPage', path: string) - Navigate to a specific page in the docs tab
GitBook('navigateToAssistant') - Navigate to the assistant tab

Chat

GitBook('postUserMessage', message: string) - Post a message to the chat
GitBook('clearChat') - Clear chat history

Configuration

GitBook('configure', settings: {...}) - Configure widget settings (see Configuration section below)
GitBook('unload') - Completely remove the widget from the page

Configuration Options

`GitBook('configure')`

Most configuration options are available via GitBook('configure', {...}):

`tabs`

Override which tabs are displayed.

Search is enabled by default. If you set tabs, the embed shows only the tabs you list.

Type: ('assistant' | 'search' | 'docs')[]
Options:
- ['assistant', 'search', 'docs'] - Show all tabs
- ['search', 'docs'] - Show search and docs only
- ['docs'] - Show only the docs tab

`actions`

Custom action buttons rendered in the sidebar alongside tabs. Each action button triggers a callback when clicked.

Note: This was previously named buttons. Use actions instead.

Type: Array<{ icon: string, label: string, onClick: () => void }>
Properties:
- icon: string - Icon name. Any FontAwesome icon is supported
- label: string - Button label text
- onClick: () => void | Promise<void> - Callback function when clicked

`greeting`

Welcome message displayed in the Assistant tab.

Type: { title: string, subtitle: string }

`assistantName`

Override the assistant name shown in the UI.

Type: string
Max length: 32 characters
Example:

window.GitBook('configure', {
  assistantName: 'Support Copilot'
});

`closeButton`

Display a close button inside the Assistant.

Type: boolean
Example:

window.GitBook('configure', {
  closeButton: true
});

`suggestions`

Suggested questions displayed in the Assistant welcome screen.

Type: string[]

`trademark`

Show or hide the GitBook trademark in the embed UI — including the Docs Embed footer and Assistant branding.

Type: boolean
Default: true
Example:

window.GitBook('configure', {
  trademark: false
});

`tools`

Custom AI tools to extend the Assistant. See Creating custom tools for details.

Type: Array<{ name: string, description: string, inputSchema: object, execute: Function, confirmation?: {...} }>

`button`

Configure the widget button that launches the embed (standalone script only). This allows you to customize the label and icon of the button that appears in the bottom-right corner of your page.

Type: { label: string, icon: 'assistant' | 'sparkle' | 'help' | 'book' }
Properties:
- label: string - The text displayed on the button
- icon: 'assistant' | 'sparkle' | 'help' | 'book' - The icon displayed on the button
  - assistant - Assistant icon
  - sparkle - Sparkle icon
  - help - Help/question icon
  - book - Book icon

Example:

window.GitBook('configure', {
  button: {
    label: 'Ask',
    icon: 'assistant'
  }
});

Note: This option is only available when using the standalone script tag implementation. For React or Node.js implementations, you'll need to create your own button to trigger the embed.

`frameOptions`

Some options are set on the frame instead of as configuration. Pass them in frameOptions when calling GitBook('init', options, frameOptions).

`colorScheme`

Override the embed color scheme.

When omitted, the embed follows the iframe's CSS color-scheme, which lets it inherit the parent page or browser preference.

Type: 'light' | 'dark'
Example:

window.GitBook(
  'init',
  { siteURL: 'https://docs.company.com' },
  { colorScheme: 'dark' }
);

`visitor` (Authenticated Access)

Pass when initializing with GitBook('init', options, frameOptions). Used for Adaptive Content and Authenticated Access.

Type: { token?: string, unsignedClaims?: Record<string, unknown> }
Properties:
- token: string (optional) - Signed JWT token
- unsignedClaims: Record<string, unknown> (optional) - Unsigned claims for dynamic expressions

Common pitfalls

Script URL is incorrect – Ensure you're using your actual docs URL, not the example docs.company.com.
Calling GitBook before script loads – Wrap API calls in script.onload or place them after the script tag.
Authenticated docs not accessible – If your docs require sign-in, you must provide the visitor.token when initializing. See Using with authenticated docs.
CORS or CSP errors – Ensure your site's Content Security Policy allows loading scripts and iframes from your GitBook domain.
Widget not visible – Check z-index conflicts with other elements on your page. The widget uses a high z-index by default.
Forgetting to initialize – Make sure to call GitBook('init', { siteURL: '...' }) before using other methods.

Last updated 2 months ago

Was this helpful?

Script tag

Get started

Copy your embed script URL

Add the script to your HTML

If your docs require authentication

Verify

Optionally configure the embed

Set the color scheme

Control widget visibility

Navigate and interact programmatically

Load the embed script dynamically

API Reference

Initialization

Widget Control

Navigation

Chat

Configuration

Configuration Options

`GitBook('configure')`

`tabs`

`actions`

`greeting`

`assistantName`

`closeButton`

`suggestions`

`trademark`

`tools`

`button`

`frameOptions`

`colorScheme`

`visitor` (Authenticated Access)

Common pitfalls

Get started

Copy your embed script URL

Add the script to your HTML

If your docs require authentication

Verify

Optionally configure the embed

Set the color scheme

Control widget visibility

Navigate and interact programmatically

Load the embed script dynamically

API Reference

Initialization

Widget Control

Navigation

Chat

Configuration

Configuration Options

GitBook('configure')

tabs

actions

greeting

assistantName

closeButton

suggestions

trademark

tools

button

frameOptions

colorScheme

visitor (Authenticated Access)

Common pitfalls

`GitBook('configure')`

`tabs`

`actions`

`greeting`

`assistantName`

`closeButton`

`suggestions`

`trademark`

`tools`

`button`

`frameOptions`

`colorScheme`

`visitor` (Authenticated Access)