脚本标签

了解如何使用单个脚本标签将 Docs Embed 小组件添加到任何网站或 Web 应用中

将 Docs Embed 添加到您的网站或应用的最简单方式，是在 HTML 中包含一个独立脚本。每个 GitBook 文档站点都会提供一个可直接使用的嵌入脚本，它会自动加载小组件并将其连接到您的文档。本页面将告诉您如何完成这一操作。

无需 SDK、构建步骤或框架集成。只需包含该脚本，小组件就会出现在您的页面上。

开始使用

复制您的嵌入脚本 URL

在 GitBook 应用中进入您的文档站点，导航到设置选项卡，然后到 AI 与 MCP 并复制嵌入脚本 URL。

您也可以手动构建：

https://YOUR_DOCS_DOMAIN/~gitbook/embed/script.js

将您的 YOUR_DOCS_DOMAIN 替换为您真实文档站点的域名。

将脚本添加到您的 HTML 中

在页面 HTML 中添加以下标签。把它放在 <head> 中，或放在 </body>.

之前。
<script>window.GitBook('show');</script>

如果您的文档需要身份验证

如果您的文档位于身份验证之后，脚本必须包含已签名的 JWT 令牌。

将其作为查询参数附加：

<script src="https://YOUR_DOCS_DOMAIN/~gitbook/embed/script.js?jwt_token=YOUR_TOKEN"></script>

验证

重新加载您的页面。

小组件应显示在右下角。

可选：配置嵌入

您可以在显示之前自定义小组件。加载脚本后、调用之前，执行 configure ，然后再调用 window.GitBook('show').

之前。
<script>
  window.GitBook('configure', {
    button: {
      label: '提问',
      icon: 'assistant' // assistant | sparkle | help | book
    },
    trademark: false,
    tabs: ['assistant', 'search', 'docs'],
    actions: [
      {
        icon: 'circle-question',
        label: '联系支持',
        onClick: () => window.open('https://support.example.com', '_blank')
      }
    ],
    greeting: {
      title: '欢迎',
      subtitle: '我能帮您什么？'
    },
    suggestions: [
      '什么是 GitBook？',
      '我该如何开始？'
    ]
  });

  window.GitBook('show');
</script>

使用此方法，您可以自定义：

按钮标签和图标
小组件内可见的选项卡
自定义操作按钮
问候标题和副标题
向用户显示的建议提示。

搜索默认启用。如果您设置 tabs，请列出您想保留的每个选项卡。

设置配色方案

默认情况下，嵌入内容会遵循 iframe 的 CSS color-scheme。这样它就能自动继承您的应用主题或浏览器偏好。

如果您想强制使用某种模式，请初始化嵌入并传入 colorScheme 到 frameOptions:

之前。
<script>
  window.GitBook(
    'init',
    { siteURL: 'https://YOUR_DOCS_DOMAIN' },
    { colorScheme: 'dark' }
  );

  window.GitBook('show');
</script>

当您需要帧级别选项时，请使用此模式，例如 colorScheme 或 visitor.

控制小组件可见性

您可以通过 API 在运行时控制可见性和状态。

<script>
  // 使小组件可见
  window.GitBook('show');

  // 将小组件从页面中移除
  window.GitBook('hide');

  // 打开小组件面板
  window.GitBook('open');

  // 关闭小组件面板
  window.GitBook('close');

  // 切换打开或关闭
  window.GitBook('toggle');
</script>

当您想将小组件与自己的 UI 触发器连接起来时，这很有用。

以编程方式导航和交互

您可以从代码中驱动小组件进行导航、切换选项卡或发送消息。

<script>
  // 在小组件内打开特定文档页面
  window.GitBook('navigateToPage', '/getting-started');

  // 切换到助手选项卡
  window.GitBook('navigateToAssistant');

  // 向助手发送用户消息
  window.GitBook('postUserMessage', '我该如何开始？');

  // 清除当前聊天历史
  window.GitBook('clearChat');
</script>

此功能的典型用途包括：

从您的应用添加指向文档页面的深度链接
预填问题
在不同流程之间重置对话

动态加载嵌入脚本

如果您只想有条件地加载小组件，或需要在运行时附加身份验证令牌，请以编程方式注入脚本。

<script>
  function loadGitBookEmbed() {
    var token = "" // 如果您的站点需要身份验证，请用您的 JWT 令牌填充它
    var script = document.createElement('script');
    script.src = 'https://YOUR_DOCS_DOMAIN/~gitbook/embed/script.js'
      + token ? '?jwt_token=' + encodeURIComponent(token) : ';
    script.async = true;
    script.onload = function () {
      window.GitBook('show');
    };
    document.head.appendChild(script);
  }

  loadGitBookEmbed();
</script>

当小组件应仅在用户操作或功能开关之后加载时，请使用此模式

API 参考

初始化

GitBook('init', options: { siteURL: string }, frameOptions?: { visitor?: {...}, colorScheme?: 'light' | 'dark' }) - 使用站点 URL 和可选的帧选项初始化小组件

小组件控制

GitBook('show') - 显示小组件按钮
GitBook('hide') - 隐藏小组件按钮
GitBook('open') - 打开小组件窗口
GitBook('close') - 关闭小组件窗口
GitBook('toggle') - 切换小组件窗口

