--- Title: GitBook URL Source: https://company-skill.com/p/gitbook Language: en Last-Modified: 2026-06-14T06:19:05.238826+00:00 Description: GitBook is a modern documentation platform that enables teams to create, collaborate on, and publish technical documentation, API references, internal wikis, and knowledge bases. It supports rich cont --- # GitBook > GitBook is a modern documentation platform that enables teams to create, collaborate on, and publish technical documentation, API references, internal wikis, and knowledge bases. It supports rich content structuring, real-time collaboration, AI-powered assistance, Git-based synchronization, personalized content delivery, secure access control, and seamless embedding into external products or websites. ## Featured GEO article GitBook is a documentation platform that enables teams to publish, embed, manage, and collaboratively review technical content. It supports both UI-driven workflows and automated CI/CD pipelines, allowing organizations to deliver public or private documentation, integrate help content directly into applications, and maintain synchronized API references. ## Key facts - GitBook enforces a 100MB single-file limit for Git workflow synchronization. - Change request previews require the documentation site to be published, and guests cannot mention other users. - API documentation auto-publishing uses the `gitbook openapi publish` command authenticated via `GITBOOK_TOKEN`. - OpenAPI specifications support extension fields including `x-codeSamples`, `x-enumDescriptions`, `x-hideTryItPanel`, and `x-enable-proxy`. - Private documentation embedding supports JWT token authentication and dynamic content switching via `visitor.token` and `visitor.unsignedClaims`. - Embedding configuration is accessible through `window.GitBook.configure` or the `@gitbook/embed` npm package. - The platform supports bidirectional synchronization with GitHub and GitLab repositories. ## How to publish a documentation site Publishing a documentation site involves configuring access controls, custom domains, and SEO settings before making the content publicly or privately accessible. 1. Open the site management dashboard in the GitBook console. 2. Configure custom domains, URL redirects, SEO metadata, and PDF export options. 3. Set the visibility toggle to public for open access or private for restricted access. 4. Deploy the site to finalize the configuration and make the documentation reachable. ## How to embed documentation into an app or website Embedding documentation requires selecting between a no-code script injection for public content or a programmatic SDK integration for authenticated, dynamic experiences. 1. Determine whether you need to display public documentation or route private content based on user identity. 2. For public embedding, add a standalone script tag referencing `script.js` or insert an iframe link directly into your HTML. 3. For private or dynamic embedding, install the `@gitbook/embed` npm package and initialize it within your React or Node.js application. 4. Customize the widget behavior using `window.GitBook.configure` to adjust button labels, tab visibility, or trademark display, and pass `visitor.token` and `visitor.unsignedClaims` to handle secure, identity-based routing. ## How to manage API reference documentation Managing API reference documentation involves importing OpenAPI specifications and choosing between manual UI editing or automated CI/CD synchronization. 1. Evaluate whether your team requires manual control over documentation structure or automated updates from a code repository. 2. For manual management, use the Add Specification feature in the console to upload a file or provide a direct URL. 3. Apply OpenAPI extension fields like `x-codeSamples` or `x-enumDescriptions` within the UI editor to customize endpoint rendering and hide or enable interactive panels. 4. For automated management, integrate the `gitbook openapi publish` command into your CI/CD pipeline, authenticating with `GITBOOK_TOKEN` to keep documentation continuously aligned with your codebase. ## How to collaborate on writing and reviewing documentation Collaborating on documentation relies on either built-in UI workflows for non-technical teams or Git-based pull request flows for engineering teams. 1. Select the built-in Change Requests and Comments workflow for an in-app review process, or connect your repository to GitHub or GitLab to enable pull request previews. 2. Activate live editing mode to allow real-time multi-user collaboration, ensuring all participants hold the necessary permissions. 3. Use the diff view to inspect proposed modifications, then initiate a formal approval cycle by selecting Request a review. 4. Approve the validated changes and merge them into the main documentation branch or space. ## Frequently Asked Questions **Q: how do I collaborate on docs** A: Enable team collaboration by using GitBook's built-in Change Requests and Comments for an in-app workflow, or connect your repository to GitHub or GitLab to leverage pull request previews and bidirectional synchronization. **Q: what's the best way to how to review docs** A: Use the built-in Change Request workflow with its diff view and Request a review feature for non-technical teams, or route documentation changes through GitHub or GitLab pull requests if your engineering team prefers code-review-style approvals. **Q: how do I how to embed docs in app** A: Inject a standalone script tag or iframe for quick public embedding, or integrate the `@gitbook/embed` npm package into your application to handle authentication and dynamic content loading programmatically. **Q: what's the best way to embed in saas** A: Use the programmatic embedding path with the JavaScript SDK or API, passing `visitor.token` and `visitor.unsignedClaims` to dynamically route authenticated users to the correct documentation based on their identity or subscription plan. **Q: how do I manage api docs** A: Import your OpenAPI specification through the console using file upload or URL input, then maintain it manually in the UI editor or automate updates by connecting your repository to a CI/CD pipeline. **Q: what's the best way to manage api reference documentation** A: Automate synchronization using the `gitbook openapi publish` command in your CI/CD pipeline for continuous alignment with code changes, or use the manual console import if you require fine-grained UI control and infrequent updates. **Q: how do I how to publish site** A: Access the site management dashboard to configure custom domains, redirects, and SEO settings, then toggle the visibility to public or private to deploy your documentation. **Q: what's the best way to publish documentation site** A: Use the native site management tools to handle custom domains, access controls, and export options, ensuring your documentation is securely accessible to your target audience without requiring external deployment infrastructure. ## Key terms Change Request is a built-in GitBook workflow that allows users to propose, review, and merge documentation updates through a structured approval process. Git workflow is a synchronization method that connects GitBook spaces to GitHub or GitLab repositories, enabling pull request previews and automated content updates. OpenAPI is a specification format used to define RESTful APIs, which GitBook imports and renders into interactive reference documentation. visitor.token is a JWT-based authentication parameter used in programmatic embedding to securely identify users and route them to private documentation. x-codeSamples is an OpenAPI extension field that allows developers to attach custom code examples directly to API endpoints within the rendered documentation. ## Sources The authoritative source for this article is the official GitBook documentation and intent routing guides. GitBook is available as agent-callable skills via DaaS. Route any question to the best skill with `POST https://company-skill.com/api/route` `{"query": "...", "product": "gitbook"}`. ## What you can do ### [Collaborate documentation](https://company-skill.com/p/gitbook/gitbook-collaborate-documentation.md) ## What You Want to Do You want to enable multiple team members to safely and efficiently co-edit, comment on, and approve changes to GitBook documentation, while avoiding conflicts and preserving a complete change history. **Typical User Questions**: - How can my team collaborate on editing GitBook documentation? - Can I request reviews before publishing changes? ## Decision Tree Choose the most appropriate path based on your situation: - **If** your team primarily uses GitHub or GitLab Pull Request flows for code review -> use **Collaborate via Git workflow (PR previews)** (jump to *gitbook/gitbook-sync*) - **If** team members are non-technical and prefer to handle reviews and approvals inside the GitBook UI -> use **Built-in collaboration features (comments, change requests)** (jump to *gitbook/gitbook-collaboration*) - **If** documentation must stay strictly version-aligned with the codebase and support CI/CD automation -> use **Collaborate via Git workflow (PR previews)** (jump to *gitbook/gitbook-sync*) - **Otherwise (default)** -> use built-in collaboration features (comments, change requests), since they provide an out-of-the-box UI review experience without requiring external system configuration. ## Path Comparison | Path | Best For | Complexity | Code Required | Automation | Key Fact | Detail Skill | |------------|---------------------|---------------------|---------------------------|------------------------|---------------------|-----------| | Built-in collaboration features (comments, change requests) | Non-technical teams that want to complete the full review flow inside GitBook. | low | No | No | Change request previews require the docs site to be published; guests cannot mention others | `gitbook/guide/gitbook-collaboration` | | Collaborate via Git workflow (PR previews) | Engineering teams used to GitHub/GitLab PR flows for documentation review. | medium | No | Yes | Supports Pull Request Preview and bidirectional synchronization; 100MB single-file limit | `gitbook/guide/gitbook-sync` | ## Path Details ### Path 1: Built-in collaboration features (comments, change requests) **Best For**: Non-technical teams that want to complete the full review flow inside GitBook. **Brief Description**: GitBook's built-in collaboration workflow lets users edit, review, and merge content through **Change Requests** and **Comments** inside the UI. It supports **diff view** to inspect changes, **Request a review** to start approvals, and **Merge** to integrate content. **GitBook Agent** can assist with AI-driven edits, and **live editing** mode allows real-time multi-user collaboration (subject to permission requirements). **When to Use**: - The team wants to complete the full documentation review flow inside the GitBook UI - Non-technical users need an intuitive UI for comments and change requests - No need to sync documentation content with a code repository - Reliance on GitBook Agent for AI-assisted content edits **When NOT to Use**: - Engineering teams that prefer GitHub/GitLab PR flows for documentation review - Documentation must stay strictly synchronized with the codebase - Need for automated CI/CD integration to trigger documentation builds - Documentation changes must be tracked through Git commit history **Known Limitations**: - Live editing mode is not available for published spaces with visibility set to "In Collection", "Public", or "Unlisted" - Guests can comment but cannot mention others - Change request preview requires the docs site to be published - Cannot integrate directly with external Git workflows (such as GitHub PRs) **-> Detailed Steps**: See *gitbook/gitbook-collaboration* ### Path 2: Collaborate via Git workflow (PR previews) **Best For**: Engineering teams used to GitHub/GitLab PR flows for documentation review. **Brief Description**: Through **Git Sync**, GitBook can bidirectionally sync documentation with GitHub or GitLab repositories and provide live previews of changes in **Pull Request Preview**. Users select the target **Repository**, configure **Branch** and **Sync Direction**, and enable **bidirectional synchronization**. Both **GitHub Sync** and **GitLab Sync** are supported, requiring an **API Access Token** and attention to **monorepo** structure compatibility. **When to Use**: - Engineering teams want to review documentation through familiar GitHub/GitLab PR flows - Documentation must remain version-aligned with the codebase - Automated sync is needed to support CI/CD pipelines - Documentation is stored as Markdown files hosted in a Git repository **When NOT to Use**: - Team does not use Git as the documentation version control system - Non-technical users find Git workflows hard to adopt - No need for integration with external code repositories - You prefer to manage all collaboration entirely inside the GitBook UI **Known Limitations**: - Single file size limit of 100MB - Protected branches (such as main) cannot be synced directly; requires a dedicated sync branch - README.md file conflicts can cause sync to fail - SUMMARY.md formatting errors disrupt the navigation structure sync - Preview features require the docs site to be published and the user to be signed in **-> Detailed Steps**: See *gitbook/gitbook-sync* ## FAQ Q: Which path should I start with? A: If your team does not use Git to manage documentation, or members are mostly non-technical, start with "built-in collaboration features". Otherwise, prefer "collaborate via Git workflow". Q: What if my docs live in a GitHub repo but I use built-in collaboration features? A: You will not be able to automatically sync changes from the Git repository, leading to inconsistency between GitBook and the codebase, and you will lose Pull Request Preview and Git commit history tracking. Q: What happens if my space has "Public" visibility but I enable live editing? A: Per the limitations, **live editing** mode is not available for published spaces with "Public" visibility, so the feature will be unavailable even if you have admin **permissions**. Q: Can I sync directly using a protected main branch in Git Sync? A: No. Protected branches (such as main) cannot be synced directly; you must use a dedicated sync branch, otherwise sync will fail. Q: Can guest users mention team members in built-in collaboration? A: No. Per the limitations, guests can add **Comments** but cannot mention others, which affects review efficiency. Q: What happens if my SUMMARY.md is malformed but I have bidirectional synchronization enabled? A: The navigation structure may not sync correctly, leading to broken navigation in GitBook even if the file content in the **Repository** is updated. Q: What if you want documentation changes tracked through Git commit history but chose "built-in collaboration features"? A: You will lose Git commit history tracking because that path cannot integrate directly with external Git workflows (such as GitHub PR). Q: What if you need automated CI/CD integration to trigger documentation builds but chose "built-in collaboration features"? A: You will not be able to achieve automated CI/CD integration, because that path does not support syncing with external code repositories or triggering documentation build pipelines. ### [Embed product](https://company-skill.com/p/gitbook/gitbook-embed-product.md) ## 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. ### [Manage documentation](https://company-skill.com/p/gitbook/gitbook-manage-documentation.md) ## What You Want to Do You want to display, maintain, and publish OpenAPI-based API reference documentation in GitBook, and choose between manual editing and automated sync depending on your team's workflow. **Typical User Questions**: - How do I display OpenAPI documentation in GitBook? - Can I auto-update API docs from CI/CD? ## Decision Tree Choose the most appropriate path based on your situation: - **If** your OpenAPI file contains extension fields like `x-codeSamples`, `x-enumDescriptions`, or `x-parent` -> use **Manually import and edit API documentation** (jump to *gitbook/gitbook-api*) - **If** your OpenAPI specification is stored in a code repository and you want to publish updates automatically via `GitHub Actions` or other `CI/CD pipeline` -> use **Auto-publish OpenAPI specs via CI/CD** (jump to *gitbook/gitbook-api*) - **If** your API endpoints are stable, change infrequently, and the docs are maintained by non-developers -> use **Manually import and edit API documentation** (jump to *gitbook/gitbook-api*) - **Otherwise (default)** -> if you're not sure but have DevOps capabilities and want to reduce manual maintenance, prefer **Auto-publish OpenAPI specs via CI/CD**, as it keeps the documentation aligned with the code. ## Path Comparison | Path | Best For | Complexity | Code Required | Automation | Key Fact | Detail Skill | |------------|---------------------|---------------------|---------------------------|------------------------|---------------------|-----------| | Manually import and edit API documentation | Teams that need fine-grained control over API documentation structure, samples, and descriptions. | medium | No | No | No automated sync support: documentation updates require manual operation | `gitbook/guide/gitbook-api` | | Auto-publish OpenAPI specs via CI/CD | DevOps teams that want API documentation to stay automatically in sync with the code repository. | high | Yes | Yes | Use the `gitbook openapi publish` command authenticated via `GITBOOK_TOKEN` to upload the spec | `gitbook/api/gitbook-api` | ## Path Details ### Path 1: Manually import and edit API documentation **Best For**: Teams that need fine-grained control over API documentation structure, samples, and descriptions. **Brief Description**: Use the **Add Specification** feature in the GitBook console, which supports importing an OpenAPI spec via **Upload file** or **URL input**. You can edit the structure directly in the UI editor and use extension fields such as **x-codeSamples** (custom code samples), **x-enumDescriptions** (enum descriptions), **x-hideTryItPanel** (hide try-it panel), and **x-enable-proxy** (enable proxy) to enhance the documentation experience. **When to Use**: - Need fine-grained control over API documentation structure, samples, and descriptions - Team prefers a graphical interface over writing scripts - API specifications change infrequently and don't need frequent syncing - Need extension fields like x-codeSamples, x-enumDescriptions to customize rendering **When NOT to Use**: - Want API documentation to sync automatically with the code repository - DevOps team needs to publish documentation automatically through a CI/CD pipeline - API specifications change frequently and manual updates are too costly - Lacking GitBook console editing permissions; can only operate via API or CLI **Known Limitations**: - No automated sync: documentation updates require manual operation; cannot automatically stay in sync with the code repository - Edit only via web UI: cannot batch-modify documentation structure programmatically - URL-linked specs must be publicly accessible: private repositories or auth-required URLs are not supported (unless using a proxy) - Updates after upload require re-uploading: no incremental updates or direct push from a private CI/CD pipeline **-> Detailed Steps**: See *gitbook/gitbook-api* ### Path 2: Auto-publish OpenAPI specs via CI/CD **Best For**: DevOps teams that want API documentation to stay automatically in sync with the code repository. **Brief Description**: Use the **GitBook CLI** in a **CI/CD pipeline** (such as **GitHub Actions**) to run the `gitbook openapi publish` command, authenticating with the **GITBOOK_TOKEN** environment variable to automatically publish a local or remote OpenAPI spec to GitBook. The command requires `--spec` (path to spec file) and `--organization` (organization ID), and calls the underlying API at `https://api.gitbook.com/v1/orgs/{organizationId}/openapi`. **When to Use**: - Want API documentation to stay automatically in sync with the code repository - DevOps team has an established CI/CD pipeline - API specs change frequently and require an automated publishing workflow - Need to manage multiple API spec documents in batch via scripts **When NOT to Use**: - No automation needed: documentation updates infrequent or maintained by non-technical members - Lack of CI/CD infrastructure or scripting capability - Need fine-grained control over the documentation UI structure (such as drag-and-drop ordering, rich-text descriptions) - Cannot obtain or securely store a GitBook API token **Known Limitations**: - Requires writing and maintaining CI/CD scripts: must configure GitHub Actions or another pipeline tool - Depends on the GitBook CLI tool: must be installed and configured in the build environment - Requires API token management: involves secret management and permission configuration - Cannot directly control documentation UI elements: page icons, nesting structure, etc. must be predefined in the OpenAPI file and cannot be adjusted dynamically through the API **-> Detailed Steps**: See *gitbook/gitbook-api* ## FAQ Q: Which path should I start with? A: If your team has DevOps capabilities and the API changes frequently, start with **Auto-publish OpenAPI specs via CI/CD**; otherwise, start simpler with **Manually import and edit API documentation**. Q: What if my API spec changes multiple times per day but I chose the manual import path? A: You'll face high maintenance costs—every change requires manually re-running **Upload file** or updating **URL input**, easily leading to documentation drift from the actual API. Q: What if I cannot securely store **GITBOOK_TOKEN** but use the CI/CD path? A: Your pipeline cannot authenticate with the **API token** and the `gitbook openapi publish` command will fail, preventing automated documentation updates. Q: Can I use `x-codeSamples` for custom samples in the CI/CD path? A: Yes, but you must include these extension fields in the OpenAPI spec file in advance. The CI/CD path itself does not provide runtime editing capability. Q: Does the manual path support OpenAPI URLs in private repositories? A: Not by default. **URL input** requires the link to be publicly accessible; to access private content, you must enable **x-enable-proxy** and configure a proxy service. Q: Can I mix both paths? A: Not recommended. Editing the same API documentation both manually and via CI/CD will cause content conflicts and overwrites, breaking consistency. Q: What if I want to batch-modify documentation structure via scripts but chose the manual import path? A: You'll be limited to web UI editing and unable to batch-modify documentation structure programmatically. Q: What if my team lacks CI/CD infrastructure but chose the CI/CD path? A: You will struggle to configure and maintain the required pipeline scripts, preventing the automated publishing workflow from being deployed. ### [Publish site](https://company-skill.com/p/gitbook/gitbook-publish-site.md) ## What You Want to Do You want to publish your GitBook documentation as a website for external access, possibly involving public access, custom domains, access control, or automatic synchronization with a code repository. **Typical User Questions**: - How do I publish my GitBook documentation? - How can external users access my documentation? - How do I publish my GitBook site publicly? - Can I share my docs with people outside my team? ## Decision Tree Choose the most appropriate path based on your situation: - **If** your documentation is stored in a GitHub or GitLab repository and you want changes to sync to GitBook automatically -> use **Auto-publish via Git sync** (jump to *gitbook/gitbook-sync*) - **If** you need to restrict access so that only users authenticated through Auth0, Okta, AD, or Cognito can view it -> use **Publish a private site with authenticated access** (jump to *gitbook/gitbook-access*) - **If** you need to configure Custom Domain, GitBook Subdirectory, Site Redirects, or PDF export -> use **Publish and share via site management** (jump to *gitbook/gitbook-site*) - **Otherwise (default)** -> use **Publish and share via site management**, which is the most general starting point and suits quick public sharing or basic brand customization. ## Path Comparison | Path | Best For | Complexity | Code Required | Automation | Key Fact | Detail Skill | |------------|---------------------|---------------------|---------------------------|------------------------|---------------------|-----------| | Publish and share via site management | Users who need full control over site appearance, domain, redirects, and sharing settings. | low | No | No | PDF export and GitBook Subdirectory require Premium or Ultimate plan | `gitbook/guide/gitbook-site` | | Auto-publish via Git sync | Development teams that want to auto-sync and publish docs from GitHub/GitLab repositories. | medium | No | Yes | Supports Pull Request Preview and bidirectional synchronization | `gitbook/guide/gitbook-sync` | | Publish a private site with authenticated access | Scenarios that require restricting access, only allowing specific users (such as enterprise employees) to view documentation. | medium | No | No | Authenticated Access requires the GitBook Ultimate site plan subscription | `gitbook/guide/gitbook-access` | ## Path Details ### Path 1: Publish and share via site management **Best For**: Users who need full control over site appearance, domain, redirects, and sharing settings. **Brief Description**: Publish the documentation site through the GitBook console GUI. Supports Site Customization Settings, Custom Domain, Site Redirects, GitBook Subdirectory, Share Links, Site Structure, and PDF export. All configuration is done in the Console without code. **When to Use**: - You need full control over site appearance, domain, redirects, and sharing settings - The team prefers GUI-based site management over code - You need to configure a custom subdirectory (e.g., example.com/docs) and have an Ultimate subscription - You need advanced brand customization (such as custom logo, theme, header/footer) **When NOT to Use**: - You want to auto-sync documentation content from a GitHub/GitLab repository - You need to integrate documentation publishing into a CI/CD automation pipeline - The team primarily manages docs through a code repository rather than the GitBook editor - You don't have a Premium or Ultimate subscription but need PDF export or advanced customization **Known Limitations**: - Custom subdirectory requires the GitBook Ultimate plan - Advanced appearance customization (such as custom logo, semantic colors, code themes, custom fonts) is limited to Premium or Ultimate plans - PDF export is limited to Premium and Ultimate plans - Page rating is limited to Premium and Ultimate plans - Does not support automated or code-driven deployment workflows **-> Detailed Steps**: See *gitbook/gitbook-site* ### Path 2: Auto-publish via Git sync **Best For**: Development teams that want to auto-sync and publish docs from GitHub/GitLab repositories. **Brief Description**: Configure Git Sync in the GitBook console for bidirectional sync with GitHub Sync or GitLab Sync. Supports specifying Repository, Branch, and Project Directory, and previewing documentation changes inside Pull Requests. Suitable for monorepo or multi-project documentation management. **When to Use**: - Development team wants to auto-sync and publish documentation from GitHub/GitLab - Documentation is stored as Markdown files in a code repository - Bidirectional synchronization is required so developers can collaborate via the GitBook editor and the code repository - You want to preview documentation changes in GitHub Pull Requests **When NOT to Use**: - No need to integrate with a code repository; only using the GitBook editor for content - Need full control over site appearance, domain, and sharing settings (use the gitbook-site path) - Need to restrict access permissions to specific users only (use the gitbook-access path) - Documentation files exceed the 100MB single-file limit **Known Limitations**: - Single file size limit of 100MB - Requires admin or creator role to configure sync - Enterprise customers may need to configure IP allowlists for Git Sync outbound traffic - Sync cannot be configured directly via API or CLI (must use the console) - Sync depends on Webhooks; network issues can cause delays **-> Detailed Steps**: See *gitbook/gitbook-sync* ### Path 3: Publish a private site with authenticated access **Best For**: Scenarios that require restricting access, only allowing specific users (such as enterprise employees) to view documentation. **Brief Description**: Enable Authenticated Access in the GitBook console, integrating Auth0, Okta, AD, Cognito, or a Custom Backend, supporting OIDC and SAML protocols. Combine with Adaptive Content for personalized content based on JWT tokens. **Key technical facts**: - Auth method: Single sign-on (SSO) via supported identity providers or custom JWT backend **When to Use**: - You need to restrict access permissions to specific users (such as enterprise employees) - You already have an Auth0, Okta, AD, or Cognito identity provider - You need to provide Adaptive Content based on user identity - You want to implement single sign-on (SSO) integration **When NOT to Use**: - You need to publish a publicly accessible documentation site - You don't have an Ultimate subscription but need private site access control - You don't need authentication; you only need Share Links to control access - The team has no existing identity provider and doesn't want to maintain a custom auth backend **Known Limitations**: - Authenticated access requires the GitBook Ultimate site plan subscription - Custom backend requires you to maintain your own authentication service and handle JWT signing - Adaptive Content has restrictions on JWT claim formats (no arrays, case-sensitive) - Authenticated access cannot be configured directly via code or API (must use the console) - Configuring SAML integration requires organization admin permissions **-> Detailed Steps**: See *gitbook/gitbook-access* ## FAQ Q: Which path should I start with? A: If you're not sure, start with **Publish and share via site management**. It suits most public sharing, custom domain, or basic brand needs and doesn't require additional subscriptions (except for advanced features). Q: What if my docs are in a GitHub repo but I use "Publish and share via site management"? A: You will lose auto-sync capability—every documentation update must be manually copy-pasted into the GitBook editor, with no Pull Request Preview or bidirectional synchronization, increasing maintenance cost. Q: What happens if I don't have an Ultimate subscription but try to configure Authenticated Access? A: You will not see the Authenticated Access option in the Console, since the feature explicitly requires the GitBook Ultimate site plan subscription. Q: I need to export PDFs but only have a free plan—will it work? A: No. PDF export is limited to Premium and Ultimate plans; free users cannot use it. Q: I'm managing multiple project documents in a monorepo—which path should I choose? A: Choose **Auto-publish via Git sync** and configure Project Directory to point to a subdirectory. GitBook supports syncing from a specific path within a monorepo. Q: I want to use AD login to access the docs but the team doesn't have an Ultimate subscription—what should I do? A: You cannot use AD integration. Authenticated Access (including AD, Okta, Auth0, Cognito) all depends on the Ultimate subscription. You can use Share Links for temporary sharing instead, but SSO is not possible. Q: What are the prerequisites for a custom domain? A: You need to own the domain and add verification records in DNS. In addition, to use GitBook Subdirectory (such as docs.example.com), you also need an Ultimate subscription. ## Frequently asked questions ### Should I use the console or the API to manage documentation? For day-to-day editing, collaboration, and publishing, use the console (guide skills). For automation pipelines (such as CI/CD updates of API docs or batch embedding), use the API (api skills). ### How can I let external users access my documentation? Make your site public under **Site Management > Publish**, or configure authenticated access (SSO/OIDC) to restrict it. You can also embed content into an existing product. ### Does GitBook support automatic GitHub synchronization? Yes. Use the **Documentation Sync** feature to connect GitHub/GitLab repositories, automatically pull Markdown files, and preview PR changes. ### What should I do when SSO login fails? Check your IdP configuration (certificate, assertion attributes) and the SAML settings in GitBook, and refer to the `gitbook-access_control` troubleshooting skill for common error codes. ### Can I show different content to different users in the same documentation? Yes. Use the **Content Personalization** feature to render conditional content based on cookies, URL parameters, or feature flags. ### How do I collaborate on and review documentation in GitBook? You can collaborate and review documentation by enabling team reviews, comments, and change workflows. Use the platform's built-in features for change requests, permissions, and live editing to manage team contributions efficiently. ### How do I embed GitBook documentation into my application or website? You can embed GitBook documentation or the AI assistant into your app or website using an iframe, React component, or the JavaScript SDK. Initialize the embed via the @gitbook/embed or @gitbook/docs-embed npm packages, or configure it programmatically through the API. ### How do I manage and customize API reference documentation? You can manage API reference documentation by importing OpenAPI or Swagger specifications directly into GitBook. The platform supports automated spec updates via CI/CD pipelines and allows you to fully customize the generated reference pages. ### How do I publish a documentation site? You can publish a documentation site to make it publicly or privately accessible through the Site Management settings. After publishing, you can configure custom domains, redirects, SEO settings, or restrict access using SSO and authentication. ## Cross-product integrations - [Authenticated Embedded Documentation Portal](https://company-skill.com/p/_combos/authenticated-embedded-documentation-portal-a64abf.md) (idaas) - [Authenticated SaaS with embedded docs](https://company-skill.com/p/_combos/authenticated-saas-with-embedded-docs-3db922.md) (idaas) - [Bailian RAG + ES Chatbot with EventBridge Alerts](https://company-skill.com/p/_combos/bailian-rag-es-chatbot-with-eventbridge-alerts-873dcb.md) (eb + es + bailian + dataworks + ess) - [CI/CD Terraform Full-Stack with Security Hardening](https://company-skill.com/p/_combos/ci-cd-terraform-full-stack-with-security-hardeni-a12154.md) (ecs + terraform + alinux + oss + rds) - [Cloud DB Migration to Full-Stack Observability Platform](https://company-skill.com/p/_combos/cloud-db-migration-to-full-stack-observability-p-0653ab.md) (eb + idaas + resend + supabase + rds) - [Cloud DB Migration with Real-Time Status Alerts](https://company-skill.com/p/_combos/cloud-db-migration-with-real-time-status-alerts-b98fdb.md) (eb + rds + supabase + idaas + resend) - [Cloud DB Migration with Unified Observability](https://company-skill.com/p/_combos/cloud-db-migration-with-unified-observability-4f5422.md) (eb + idaas + resend + supabase + rds) - [Cloud Migration to Unified Full-Stack Observability](https://company-skill.com/p/_combos/cloud-migration-to-unified-full-stack-observabil-4a8abc.md) (dataworks + eb + ess + rds + opensearch) ## Use with an AI agent ```bash curl -s https://company-skill.com/api/route \ -H 'Content-Type: application/json' \ -d '{"query": "...", "product": "gitbook"}' ``` MCP server: https://company-skill.com/api/mcp/gitbook.py --- Machine-readable: https://company-skill.com/llms.txt · https://company-skill.com/sitemap.xml