# Technical Documentation: GitbookIO/gitbook > ℹ️ **Provenance:** Multi-Tier Ingestion · [CodeWiki Reference](https://codewiki.google/github.com/GitbookIO/gitbook) ### Overview (`README.md`)

GitBook

GitBook

Docs - Community - Developer Docs - Changelog - Bug reports - Feature requests

Welcome to GitBook, the platform for managing technical knowledge for teams.

This repository contains the open source code used to render GitBook's published content.

GitBook Open Published Site

## Table of Contents - [Getting Started](#getting-started) - [Contributing](#contributing) - [Types of contributions](#types-of-contributions) - [Licensing](#license) - [Acknowledgements](#acknowledgements) - [Legacy GitBook](#legacy-gitbook-deprecated) ## Getting Started To run a local version of this project, please follow these simple steps. ### Prerequisites - Node.js (Version: >= 22.3) - Use nvm for easy Node management - [Bun](https://bun.sh/) (Version: >=1.2.15) - We use a text-based lockfile which isn't supported below 1.2.15 ### Set up 1. Clone the repo into a **public** GitHub repository. If you plan to distribute the code, keep the source code public to comply with GNU GPLv3. To clone in a private repository, acquire a [commercial license](https://www.gitbook.com/pricing). ``` git clone https://github.com/gitbookIO/gitbook.git ``` 2. Ensure you are using the project's version of `node`. Running `nvm use` will change your local version to the correct one. 3. Install the project's dependencies through Bun. ``` bun install ``` 4. Start your local development server. ``` bun dev ``` 6. Open a published GitBook space in your web browser, prefixing it with `http://localhost:3000/url`. examples: - http://localhost:3000/url/gitbook.com/docs - http://localhost:3000/url/open-source.gitbook.io/midjourney Any published GitBook site can be accessed through your local development instance, and any updates you make to the codebase will be reflected in your browser. ### CI and testing All pull-requests will be tested against both visual and performances testing to prevent regressions. ## Fonts and Icons GitBook Open uses fontawesome. For self-hosting and local development, for licensing reasons, only the icons from the free version should be used. ## Contributing GitBook's rendering engine is fully open source and built on top of [Next.js](https://nextjs.org/). Head to our [contributing guide](https://github.com/GitbookIO/gitbook/blob/main/.github/CONTRIBUTING.md) to learn how to report bugs and suggest changes. ### Types of contributions We encourage you to contribute to GitBook to help us build the best tool for documenting technical knowledge. If you're looking for some quick ways to contribute, continue reading to learn more about popular contributions. #### Translations The GitBook UI is rendered using a set of translation files found in [`packages/gitbook/src/intl/translations`](/packages/gitbook/src/intl/translations/). Spotted a wrong or missing translation? Open an issue and let us know. #### Bugs Encounter a bug? [Open an issue](https://github.com/GitbookIO/gitbook/issues/new/choose) with as much detail as you can. Clear reports help us fix things faster for everyone. ## Deployment > [!WARNING] > While it is possible to self-host this project, we do not recommend this unless you are certain this option fits your need. > > _Looking for a specific feature in GitBook? Head to our [contributing guide](https://github.com/GitbookIO/gitbook/blob/main/.github/CONTRIBUTING.md) to suggest it._ > > Self-hosting this project puts the responsibility of maintaining and merging future updates on **you**. We cannot guarantee support, maintenance, or updates to forked and self-hosted instances of this project. > > We want to make it as easy as possible for our community to collaborate and push the future of GitBook, which is why we encourage you to share your ideas with us instead of creating your own version. This project allows you to self-host the rendering portion of your GitBook published content. Self-hosting has pros and cons. On the pro side, you can customize the look and feel of your content, and better embed your documentation in your application. On the con side, you become responsible for the reliability of your published site, and keeping the renderer up-to-date with the changes made to the GitBook platform. ## License Distributed under the [GNU GPLv3 License](https://github.com/GitBookIO/gitbook/blob/main/LICENSE). If you plan to distribute the code, you must make the source code public to comply with the GNU GPLv3. To clone in a private repository, acquire a [commercial license](https://www.gitbook.com/pricing). See `LICENSE` for more information. ## Badges

