自定义脚本

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

使用 Tailwind CSS 进行样式设计

使用 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" />

使用 style 属性可能会在页面加载时导致布局位移，尤其是在自定义模式的页面中。请改用 Tailwind CSS 类或自定义 CSS 文件，以避免位移或闪烁。

添加自定义 CSS

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 选择器

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

页面布局

#body-content—页面主体的最外层容器。
#content-area—主要内容区域，不包括侧边栏和目录。
#content—内容区域内的内部内容元素。
#header—页面级头部元素。
#banner—显示在导航栏上方的公告横幅。
#footer—页脚。也可用作元素选择器：footer。
#page-title—每个页面顶部的 <h1> 标题。
#pagination—底部分页栏，包含上一页和下一页链接。
#panel—浮动面板覆盖层。也可用作元素选择器：panel。
#background-color—页面背景颜色元素。

导航

#navbar—顶部导航栏。
#topbar-cta-button—顶栏中的行动号召按钮。
#mobile-nav—移动端导航覆盖层。
#mobile-nav-content—移动端导航覆盖层内的内容区域。

侧边栏

#sidebar—侧边栏导航面板。
#sidebar-content—侧边栏内可滚动的内容区域。

#table-of-contents—页面右侧的目录面板。
#table-of-contents-layout—目录的布局容器。
#table-of-contents-content—目录内可滚动的内容。

搜索

#search-bar-entry—顶栏中的搜索栏触发器。
#search-bar-entry-mobile—移动端的搜索栏触发器。
#search-input—搜索模态框内的文本输入字段。

AI 助手

#assistant-entry—顶栏中的 AI 助手按钮。
#assistant-entry-mobile—移动端的 AI 助手按钮。
#chat-assistant-sheet—AI 助手聊天面板。
#chat-assistant-textarea—AI 助手面板内的文本输入。

API 参考

#request-example—API playground 中的请求示例面板。
#response-example—API playground 中的响应示例面板。
#api-playground-input—API playground 的输入区域。
#endpoints-menu-trigger—打开端点选择器下拉菜单的按钮。

代码块

#ask-assistant-code-block-button—代码块上显示的“询问助手”按钮。
#code-snippet-feedback-button—代码片段上的反馈按钮。
#code-snippet-feedback-textarea—代码片段反馈表单内的文本区域。

反馈

#feedback-thumbs-up—页面底部的点赞按钮。
#feedback-thumbs-down—页面底部的点踩按钮。
#feedback-form—点踩后显示的反馈表单。
#feedback-form-input—反馈表单内的文本输入。
#feedback-form-cancel—反馈表单内的取消按钮。
#feedback-form-submit—反馈表单内的提交按钮。

页面上下文菜单

#page-context-menu—当前页面的上下文选项菜单。
#page-context-menu-button—触发页面上下文菜单的按钮。

本地化

#localization-select-trigger—打开语言选择器的按钮。
#localization-select-content—语言选择器的下拉内容。
#localization-select-item—选择器中的单个语言选项。

变更日志

#changelog-filters—变更日志页面上的过滤控件。
#changelog-filters-content—变更日志过滤面板内的内容区域。

多视图

#multi-view-dropdown—用于切换文档视图的下拉菜单。

文本选择

#text-selection-tooltip—在页面上选择文本时显示的提示框。
#text-selection-tooltip-button—文本选择提示框内的操作按钮。

元素选择器

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

内容组件

accordion—可折叠的手风琴项。
accordion-group—包含多个手风琴的容器。
callout—标注块（Note、Warning、Tip 等）。
card—单个卡片元素。
card-group—包含多个卡片的容器。已弃用，推荐使用 columns，但为向后兼容而保留。
columns—多列布局容器。
code-block—代码块元素。
code-block-icon—代码块头部显示的图标。
code-group—带标签页的代码块组。
expandable—可展开区域元素。
frame—用于图片或嵌入内容的框架容器。
icon—内联图标元素。
mermaid—Mermaid 图表容器。
step—步骤序列中的单个步骤。
steps—编号步骤容器。
tab-icon—标签页中显示的图标。
tabs—标签页内容容器。
tile—Tile 组件元素。
tooltip—提示框元素。
update—变更日志更新条目。

页面布局

mdx-content—已渲染的 MDX 内容区域。
panel—浮动面板组件。也可用作 ID 选择器：#panel。
eyebrow—页面标题上方显示的小标签。
link—锚点链接元素。
breadcrumb-list—面包屑导航列表。
breadcrumb-item—单个面包屑项。

顶栏导航

nav-logo—导航栏中的 Logo。
navbar-link—导航栏内的链接元素。
nav-anchors—顶栏中锚点链接的容器。
nav-anchor—顶栏中的单个锚点链接。
nav-tabs—顶部导航中的标签页栏。
nav-tabs-item—顶部导航标签页栏中的单个标签页项。
mobile-nav-tabs-item—移动导航标签页栏中的标签页项。
topbar-right-container—顶栏的右侧部分。
nav-tag-pill—导航中显示的标签徽章。
nav-tag-pill-text—导航标签徽章中的文本。

