自定义脚本

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

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

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

组件接受 className prop。Mintlify 会将你的类与组件自身的样式合并，因此你无需额外的包裹标记或编写 CSS 覆盖，即可为单个实例重新设置样式。

<Note className="mt-0">This callout has no top margin.</Note>

<Card title="Quickstart" href="/quickstart" className="border-2 border-blue-500">
  Deploy your first documentation site.
</Card>

有三个组件不接受 className：Banner、MDX 和 Visibility。

当没有工具类能满足所需的值时，请使用任意值（arbitrary value）。

<img src="/images/diagram.png" alt="System architecture diagram" className="w-[450px]" />

<Frame className="lg:w-[calc(100%-2rem)] bg-[#0f172a]">
  <img src="/images/hero.png" alt="Product hero image" />
</Frame>

变体（variant）的用法与任何 Tailwind 项目相同，包括响应式前缀（sm:、md:、lg:）、状态变体（hover:、focus:）、dark:、数据属性变体（data-[state=open]:）、不透明度修饰符（bg-black/50）以及 ! important 修饰符。

Mintlify 会为在页面源码中找到的 Tailwind 类生成 CSS，因此请完整写出类名。

{/* Generates CSS: the full class name appears in the page source. */}
<div className="bg-blue-500" />

{/* Generates no CSS: the class name is assembled at runtime. */}
<div className={`bg-${color}-500`} />

Mintlify 会自动在你的文档站点的每个页面中包含内容目录下的任何 .css 文件，方式与包含自定义 .js 文件相同。内容目录是仓库中包含 docs.json 文件和 MDX 页面的文件夹。你无需在 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.api.playground.setServerVariables，通过自定义 JavaScript 预填充 OpenAPI 服务器变量。当页面加载后才能获得这些值时使用此方法，例如身份验证 SDK 初始化完成或租户发生变化时。该方法会立即更新已打开的 API Playground，也会应用到之后打开的 Playground。

传入一个值为字符串的对象。每次调用都会替换完整的运行时覆盖值。省略的键会被移除，无效值会被忽略。运行时值优先于 OpenAPI 默认值和已保存的服务器变量。

window.mintlify.api.playground.setServerVariables({
  tenantDomain: 'example.us.auth0.com',
});

当这些值不再适用时调用 window.mintlify.api.playground.clearServerVariables()，例如注销后。清除后，API Playground 会回退到其他已配置的值。

window.mintlify.api.playground.clearServerVariables();

在客户端初始化之前发出的调用会进入队列，并在客户端初始化时应用。覆盖值仅在当前页面会话的内存中保留。不会写入 localStorage 或凭据存储。完整刷新页面会移除覆盖值。

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

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

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

  renderAppLauncher(user);
});

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

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

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