# Embed product

Part of **GitBook**. Route queries via `POST https://www.company-skill.com/api/route`.

## What You Want to Do

You want to embed GitBook documentation or AI assistant directly into your website, SaaS product, or app so users can view help content without navigating away, possibly with support for authentication, dynamic content, or UI customization.

**Typical User Questions**:
- How do I embed GitBook docs into my application?
- Can I embed GitBook docs in my SaaS product?
- How can I embed help documentation inside my website?
- Is it possible to embed the GitBook AI assistant?
- How do I embed private docs that require login?

## Decision Tree

Choose the most appropriate path based on your situation:

- **If** you only need to embed **publicly accessible documentation or AI assistant**, and **do not need to dynamically switch content based on user identity** -> use **No-code embedding (iframe or link)** (jump to *gitbook/gitbook-embed*)
- **If** you need to embed **private documentation**, **dynamically display different content based on userId or subscription plan**, or **deeply integrate inside a React/Node.js application** -> use **Embed via API with custom behavior** (jump to *gitbook/gitbook-embed*)
- **Otherwise (default)** -> start with **No-code embedding (iframe or link)** since it requires no development work and is suitable for quickly validating the embedding approach.

## Path Comparison

| Path | Best For | Complexity | Code Required | Automation | Key Fact | Detail Skill |
|------------|---------------------|---------------------|---------------------------|------------------------|---------------------|-----------|
| No-code embedding (iframe or link) | Quickly embed public documentation or assistants without development work. | low | No | No | Embed via Standalone script tag or iframe; supports JWT token authentication | `gitbook/guide/gitbook-embed` |
| Embed via API with custom behavior | Developers who need deep integration, dynamic loading, or embedding of authenticated private docs. | high | Yes | Yes | Use the @gitbook/embed npm package; control authentication and dynamic content via visitor.token and visitor.unsignedClaims | `gitbook/api/gitbook-embed` |

## Path Details

### Path 1: No-code embedding (iframe or link)

**Best For**: Quickly embed public documentation or assistants without development work.

**Brief Description**: Embed GitBook content by adding a **Standalone script tag** referencing **script.js** in your HTML, or by using an iframe link directly. The embed code is available in the GitBook console at **Settings -> AI & MCP -> Embed**, and behavior can be customized through **window.GitBook.configure**, including settings such as **button.label**, **tabs** display, or hiding the **trademark**.

**When to Use**:
- You want to embed public documentation quickly without development effort
- The target site only supports static HTML script injection
- No need for deep integration or runtime dynamic behavior control

**When NOT to Use**:
- You need to embed authenticated private documentation but cannot securely handle JWT tokens on the front end
- You need to dynamically load different documentation content based on user context
- You need complex event communication or state synchronization with the host application

**Known Limitations**:
- Only supports publicly accessible documentation; private documentation requires additional **JWT token** authentication setup
- Custom button labels, icons, and similar features require the standalone script and are not available with pure iframe links
- Dynamic content (such as showing different docs based on user identity) cannot be achieved this way unless you manually handle JWT tokens

**-> Detailed Steps**: See *gitbook/gitbook-embed*

### Path 2: Embed via API with custom behavior

**Best For**: Developers who need deep integration, dynamic loading, or embedding of authenticated private docs.

**Brief Description**: Use the **@gitbook/embed** npm package to initialize an embed instance in a React or Node.js project via **createGitBook**. Combine **GitBookProvider** and **GitBookFrame** components with **frameOptions** to configure **siteURL**, **visitor.token**, and **visitor.unsignedClaims**, enabling authenticated private documentation with dynamic loading and behavior control.

**When to Use**:
- Need deep integration of GitBook documentation in a React or Node.js application
- Need to display different content based on user identity (such as userId, plan)
- Need to precisely control embed widget behavior via API methods (such as navigate, postMessage)

**When NOT to Use**:
- Target platform does not support npm packages or modern JavaScript module systems
- Team lacks front-end development resources to maintain the embed code
- Only need to display public documentation simply, with no dynamic behavior or authentication

**Known Limitations**:
- Requires a JavaScript/TypeScript development environment (Node.js or React)
- Requires managing secure distribution of JWT tokens; not suitable for purely static sites
- Dynamic content depends on the **visitor.unsignedClaims** structure, which requires preconfigured rules in the GitBook backend

**-> Detailed Steps**: See *gitbook/gitbook-embed*

## FAQ

Q: Which path should I start with?  
A: If you're not sure, start with **no-code embedding** to validate the approach quickly. Switch to the API method only when you need to embed private documentation, dynamic content, or deep integration.

Q: What happens if my docs are private but I use no-code embedding (iframe)?  
A: If a **JWT token** is not properly passed (via query parameter or **visitor.token** prop), users will see a "403 Forbidden" or be redirected to a login page, because the iframe cannot automatically inherit your application's authentication state.

Q: What happens if my site is pure static HTML (no React/Node.js) but I choose API embedding?  
A: You will not be able to use **@gitbook/embed**, **GitBookProvider**, or **createGitBook** because these depend on npm and a module system. You will encounter build failures or runtime errors.

Q: Can I hide the GitBook trademark in no-code embedding?  
A: Yes, via **window.GitBook.configure({ trademark: false })**, but this is only effective with the **Standalone script tag**; pure iframe links do not support it.

Q: For dynamic content (such as showing different chapters based on user plan), which method must I use?  
A: You must use API embedding and pass user attributes (such as `{ plan: 'pro' }`) via **visitor.unsignedClaims**, while configuring content visibility rules in the GitBook backend.

Q: Do both methods support embedding the GitBook AI assistant?  
A: Yes. As long as the Assistant is enabled in the GitBook console under **AI & MCP**, both methods can embed it, but the API approach gives better control over initialization timing and context.

Q: What if I only need to embed public documentation but choose API embedding?  
A: You will introduce unnecessary development complexity, including installing **@gitbook/embed**, configuring **GitBookProvider**, and managing **visitor.token**, none of which is needed in the no-code approach.

Q: What if I need to display content based on user identity but use no-code embedding (iframe or script tag)?  
A: You will not be able to switch content dynamically because that approach does not support reading user context at runtime; even if you manually craft a JWT token, you cannot leverage the **visitor.unsignedClaims** rule engine, leading to limited content access control.

## Related queries

how to embed docs in app, embed GitBook in SaaS, documentation embed, authenticated embed, customize embedded docs, iframe embed GitBook, script tag embed, GitBook AI assistant embed, React embed GitBook, npm embed docs, JWT token embed, window.GitBook.configure, @gitbook/embed, createGitBook, GitBo

---
Part of [GitBook](https://www.company-skill.com/p/gitbook.md) · https://www.company-skill.com/llms.txt