脚本标签

通过一个简单的脚本标签将 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 图标均受支持
- 标签: string - 按钮标签文本
- onClick: () => void | Promise<void> - 点击时的回调函数

`greeting`

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

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

`suggestions`

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

类型: string[]

`tools`

用于扩展助理的自定义 AI 工具。详见创建自定义工具以获取详细信息。

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

`按钮`

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

类型: { label: string, icon: 'assistant' | 'sparkle' | 'help' | 'book' }
属性:
- 标签: 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个月前

这有帮助吗？

晚安

hashtag步骤

hashtag获取您的嵌入脚本 URL

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

hashtag替换文档 URL

hashtag测试小部件

hashtag可选地配置嵌入

hashtag控制小部件可见性

hashtag以编程方式导航和交互

hashtag动态加载（可选）

hashtag验证设置

hashtagAPI 参考

hashtag初始化

hashtag小部件控制

hashtag导航

hashtag聊天

hashtag配置

hashtag配置选项

hashtagtabs

hashtagactions

hashtaggreeting

hashtagsuggestions

hashtagtools

hashtag按钮

hashtagvisitor （经过身份验证的访问）

hashtag常见错误

步骤