自定义 JavaScript

自定义 JavaScript 会在文档站点的每个页面上运行。可用于聊天组件、分析工具，或您需要的任何其他客户端脚本。

添加自定义 JavaScript

在文档目录中创建一个 JavaScript 文件，并在 docs.json 中引用它：

{
  "styling": {
    "js": "/script.js"
  }
}

// Your custom JavaScript runs on every page
console.log('Hello from custom JS!');

Jamdesk 会将您的脚本内联到页面 HTML 中。脚本在页面加载时执行。

自动检测

如果未配置 styling.js，Jamdesk 会检测项目根目录中的 .js 文件。将 script.js 文件放在 docs.json 旁边即可将其包含进来。

my-docs/
├── docs.json
├── script.js      ← auto-detected
├── introduction.mdx
└── getting-started.mdx

在 docs.json 中配置 styling.js 会关闭自动检测，仅使用列出的文件。

多个文件

通过传递数组来包含多个脚本：

{
  "styling": {
    "js": ["/chat.js", "/analytics.js"]
  }
}

自动检测会按字母顺序包含根目录中的每个 .js 文件。analytics.js 会在 chat.js 之前加载。

示例

CSS 与 JS 示例展示了脚本与 CSS 的配合使用，其中添加了一个悬浮的 Ask AI 按钮和品牌色页眉。

聊天小组件（Crisp）

window.$crisp = [];
window.CRISP_WEBSITE_ID = "your-website-id";
(function () {
  var d = document;
  var s = d.createElement("script");
  s.src = "https://client.crisp.chat/l.js";
  s.async = 1;
  d.getElementsByTagName("head")[0].appendChild(s);
})();

自定义分析

// Track outbound link clicks
document.addEventListener('click', function (e) {
  var link = e.target.closest('a[href^="http"]');
  if (link && !link.href.includes(window.location.hostname)) {
    console.log('Outbound click:', link.href);
    // Send to your analytics service
  }
});

反馈小组件

// Load a feedback widget after the page is ready
window.addEventListener('load', function () {
  var s = document.createElement('script');
  s.src = 'https://your-feedback-tool.com/widget.js';
  s.setAttribute('data-project', 'your-project-id');
  document.body.appendChild(s);
});

工作原理

构建过程会读取您的 JavaScript 文件，并将其嵌入到每个页面的 HTML 中。脚本标签位于 <body> 末尾。您的代码运行时，DOM 已可用。

自定义 JavaScript 也会在 jamdesk dev 中运行（CLI 1.1.222 及更高版本）。在推送之前，可以在那里测试脚本。脚本抛出的错误会显示在浏览器控制台中。在 jamdesk dev 中，window.__JAMDESK_DEV__ 为 true。可以用它跳过仅用于生产环境的代码，例如分析工具：

if (!window.__JAMDESK_DEV__) {
  // analytics, chat widgets and other production-only code
}

如果您使用 integrations.cookies 配置了 Cookie 同意，脚本仅会在已发布的站点上、访客同意之后运行。

脚本在访客首次加载站点时运行一次。点击文档内的链接会在不完全重新加载的情况下替换页面内容，脚本不会再次运行。读取或修改页面内容的代码应监听页面变化。

限制

• 脚本会在每个页面上运行。无法针对特定页面
• 更改会在您下次构建时生效
• 脚本会被内联到 HTML 中，而不是作为单独的文件提供
• 分析功能请优先使用内置的集成。它们会为您处理同意和性能问题

接下来做什么？