自定义脚本

使用 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');

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

访问已登录用户的数据

如果你的站点启用了身份验证，自定义脚本可以通过 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 字段的所有内容都会暴露给客户端脚本。不要在其中包含不应在浏览器中被读取的机密或凭据。

快速入门

组织

自定义

创建内容

编写 API 文档

部署

优化

使用 Tailwind CSS 进行样式设计

添加自定义 CSS

ID 选择器

元素选择器

自定义 JavaScript

访问已登录用户的数据

​使用 Tailwind CSS 进行样式设计

​添加自定义 CSS

​ID 选择器

​元素选择器

​自定义 JavaScript

​访问已登录用户的数据

使用 Tailwind CSS 进行样式设计

添加自定义 CSS

ID 选择器

元素选择器

自定义 JavaScript

访问已登录用户的数据