```md [](https://www.gitbook.com/preview?utm_source=gitbook_readme_badge&utm_medium=organic&utm_campaign=preview_documentation&utm_content=link) ``` ```html ``` ## Acknowledgements GitBook wouldn't be possible without these projects: - [Next.js](https://nextjs.org/) - [Bun](https://bun.sh/) - [Tailwind CSS](https://tailwindcss.com/) - [Framer Motion](https://www.npmjs.com/package/framer-motion) ## Contributors ## Legacy GitBook (Deprecated) Our previous version of GitBook and it's CLI tool are now deprecated. You can still view the old repository and it's commits on this [branch](https://github.com/GitbookIO/gitbook/tree/legacy). --- ### Overview (`.changeset/README.md`) # Changesets Hello and welcome! This folder has been automatically generated by `@changesets/cli`, a build tool that works with multi-package repos, or single-package repos to help you version and publish your code. You can find the full documentation for it [in our repository](https://github.com/changesets/changesets) We have a quick list of common questions to get you started engaging with this project in [our documentation](https://github.com/changesets/changesets/blob/main/docs/common-questions.md) --- ### Overview (`packages/browser-types/README.md`) # `@gitbook/browser-types` Typescript types for the global variables available in a GitBook website. These types can be used by integrations embedding scripts. --- ### Overview (`packages/cache-tags/README.md`) # `@gitbook/cache-tags` Utility to generate cache tags for GitBook Open. --- ### Overview (`packages/colors/README.md`) # `@gitbook/colors` A set of default colors and transformation functions used throughout the GitBook Open and app. --- ### Overview (`packages/embed/README.md`) # GitBook Docs Embed (`@gitbook/embed`) Embed your GitBook docs in your product or website. The Docs Embed can contain three tabs: - **Assistant**: The [GitBook Assistant](https://gitbook.com/docs/publishing-documentation/gitbook-ai-assistant) - an AI-powered chat interface to help users find answers - **Search**: A search-focused surface for quickly finding pages and asking scoped questions - **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](https://gitbook.com/docs/publishing-documentation/authenticated-access), and more. See the [Configuration](#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. ```html ``` The script initializes the widget itself, so there is nothing to call. To pin the embed to one color scheme, put it on the script URL — it has to be known before the widget renders: ```html ``` To authenticate the visitor, call `init` with their token. Keep tokens out of the script URL: it is publicly cacheable and ends up in server logs. ```html ``` The standalone script provides a global `GitBook` function. See the [API Reference](#api-reference) section for all available methods. ### Example: Configuring the widget ```javascript GitBook('configure', { button: { label: 'Ask', icon: 'assistant' // 'assistant' | 'sparkle' | 'help' | 'book' }, tabs: ['assistant', 'search', 'docs'], defaultPage: '/getting-started', 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 Assistant', suggestions: ['What is GitBook?', 'How do I get started?'], tools: [/* ... */], closeButton: true, }); ``` See the [Configuration](#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: ``` /* Detailed source-code truncated for AI context efficiency. */ ``` ## As React components After installing the NPM package, you can import prebuilt React components: ```tsx import { GitBookProvider, GitBookFrame } from '@gitbook/embed/react'; window.open('https://support.example.com', '_blank') } ]} tools={[/* ... */]} closeButton /> ``` You can also use the `useGitBook` hook to access the client: ```tsx import { useGitBook } from '@gitbook/embed/react'; function MyComponent() { const gitbook = useGitBook(); const frameURL = gitbook.getFrameURL({ colorScheme: 'dark', visitor: { token: '...' } }); // ... } ``` # API Reference ## Method Comparison | Method | Standalone Script | NPM Package | React Components | |--------|------------------|-------------|------------------| | **Initialize** | `GitBook('init', options, frameOptions)` | `createGitBook(options)` | `` | | **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 `` | | **Event listeners** | ❌ | `frame.on(event, listener)` | Via frame client | | **Unload** | `GitBook('unload')` | ❌ | ❌ | ## Method Signatures ### Standalone Script - `GitBook('init', options: { siteURL: string }, frameOptions?: { colorScheme?: 'light' | 'dark', 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 (accepts the page path within the site, an absolute path, or the full published URL; resolves pages in any space/section) - `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?: { colorScheme?: 'light' | 'dark', visitor?: {...} })` → `string` - `client.createFrame(iframe: HTMLIFrameElement)` → `GitBookFrameClient` **Frame Client:** - `frame.navigateToPage(path: string)` → `void` (accepts the page path within the site, an absolute path, or the full published URL; resolves pages in any space/section) - `frame.navigateToAssistant()` → `void` - `frame.postUserMessage(message: string)` → `void` - `frame.clearChat()` → `void` - `frame.configure(settings: Partial)` → `void` - `frame.on(event: string, listener: Function)` → `() => void` (unsubscribe) ### React Components **Components:** - `` - Provider component - `` - Frame component (accepts all config options as props) **Hooks:** - `useGitBook()` → `GitBookClient` (must be used within ``) # 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 `` ### `tabs` Available in: Standalone script, NPM package, React components Override which tabs are displayed. Defaults to your site's configuration. - **Type**: `('assistant' | 'search' | 'docs')[]` ```javascript tabs: ['assistant', 'search', 'docs'] ``` ### `defaultTab` Available in: Standalone script, NPM package, React components The tab the embed opens on. Without it, the embed opens on `defaultPage` if set, otherwise on the assistant (or the docs when the assistant isn't available). The tab must be one of the enabled `tabs`. - **Type**: `'assistant' | 'search' | 'docs'` ```javascript tabs: ['assistant', 'search', 'docs'], defaultTab: 'search' ``` `defaultTab` and `defaultPage` apply when the embed first loads: the standalone widget keeps its place when it is closed and reopened. To move it later, use `navigateToPage` or `navigateToAssistant`. ### `defaultPage` Available in: Standalone script, NPM package, React components The page the docs tab opens on, in place of your site's home page. Accepts the same references as `navigateToPage`: the page's path within the site, an absolute path, or its full published URL. Unless `defaultTab` says otherwise, the embed opens on this page. - **Type**: `string` ```javascript defaultPage: '/getting-started/quickstart' ``` ### `closeButton` Available in: Standalone script, NPM package, React components Display a close (`x`) button in the embed sidebar. - **Type**: `boolean` - **Default**: `false` ```javascript closeButton: true ``` Behavior: - When clicked, the embed sends a `close` event to the parent page. - In the standalone script, this event is handled automatically and the widget closes. - In custom iframe integrations (NPM package), you must listen for the `close` event and decide how to hide/collapse your UI. - In React, this works automatically when using the standard widget flow. If you build custom frame wiring, handle `close` the same way as the NPM package. NPM package example: ```typescript const frame = gitbook.createFrame(iframe); frame.configure({ closeButton: true }); const unsubscribe = frame.on('close', () => { // Hide your modal/drawer/container container.classList.add('hidden'); }); ``` Notes: - The close button is rendered in the same sidebar area as tabs/actions. - If your UI hides that sidebar or doesn't render it, the button will not be visible. ### `trademark` Available in: Standalone script, NPM package, React components Display GitBook branding in the embed. Defaults to true. - **Type**: `boolean` - **Default**: `true` ```javascript trademark: true ``` ### `actions` Available in: Standalone script, NPM package, React components Custom action buttons rendered in the sidebar alongside tabs. Each action button triggers a callback when clicked. **Note**: This prop was previously named `buttons`. Use `actions` instead, it has the same functionality. - **Type**: `GitBookEmbeddableActionDefinition[]` - **Properties**: - `icon`: `string` - Icon name. Any [FontAwesome icon](https://fontawesome.com/search) is supported. (e.g., `'rocket'`, `'comments'`, `'user-circle'`, ...) - `label`: `string` - Button label text - `onClick`: `() => void | Promise` - Callback function when clicked ```javascript actions: [ { icon: 'comments', label: 'Contact Support', onClick: () => window.open('https://support.example.com', '_blank') }, { icon: 'rocket', label: 'Get started', onClick: () => { GitBook('navigateToPage', '/getting-started'); } } ] ``` ### `greeting` Available in: Standalone script, NPM package, React components Welcome message displayed in the [Assistant](https://gitbook.com/docs/publishing-documentation/gitbook-ai-assistant) tab. - **Type**: `{ title: string, subtitle: string }` ```javascript greeting: { title: 'Welcome!', subtitle: 'How can I help you today?' } ``` ### `assistantName` Available in: Standalone script, NPM package, React components Override the assistant name displayed in the chat header and assistant entry points (for example, sidebar tabs and action labels). This name will be limited to 32 characters to prevent text overflow. - **Type**: `string` ```javascript assistantName: 'Support Assistant' ``` ### `suggestions` Available in: Standalone script, NPM package, React components Suggested questions displayed in the [Assistant](https://gitbook.com/docs/publishing-documentation/gitbook-ai-assistant) welcome screen. - **Type**: `string[]` ```javascript suggestions: [ 'What is GitBook?', 'How do I get started?', 'What can you do?' ] ``` ### `tools` Available in: Standalone script, NPM package, React components Custom AI tools to extend the [Assistant](https://gitbook.com/docs/publishing-documentation/gitbook-ai-assistant). Tools allow the assistant to execute functions and integrate with your own systems. **Note**: In addition to custom tools, the Assistant will always have access to any [MCP servers you define](https://gitbook.com/docs/publishing-documentation/gitbook-ai-assistant#extend-gitbook-assistant-with-mcp-servers) in your site's AI settings. - **Type**: `GitBookToolDefinition[]` - **Properties**: - `name`: `string` - Unique tool identifier - `description`: `string` - Description of what the tool does (used by the AI to decide when and how to use it). - `inputSchema`: `object` - JSON schema defining the tool's input parameters - `execute`: `(input: object) => Promise<{ output: any, summary: string }>` - Async function that executes the tool. - `output`: The result of the tool execution, provided to the AI to continue working with. Not shown to the user. - `summary`: The visual summary of the tool execution, shown in the user's chat window. - `confirmation`: `{ icon?: string, label: string }` (optional) - Confirmation button shown before execution, useful for actions that require the user's express approval. ``` /* Detailed source-code truncated for AI context efficiency. */ ``` ### `visitor` (Authenticated Access) Available in: Standalone script (via `init`), NPM package (via `getFrameURL()`), React components (as prop) [Authenticated Access](https://gitbook.com/docs/publishing-documentation/authenticated-access) options passed when creating the frame URL. Used for [Adaptive Content](https://gitbook.com/docs/publishing-documentation/adaptive-content) and [Authenticated Access](https://gitbook.com/docs/publishing-documentation/authenticated-access). **Note**: This is not a configuration option but rather a parameter when initializing the frame or creating the frame URL. **Standalone script**: Pass as the second argument to `GitBook('init', options, frameOptions)` **NPM package**: Pass to `getFrameURL({ visitor: {...} })` **React components**: Pass as the `visitor` prop on `` - **Type**: `{ token?: string, unsignedClaims?: Record }` - **Properties**: - `token`: `string` (optional) - Signed JWT token for [Adaptive Content](https://gitbook.com/docs/publishing-documentation/adaptive-content) or [Authenticated Access](https://gitbook.com/docs/publishing-documentation/authenticated-access) - `unsignedClaims`: `Record` (optional) - Unsigned claims that can be used in dynamic expressions via `visitor.claims.unsigned.` ```javascript visitor: { token: 'your-jwt-token', unsignedClaims: { userId: '123', plan: 'premium', role: 'admin' } } ``` ### `colorScheme` Available in: Standalone script (via `init`), NPM package (via `getFrameURL()`), React components (as prop) Override the embed's color scheme. When omitted, the standalone widget follows the page it is embedded in — its `color-scheme`, falling back to the visitor's OS preference only when that page declares support for both. With the NPM package or the React components you own the iframe, so the embed follows the visitor's OS preference unless you pass this. **Note**: This is not a configuration option but rather a parameter when initializing the frame or creating the frame URL. **Standalone script**: `?theme=light` on the script URL **NPM package**: Pass to `getFrameURL({ colorScheme: 'dark' })` **React components**: Pass as the `colorScheme` prop on `` - **Type**: `'light' | 'dark'` ```html ``` Sites published with a single theme always render in that theme, so `colorScheme` has no effect on them — the widget follows the site instead, to keep its chrome and the docs inside it consistent. ### `button` Available in: Standalone script only Configure the widget button for the standalone script. This option is not available when using the NPM package or React components, since they can be customized completely. - **Type**: `{ label: string, icon: 'assistant' | 'sparkle' | 'help' | 'book' }` - **Properties**: - `label`: `string` - Button label text - `icon`: `'assistant' | 'sparkle' | 'help' | 'book'` - Icon displayed on the button. Choose from one of 4 presets. ```javascript button: { label: 'Ask', icon: 'assistant' } ``` --- ### Overview (`packages/expr/README.md`) # `@gitbook/expr` Safely evaluate & parse user-defined GitBook expressions. --- ### Overview (`packages/fonts/README.md`) # `@gitbook/fonts` Utilities to lookup default fonts supported by GitBook. --- ### Overview (`packages/icons/README.md`) # `@gitbook/icons` Icon sets useed in GitBook content. ## Usage ```tsx import { Icon } from '@gitbook/icons'; ; ``` --- ### Overview (`packages/openapi-parser/README.md`) # `@gitbook/openapi-parser` Modern OpenAPI parser written in TypeScript with support for OpenAPI 3.1, OpenAPI 3.0 and Swagger 2.0. --- ### Overview (`packages/react-math/README.md`) # `@gitbook/react-math` React component to render a Math formula. It uses KaTeX when possible and fallbacks to MathJaX if needed. --- ### Overview (`packages/react-openapi/README.md`) # `@gitbook/react-openapi` Style-less React components to render OpenAPI operation blocks. --- --- METRICS --- - Files Extracted: 12 - Estimated Token Budget: ~6704 tokens - Canonical Reference: https://codewiki.google/github.com/GitbookIO/gitbook