Script tag
Add Docs Embed to any website with a simple script tag
Last updated
Was this helpful?
Add Docs Embed to any website with a simple script tag
Last updated
Was this helpful?
Was this helpful?
The quickest way to add Docs Embed to your website or app is by adding it through a "standalone" script tag. Every docs site in GitBook includes a ready-to-use script for embedding your docs as a widget.
Place this code in your HTML <head> or before the closing </body> tag:
<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>Add customization options before calling show():
<script src="https://docs.company.com/~gitbook/embed/script.js"></script>
<script>
window.GitBook('init', { siteURL: 'https://docs.company.com' });
window.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?']
});
window.GitBook('show');
</script>Use the API to show, hide, open, or close the embed:
<script>
// Show the widget
window.GitBook("show");
// Hide the widget
window.GitBook("hide");
// Open the embed window
window.GitBook("open");
// Close the embed window
window.GitBook("close");
// Toggle the embed window
window.GitBook("toggle");
</script>Use the API to navigate to pages, switch tabs, or post messages:
<script>
// Navigate to a specific page in the docs tab
window.GitBook('navigateToPage', '/getting-started');
// Switch to the assistant tab
window.GitBook('navigateToAssistant');
// Post a message to the chat
window.GitBook('postUserMessage', 'How do I get started?');
// Clear chat history
window.GitBook('clearChat');
</script>For authenticated docs or conditional loading, inject the script at runtime:
<script>
function loadGitBookEmbed() {
var script = document.createElement("script");
script.src = "https://docs.company.com/~gitbook/embed/script.js";
script.async = true;
script.onload = function () {
window.GitBook('init', { siteURL: 'https://docs.company.com' });
window.GitBook("show");
};
document.head.appendChild(script);
}
// Load when ready
loadGitBookEmbed();
</script>GitBook('init', options: { siteURL: string }, frameOptions?: { visitor?: {...} }) - Initialize widget with site URL and optional authenticated access
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
GitBook('postUserMessage', message: string) - Post a message to the chat
GitBook('clearChat') - Clear chat history
GitBook('configure', settings: {...}) - Configure widget settings (see Configuration section below)
GitBook('unload') - Completely remove the widget from the page
Configuration options are available via GitBook('configure', {...}):
tabsOverride which tabs are displayed. Defaults to your site's configuration.
Type: ('assistant' | 'docs')[]
Options:
['assistant', 'docs'] - Show both tabs
['assistant'] - Show only the assistant tab
['docs'] - Show only the docs tab
actionsCustom 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
greetingWelcome message displayed in the Assistant tab.
Type: { title: string, subtitle: string }
suggestionsSuggested questions displayed in the Assistant welcome screen.
Type: string[]
toolsCustom AI tools to extend the Assistant. See Creating custom tools for details.
Type: Array<{ name: string, description: string, inputSchema: object, execute: Function, confirmation?: {...} }>
buttonConfigure 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.
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
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.