自定义脚本

使用 CSS 为 HTML 元素设置样式，或添加自定义 CSS 和 JavaScript，全面定制文档的外观与使用体验。

使用 Tailwind CSS v3 为 HTML 元素设置样式。你可以控制布局、间距、颜色及其他视觉属性。常见的类包括：

• w-full - 宽度占满
• aspect-video - 16:9 比例
• rounded-xl - 大圆角
• block, hidden - 显示控制
• dark:hidden, dark:block - 深色模式下的可见性

不支持 Tailwind CSS 的任意值语法。若需自定义值，请改用 style 属性。

<img style={{ width: '350px', margin: '12px auto' }} src="/path/image.jpg" />

Mintlify 会自动在你的文档站点的每个页面中包含内容目录下的任何 .css 文件，方式与包含自定义 .js 文件相同。你无需在 docs.json 或 MDX 文件中导入或引用该文件。

要添加自定义样式，请在内容目录的任意层级创建一个 .css 文件（例如 style.css）。你在其中定义的任何类名、ID 选择器或元素选择器都可以在所有 MDX 文件中使用。

例如，在 style.css 中定义一个类：

.my-callout {
  border-radius: 1rem;
  background: #f0f9ff;
  padding: 1rem;
}

然后在任意 MDX 文件中通过 className 属性使用它：

<div className="my-callout">
  内容在这里。
</div>

你可以在同一个元素上将自定义类名与 Tailwind CSS 类组合使用。

自定义 CSS 会应用于站点的每个页面，包括自定义模式页面和落地页。若要将样式限定到特定页面或部分，请使用 数据属性中介绍的 html[data-current-path="..."] 属性选择器。

引用和常用元素的样式可能会发生变化。请谨慎使用自定义样式，因为未来更新中可能出现不兼容的变更。

例如，你可以添加以下 style.css 文件以自定义导航栏和页脚的样式。

#navbar {
  background: #fffff2;
  padding: 1rem;
}

footer {
  margin-top: 2rem;
}

Mintlify 提供两种类型的 CSS 定位钩子：

• ID 选择器：页面级唯一元素，在 CSS 中使用 #value { } 定位
• 元素选择器：组件和布局元素，在 CSS 中使用 value { } 定位（无 # 或 . 前缀）

每个 ID 在每个页面上只出现一次。在 CSS 中使用 #value 来定位。例如，#navbar { background: red; }。

这些元素可以在页面上出现多个实例。在 CSS 中使用 value 来定位。例如，accordion { border: 1px solid red; }。

自定义 JS 允许你在全局添加自定义可执行代码，相当于在每个页面都插入一个包含 JS 代码的 <script> 标签。

Mintlify 会将文档站点的 content 目录中的任何 .js 文件注入到每个文档页面，包括自定义模式页面和落地页。自定义 JavaScript 文件会在页面变为可交互后运行，无法将其作用范围限定到特定页面；当存在多个 .js 文件时，它们都会执行，但执行顺序无法保证。

若要加载第三方脚本，请从你的自定义 JavaScript 文件中注入 <script> 元素，而不是在 MDX 中直接添加原始的 <script src="..."> 标签：

const script = document.createElement('script');
script.src = 'https://example.com/widget.js';
script.async = true;
document.head.appendChild(script);

比如，你可以添加下面的 ga.js 文件，在整个文档站点启用 Google Analytics。

window.dataLayer = window.dataLayer || [];
function gtag() {
  dataLayer.push(arguments);
}
gtag('js', new Date());

gtag('config', 'TAG_ID');

如果你的站点启用了身份验证，自定义脚本可以通过 window.mintlify.user 读取已登录用户。它与 MDX 页面中暴露的 user 变量是同一个对象，因此对应你用户数据中的 content 字段。

由于自定义脚本会在用户信息解析之前运行，请监听 mintlify:user 事件，以便在用户对象可用时做出响应。该事件会在用户信息解析时触发，之后每次发生变化也会再次触发。事件的 detail 是用户对象；当访客处于未登录状态时，则为 null。

window.addEventListener('mintlify:user', (event) => {
  const user = event.detail;
  if (!user) return; // Signed out.

  renderAppLauncher(user);
});

如果你的脚本运行时用户已经解析完成，可直接读取 window.mintlify.user。

const user = window.mintlify?.user;
if (user) {
  renderAppLauncher(user);
}

在用户信息解析完成之前，以及访客处于未登录状态时，window.mintlify.user 都为 undefined。读取嵌套字段时请使用可选链操作符。