顶栏下拉菜单

nav-dropdown-trigger—打开导航下拉菜单的按钮。
nav-dropdown-content—导航下拉菜单的内容容器。
nav-dropdown-item—导航下拉菜单中的单个项。
nav-dropdown-item-text-container—下拉菜单项中的文本容器。
nav-dropdown-item-title—下拉菜单项中的标题文本。
nav-dropdown-item-description—下拉菜单项中的描述文本。
nav-dropdown-item-icon—下拉菜单项中的图标。

产品选择器

nav-dropdown-products-selector-trigger—打开产品选择器下拉菜单的按钮。
nav-dropdown-products-selector-content—产品选择器的内容容器。
nav-dropdown-products-selector-item—选择器中的单个产品。
nav-dropdown-products-selector-item-title—产品选择器项的标题。
nav-dropdown-products-selector-item-description—产品选择器项的描述。
nav-dropdown-products-selector-item-icon—产品选择器项的图标。

侧边栏

sidebar-group—侧边栏中的相关链接分组。
sidebar-group-icon—侧边栏分组的图标。
sidebar-group-header—侧边栏分组的标题标签。
sidebar-title—侧边栏中的顶级标题。
sidebar-nav-group-divider—侧边栏导航分组之间的分隔线。

toc—目录容器。
toc-item—目录中的单个标题条目。

页脚

footer—标准页脚。也可用作 ID 选择器：#footer。
advanced-footer—包含额外列或内容的扩展页脚。

分页

pagination-prev—分页栏中的上一页链接。
pagination-next—分页栏中的下一页链接。
pagination-title—分页栏中显示的页面标题。

API 参考

api-section—单个 API 端点的完整部分。
api-section-heading—API 端点部分的标题区域。
api-section-heading-title—API 端点部分标题中的标题文本。
api-section-heading-subtitle—API 端点部分标题中的副标题。
field—API 参考中的参数或属性字段。
option-dropdown—用于在 API 选项之间选择的下拉菜单。
tryit-button—打开 API playground 的 “Try it” 按钮。
method-pill—端点上的 HTTP 方法徽章（GET、POST 等）。
method-nav-pill—侧边栏导航中显示的 HTTP 方法徽章。
prompt—API 参考中的 prompt 组件。

AI 助手

chat-assistant-sheet—AI 助手面板容器。
chat-assistant-sheet-header—AI 助手面板的头部。
chat-assistant-sheet-content—AI 助手面板的内容区域。
chat-assistant-input—AI 助手面板内的文本输入。
chat-assistant-floating-input—AI 助手的浮动输入变体。
chat-assistant-send-button—AI 助手面板中的发送按钮。
chat-assistant-disclaimer-text—AI 助手面板中显示的免责声明文本。
chat-assistant-payload-item—助手面板中的单条消息或结果项。
starter-question-text—空助手面板中显示的建议起始问题。

反馈

feedback-toolbar—包含页面反馈控件的工具栏。
contextual-feedback-container—上下文内联反馈的容器。
contextual-feedback-form—内联上下文反馈表单。
contextual-feedback-form-title—上下文反馈表单的标题。
contextual-feedback-input—上下文反馈表单内的文本输入。
contextual-feedback-button—上下文反馈表单内的操作按钮。
contextual-feedback-form-submit-button—上下文反馈表单的提交按钮。

代码片段反馈

code-snippet-feedback-popover-content—代码片段反馈的弹出内容。
code-snippet-feedback-form—代码片段的反馈表单。
code-snippet-feedback-textarea—代码片段反馈表单内的文本区域。
code-snippet-feedback-form-title—代码片段反馈表单的标题。
code-snippet-feedback-form-description—代码片段反馈表单中的描述文本。
code-snippet-feedback-form-submit-button—代码片段反馈表单的提交按钮。

身份验证

login-link—发起登录流程的链接。
logout-link—发起登出流程的链接。

多视图

multi-view-item—多视图切换器中的单个视图选项。
multi-view-dropdown—用于在多个视图之间选择的下拉菜单。
multi-view-dropdown-trigger—打开多视图下拉菜单的按钮。
multi-view-dropdown-content—多视图下拉菜单的内容区域。
multi-view-dropdown-item—多视图下拉菜单中的单个项。

目录页

directory—目录页的根容器。
directory-group—目录内的相关页面分组。
directory-page—目录中的单个页面条目。
directory-card—目录中以卡片形式显示的页面条目。

404 页面

not-found-container—404 页面的根容器。
not-found-status-code—404 页面上的状态码显示。
not-found-title—404 页面上的标题。
not-found-description—404 页面上的描述文本。
not-found-recommended-pages-list—404 页面上显示的推荐页面列表。
not-found-recommended-page-link—推荐页面列表中的单个链接。

