@gitbook/embed

v0.2.1

Published

5 days ago

Embeddable components for GitBook

0High
0Medium
0Low

GitBook Docs Embed (`@gitbook/embed`)

Embed your GitBook docs in your product or website.

The Docs Embed can contain two tabs:

Assistant: The GitBook Assistant - an AI-powered chat interface to help users find answers
Docs: A browser for navigating your documentation site

The embed is set up automatically based on your site's configuration. You can optionally customize and override the configuration with custom actions, tools, suggested questions, Authenticated Access, and more. See the Configuration section for all available options.

Usage

As a standalone script from your docs site

All GitBook docs sites include a script to easily add the Docs Embed as a widget on your website.

The script is served at https://docs.company.com/~gitbook/embed/script.js.

You can find the embed script from your docs site settings, or you can copy the following and replace docs.company.com with your docs site hostname.

<script src="https://docs.company.com/~gitbook/embed/script.js"></script>
<script>
// Initialize with Authenticated Access (optional)
window.GitBook('init', 
    { siteURL: 'https://docs.company.com' },
    { visitor: { token: 'your-jwt-token' } }
);
window.GitBook('show');
</script>

The standalone script provides a global GitBook function. See the API Reference section for all available methods.

Example: Configuring the widget

GitBook('configure', {
    button: {
        label: 'Ask',
        icon: 'assistant' // 'assistant' | 'sparkle' | 'help' | 'book'
    },
    tabs: ['assistant', 'docs'],
    actions: [
        {
            icon: 'circle-question',
            label: 'Contact Support',
            onClick: () => window.open('https://support.example.com', '_blank')
        }
    ],
    greeting: { title: 'Welcome!', subtitle: 'How can I help?' },
    suggestions: ['What is GitBook?', 'How do I get started?'],
    tools: [/* ... */]
});

See the Configuration section for all available options.

As a package from NPM

Install the package: npm install @gitbook/embed and import it in your web application:

import { createGitBook } from '@gitbook/embed';

const gitbook = createGitBook({
    siteURL: 'https://docs.company.com'
});

// Create an iframe and get its URL
const iframe = document.createElement('iframe');
iframe.src = gitbook.getFrameURL({
    visitor: {
        token: 'your-jwt-token', // Optional: for Adaptive Content or Authenticated Access
        unsignedClaims: { // Optional: custom claims for dynamic expressions
            userId: '123',
            plan: 'premium'
        }
    }
});

// Create a frame client to communicate with the iframe
const frame = gitbook.createFrame(iframe);

// Use the frame client methods
frame.navigateToPage('/getting-started'); // Navigate to a page in the docs tab
frame.navigateToAssistant(); // Switch to the assistant tab
frame.postUserMessage('How do I get started?');
frame.clearChat();

// Configure the embed (see Configuration section for all options)
frame.configure({
    tabs: ['assistant', 'docs'],
    actions: [
        {
            icon: 'circle-question',
            label: 'Contact Support',
            onClick: () => window.open('https://support.example.com', '_blank')
        }
    ],
    greeting: { title: 'Welcome!', subtitle: 'How can I help?' },
    suggestions: ['What is GitBook?', 'How do I get started?'],
    tools: [/* ... */]
});

// Listen to events
frame.on('close', () => {
    console.log('Frame closed');
});

As React components

After installing the NPM package, you can import prebuilt React components:

import { GitBookProvider, GitBookFrame } from '@gitbook/embed/react';

<GitBookProvider siteURL="https://docs.company.com">
    <GitBookFrame
        visitor={{
            token: 'your-jwt-token', // Optional: for Adaptive Content or Authenticated Access
            unsignedClaims: { userId: '123' } // Optional: custom claims for dynamic expressions
        }}
        tabs={['assistant', 'docs']}
        greeting={{ title: 'Welcome!', subtitle: 'How can I help?' }}
        suggestions={['What is GitBook?', 'How do I get started?']}
        actions={[
            {
                icon: 'circle-question',
                label: 'Contact Support',
                onClick: () => window.open('https://support.example.com', '_blank')
            }
        ]}
        tools={[/* ... */]}
    />
</GitBookProvider>

You can also use the useGitBook hook to access the client:

import { useGitBook } from '@gitbook/embed/react';

function MyComponent() {
    const gitbook = useGitBook();
    const frameURL = gitbook.getFrameURL({ visitor: { token: '...' } });
    // ...
}

API Reference

Method Comparison

| Method | Standalone Script | NPM Package | React Components | |--------|------------------|-------------|------------------| | Initialize | GitBook('init', options, frameOptions) | createGitBook(options) | <GitBookProvider siteURL="..."> | | Get frame URL | ❌ (handled internally) | client.getFrameURL(options) | useGitBook().getFrameURL(options) | | Create frame client | ❌ (handled internally) | client.createFrame(iframe) | useGitBook().createFrame(iframe) | | Show/Hide widget | GitBook('show') / GitBook('hide') | ❌ | ❌ | | Open/Close window | GitBook('open') / GitBook('close') / GitBook('toggle') | ❌ | ❌ | | Navigate to page | GitBook('navigateToPage', path) | frame.navigateToPage(path) | Via frame client | | Navigate to assistant | GitBook('navigateToAssistant') | frame.navigateToAssistant() | Via frame client | | Post message | GitBook('postUserMessage', message) | frame.postUserMessage(message) | Via frame client | | Clear chat | GitBook('clearChat') | frame.clearChat() | Via frame client | | Configure | GitBook('configure', settings) | frame.configure(settings) | Props on <GitBookFrame> | | Event listeners | ❌ | frame.on(event, listener) | Via frame client | | Unload | GitBook('unload') | ❌ | ❌ |

Method Signatures

Standalone Script

GitBook('init', options: { siteURL: string }, frameOptions?: { visitor?: {...} }) - Initialize widget
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 page
GitBook('navigateToAssistant') - Navigate to assistant tab
GitBook('postUserMessage', message: string) - Post message to chat
GitBook('clearChat') - Clear chat history
GitBook('configure', settings: {...}) - Configure widget
GitBook('unload') - Unload widget

NPM Package

Client Factory:

createGitBook(options: { siteURL: string }) → GitBookClient
client.getFrameURL(options?: { visitor?: {...} }) → string
client.createFrame(iframe: HTMLIFrameElement) → GitBookFrameClient

Frame Client:

frame.navigateToPage(path: string) → void
frame.navigateToAssistant() → void
frame.postUserMessage(message: string) → void
frame.clearChat() → void
frame.configure(settings: Partial<GitBookEmbeddableConfiguration>) → void
frame.on(event: string, listener: Function) → () => void (unsubscribe)

React Components

Components:

<GitBookProvider siteURL: string> - Provider component
<GitBookFrame {...props}> - Frame component (accepts all config options as props)

Hooks:

useGitBook() → GitBookClient (must be used within <GitBookProvider>)

Configuration

Configuration options are available across usage methods as follows:

Standalone script: via GitBook('configure', {...})
NPM package: via frame.configure({...})
React components: via props on <GitBookFrame>