脚本标签

通过简单的脚本标签将文档嵌入添加到任何网站

将 Docs Embed 添加到您的网站或应用的最快方法是在 HTML 中通过“独立”脚本标签添加。每个 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>

如果您的文档站点受身份验证保护，脚本本身也在受保护的环境中提供。将签名令牌作为 jwt_token:

https://docs.company.com/~gitbook/embed/script.js?jwt_token=your-jwt-token

替换文档 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");
    // 如果您的文档站点受保护，您必须对脚本请求进行身份验证。
    // 将签名令牌作为 `jwt_token` 附加。
    var token = "your-jwt-token";
    script.src =
      "https://docs.company.com/~gitbook/embed/script.js?jwt_token=" +
      encodeURIComponent(token);
    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', {...}):

`选项卡`

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

类型: ('assistant' | 'docs')[]
选项:
- ['assistant', 'docs'] - 显示两个选项卡
- ['assistant'] - 仅显示助手选项卡
- ['docs'] - 仅显示文档选项卡

`操作`

在侧栏与选项卡并列呈现的自定义操作按钮。每个操作按钮在被点击时触发回调。

注意：此项以前命名为 buttons。请改用 操作 。

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

`问候`

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

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

`建议`

在助手欢迎屏幕中显示的建议问题。

类型: string[]

`工具`

用于扩展助手的自定义 AI 工具。请参阅创建自定义工具以获取详细信息。

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

`按钮`

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

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

示例：

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

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

`访问者` （已验证访问）

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

类型: { token?: string, unsignedClaims?: Record<string, unknown> }
属性:
- 令牌: 字符串 （可选）- 签名的 JWT 令牌
- 未签名的声明: 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: '...' }) 。

最后更新于7天前

这有帮助吗？

晚安

hashtag步骤

hashtag获取嵌入脚本 URL

hashtag将脚本标签添加到您的 HTML

hashtag替换文档 URL

hashtag测试小部件

hashtag可选地配置嵌入

hashtag控制小部件可见性

hashtag以编程方式导航和交互

hashtag动态加载（可选）

hashtag验证设置

hashtagAPI 参考

hashtag初始化

hashtag小部件控制

hashtag导航

hashtag聊天

hashtag配置

hashtag配置选项

hashtag选项卡

hashtag操作

hashtag问候

hashtag建议

hashtag工具

hashtag按钮

hashtag访问者 （已验证访问）

hashtag常见陷阱

步骤