聊天

GitBook('postUserMessage', message: string) - 向聊天发送消息
GitBook('clearChat') - 清除聊天记录

配置

GitBook('configure', settings: {...}) - 配置小组件设置（见下方“配置”部分）
GitBook('unload') - 从页面中完全移除小组件

配置选项

`GitBook('configure')`

大多数配置选项可通过以下方式使用： GitBook('configure', {...}):

`tabs`

覆盖显示哪些选项卡。

搜索默认启用。如果您设置 tabs，则嵌入内容仅显示您列出的选项卡。

类型: ('assistant' | 'search' | 'docs')[]
选项:
- ['assistant', 'search', 'docs'] - 显示所有选项卡
- ['search', 'docs'] - 仅显示搜索和文档
- ['docs'] - 仅显示文档选项卡

`actions`

在侧边栏中与选项卡并排渲染的自定义操作按钮。每个操作按钮在点击时都会触发一个回调。

注意：这之前名为 buttons。请改用 actions 。

类型: Array<{ icon: string, label: string, onClick: () => void }>
属性:
- icon: string - 图标名称。支持任何 FontAwesome 图标。
- label: string - 按钮标签文本
- onClick: () => void | Promise<void> - 点击时的回调函数

`greeting`

在助手选项卡中显示的欢迎消息。

类型: { title: string, subtitle: string }

`suggestions`

在助手欢迎界面中显示的建议问题。

类型: string[]

`trademark`

在嵌入 UI 中显示或隐藏 GitBook 商标——包括 Docs Embed 页脚和 Assistant 品牌标识。

类型: boolean
默认值: true
示例:

window.GitBook('configure', {
  trademark: false
});

`tools`

用于扩展助手的自定义 AI 工具。详见创建自定义工具了解详情。

类型: Array<{ name: string, description: string, inputSchema: object, execute: Function, confirmation?: {...} }>

`button`

配置启动嵌入的按钮（仅适用于独立脚本）。这允许您自定义页面右下角出现的按钮的标签和图标。

类型: { label: string, icon: 'assistant' | 'sparkle' | 'help' | 'book' }
属性:
- label: string - 按钮上显示的文本
- icon: 'assistant' | 'sparkle' | 'help' | 'book' - 按钮上显示的图标
  - assistant - 助手图标
  - sparkle - 闪光图标
  - help - 帮助/问号图标
  - book - 书本图标

示例：

window.GitBook('configure', {
  button: {
    label: '提问',
    icon: 'assistant'
  }
});

注意： 此选项仅在使用独立脚本标签实现时可用。对于 React 或 Node.js 实现，您需要创建自己的按钮来触发嵌入。

`frameOptions`

某些选项是在帧上设置的，而不是作为配置。请在调用时传入它们 frameOptions 当调用 GitBook('init', options, frameOptions).

`colorScheme`

覆盖嵌入的配色方案。

如果省略，嵌入将遵循 iframe 的 CSS color-scheme，从而继承父页面或浏览器偏好。

类型: 'light' | 'dark'
示例:

window.GitBook(
  'init',
  { siteURL: 'https://docs.company.com' },
  { colorScheme: 'dark' }
);

`visitor` （已认证访问）

在使用以下方式初始化时传入 GitBook('init', options, frameOptions)。用于自适应内容和已认证访问.

类型: { token?: string, unsignedClaims?: Record<string, unknown> }
属性:
- token: string （可选）- 已签名的 JWT 令牌
- unsignedClaims: Record<string, unknown> （可选）- 用于动态表达式的未签名声明

常见问题

脚本 URL 不正确 – 请确保使用的是您的真实文档 URL，而不是示例 docs.company.com.
在脚本加载前调用 GitBook – 将 API 调用包装在 script.onload 中，或将它们放在脚本标签之后。
无法访问已验证身份的文档 – 如果您的文档需要登录，您必须提供 visitor.token ，并在初始化时传入。参见与经过身份验证的文档一起使用.
CORS 或 CSP 错误 – 确保您网站的内容安全策略允许从您的 GitBook 域加载脚本和 iframe。
小组件不可见 – 检查您页面上其他元素是否存在 z-index 冲突。默认情况下，小组件使用较高的 z-index。
忘记初始化 – 请确保在使用其他方法之前调用 GitBook('init', { siteURL: '...' }) 。

最后更新于2天前

这有帮助吗？

晚安

hashtag开始使用

hashtag复制您的嵌入脚本 URL

hashtag将脚本添加到您的 HTML 中

hashtag如果您的文档需要身份验证

hashtag验证

hashtag可选：配置嵌入

hashtag设置配色方案

hashtag控制小组件可见性

hashtag以编程方式导航和交互

hashtag动态加载嵌入脚本

hashtagAPI 参考

hashtag初始化

hashtag小组件控制

hashtag导航

hashtag聊天

hashtag配置

hashtag配置选项

hashtagGitBook('configure')

hashtagtabs

hashtagactions

hashtaggreeting

hashtagsuggestions

hashtagtrademark

hashtagtools

hashtagbutton

hashtagframeOptions

hashtagcolorScheme

hashtagvisitor （已认证访问）

hashtag常见问题