脚本标签

通过简单的脚本标签将 Docs Embed 添加到任何网站

将 Docs Embed 添加到您的网站或应用的最快方法是通过“独立”脚本标签添加。GitBook 中的每个文档站点都包含一个可直接使用的脚本，用于将您的文档嵌入为小部件。

步骤

获取嵌入脚本 URL

导航到您的文档站点的设置 → AI 与 MCP 选项卡并复制脚本 URL，或使用位于 https://docs.company.com/~gitbook/embed/script.js （替换 docs.company.com 为您实际的文档站点 URL）。

将脚本标签添加到您的 HTML

将此代码放入您的 HTML <head> 或在关闭标签之前 </body> 处：

<script src="https://docs.company.com/~gitbook/embed/script.js"></script>
<script>
  // 使用已认证访问初始化（可选）
  window.GitBook('init', 
    { siteURL: 'https://docs.company.com' },
    { visitor: { token: 'your-jwt-token' } }
  );
  window.GitBook('show');
</script>

替换文档 URL

将 docs.company.com 更新为您实际的文档站点 URL。

测试小部件

加载您的页面。嵌入小部件应出现在右下角。

可选地配置嵌入

在调用前添加自定义选项 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>

控制小部件可见性

使用 API 显示、隐藏、打开或关闭嵌入：

<script>
  // 显示小部件
  window.GitBook("show");

  // 隐藏小部件
  window.GitBook("hide");

  // 打开嵌入窗口
  window.GitBook("open");

  // 关闭嵌入窗口
  window.GitBook("close");

  // 切换嵌入窗口
  window.GitBook("toggle");
</script>

以编程方式导航和交互

使用 API 导航到页面、切换选项卡或发布消息：

<script>
  // 在文档选项卡中导航到特定页面
  window.GitBook('navigateToPage', '/getting-started');

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

  // 向聊天发送消息
  window.GitBook('postUserMessage', 'How do I get started?');

  // 清除聊天记录
  window.GitBook('clearChat');
</script>

动态加载（可选）

对于需要认证的文档或条件加载，请在运行时注入脚本：

<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);
  }

  // 准备就绪时加载
  loadGitBookEmbed();
</script>

验证设置

打开浏览器控制台并输入 window.GitBook 以确认 API 可用。

API 参考

初始化

GitBook('init', options: { siteURL: string }, frameOptions?: { visitor?: {...} }) - 使用站点 URL 和可选的已认证访问初始化小部件

小部件控制

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

聊天

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

配置

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

配置选项

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

`tabs`

覆盖要显示的选项卡。默认为您站点的配置。

类型: ('assistant' | 'docs')[]
选项:
- ['assistant', 'docs'] - 显示两个选项卡
- ['assistant'] - 仅显示助理选项卡
- ['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[]

`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: 'Ask',
    icon: 'assistant'
  }
});

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

`visitor` （已认证访问）

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

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

常见问题陷阱

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

最后更新于1天前

这有帮助吗？

下午好

步骤