颜色

color—色彩样本元素。
color-row—色彩样本分组行。
color-item—颜色行中的单个颜色项。

文件树

tree—文件树容器。
tree-folder—文件树中的文件夹条目。
tree-file—文件树中的文件条目。

数据属性

部分元素暴露了可用作 CSS 选择器的数据属性。激活状态 (data-active)：

nav-dropdown-item[data-active]—导航下拉菜单中的激活项。
mobile-nav-tabs-item[data-active]—移动导航中的激活标签页。
sidebar-group[data-active]—激活的侧边栏分组。
#sidebar-content li[data-active]—激活的侧边栏链接。
.nav-tabs-item[data-active]—激活的顶部导航标签页。仅适用于简单标签页；带有下拉菜单的标签页不会接收 data-active。注意前导的 .：它针对的是标准 <a> 元素上的类，与大多数使用自定义元素名称的其他组件不同。
toc-item[data-active]—激活的目录项。
toc-item[data-active-deepest]—最深层激活的目录项。仅出现在当前可见的确切标题上，与 data-active 不同，后者也会设置在其父级标题上。

组件名称 (data-component-name)：使用 data-component-name 来定位特定的 UI 组件，该选择器在内部类名更改后仍然有效。

[data-component-name="mermaid-container"]—Mermaid 图表容器，包含缩放控件覆盖层。
[data-component-name="mermaid-controls-wrapper"]—Mermaid 缩放和平移控件。
[data-component-name="primary-header-button"]—主要头部按钮。仅限 Sequoia 主题。
[data-component-name="theme-toggle"]—主题切换开关。

组件部分 (data-component-part)：使用 data-component-part 来定位组件内的子元素。

[data-component-part="contact-support-button"]—助手面板中联系支持链接的 <a> 包装器。
[data-component-part="contact-support-icon"]—包裹图标的 <span>。
[data-component-part="contact-support-text"]—包含标签的 <p> 元素。

Badge 属性：

[data-badge]—任何 badge 元素。
[data-badge][data-color="blue"]—按颜色筛选的 badge。
[data-badge][data-size="sm"]—按尺寸筛选的 badge。

当前路径 (data-current-path)：使用 data-current-path 在特定页面或子路径上应用自定义 CSS 样式。

html[data-current-path="/"]—匹配根页面。
html[data-current-path="/quickstart"]—匹配特定页面。
html[data-current-path^="/api-reference/"]—匹配某个部分下的任何页面。

自定义 JavaScript

自定义 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');

请谨慎使用，避免造成安全漏洞。

设置 API Playground 服务器变量

使用 window.mintlify.api.playground.setServerVariables，通过自定义 JavaScript 预填充 OpenAPI 服务器变量。当页面加载后才能获得这些值时使用此方法，例如身份验证 SDK 初始化完成或租户发生变化时。该方法会立即更新已打开的 API Playground，也会应用到之后打开的 Playground。传入一个值为字符串的对象。每次调用都会替换完整的运行时覆盖值。省略的键会被移除，无效值会被忽略。运行时值优先于 OpenAPI 默认值和已保存的服务器变量。

Set API Playground server variables

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

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

Clear API Playground server variables

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

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

只能从客户端代码设置非机密值。不要在服务器变量中包含 API 密钥、令牌或其他凭据。

访问已登录用户的数据

如果你的站点启用了身份验证，自定义脚本可以通过 window.mintlify.user 读取已登录用户。它与 MDX 页面中暴露的 user 变量是同一个对象，因此对应你用户数据中的 content 字段。由于自定义脚本会在用户信息解析之前运行，请监听 mintlify:user 事件，以便在用户对象可用时做出响应。该事件会在用户信息解析时触发，之后每次发生变化也会再次触发。事件的 detail 是用户对象；当访客处于未登录状态时，则为 null。

Read the user after it resolves

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

  renderAppLauncher(user);
});

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

Read the current user

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

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

你放入用户 content 字段的所有内容都会暴露给客户端脚本。不要在其中包含不应在浏览器中被读取的机密或凭据。

快速入门

创建内容

管理站点

Agent

Assistant

面向 Agent 的内容

搜索与 SEO

编写 API 文档

集成

参考

使用 Tailwind CSS 进行样式设计

添加自定义 CSS

ID 选择器

元素选择器

自定义 JavaScript

设置 API Playground 服务器变量

访问已登录用户的数据

​使用 Tailwind CSS 进行样式设计

​添加自定义 CSS

​ID 选择器

​元素选择器

​自定义 JavaScript

​设置 API Playground 服务器变量

​访问已登录用户的数据

使用 Tailwind CSS 进行样式设计

添加自定义 CSS

ID 选择器

元素选择器

自定义 JavaScript

设置 API Playground 服务器变量

访问已登录用户的数据