Page is under construction.

Check the github issues for ways to contribute! Or provide your feedback in this quick form

文档风格指南

本指南涵盖样式约定、Mintlify 特定的陷阱以及贡献到 Livepeer 文档的最佳实践。

适用于 Mintlify 的生产级样式

框架：CSS 自定义属性（CSS 变量）

Mintlify 使用 CSS 自定义属性（CSS 变量）作为生产级样式框架。 这是 Mintlify 文档中主题的官方支持方法。

主题架构

文档使用CSS 自定义属性 定义在 style.css 仓库根目录。这是 ONLY适用于Mintlify文档的生产级样式方法。 不要使用：

❌ JavaScript主题对象（ThemeData，themeStyles.jsx） - 已弃用
❌ 内联样式对象使用硬编码颜色
❌ 基于 JavaScript 的主题切换

改用：

✅ CSS 自定义属性 (--variable-name)
✅ 全局 CSS 变量在 style.css
✅ Mintlify 主题配置在 docs.json

颜色系统

所有主题颜色都定义为 CSS 自定义属性在 style.css:

变量	浅色模式	深色模式	使用
`--accent`	`#3CB540` (翡翠绿)	`#2b9a66` (深翡翠)	重点内容、图标、链接
`--accent-dark`	`#18794E`	`#18794E`	步骤图标，强调
`--hero-text`	`#181C18`	`#E0E4E0`	标题，标题
`--text`	`#717571`	`#A0A4A0`	正文
`--muted-text`	`#9ca3af`	`#6b7280`	次要文字
`--background`	`#ffffff`	`#0d0d0d`	页面背景
`--card-background`	`#f9fafb`	`#1a1a1a`	卡片、容器
`--border`	`#e5e7eb`	`#333333`	边框，分隔线
`--button-text`	`#ffffff`	`#ffffff`	按钮文本

使用 CSS 自定义属性

内联样式（推荐）

<div style={{ 
  color: "var(--accent)", 
  border: "1px solid var(--border)",
  background: "var(--card-background)"
}}>
  Content
</div>

组件级 CSS

export const MyComponent = () => {
  return (
    <>
      <div className="my-component">
        Content
      </div>
      <style>{`
        .my-component {
          color: var(--text);
          background: var(--card-background);
          border: 1px solid var(--border);
        }
      `}</style>
    </>
  );
};

style.css 中的全局 CSS

.my-custom-class {
  color: var(--accent);
  background: var(--card-background);
}

主题切换的工作原理

Mintlify 会自动添加 .dark 类到 <html> 当启用深色模式时，element。CSS 变量会根据主题自动切换：

:root {
  --accent: #3CB540; /* Light mode */
}

.dark {
  --accent: #2b9a66; /* Dark mode */
}

无需 JavaScript - 主题切换完全由 CSS 处理。

颜色规则

使用案例	方法
品牌颜色（绿色）	使用`--accent`或`--accent-dark`
标题	使用 `--hero-text`
正文	使用 `--text`
次要文本	使用 `--muted-text`
背景	使用 `--background` 或 `--card-background`
边框	使用 `--border`
语义颜色（错误、警告、成功）	保持固定（不要主题）
白色文字在绿色标题上	保持固定为`#fff`

已弃用的方法

不要使用这些：

ThemeData 对象 - snippets/styles/themeStyles.jsx 是 ** 已弃用 **

// ❌ WRONG - DO NOT USE
import { ThemeData } from "/snippets/styles/themeStyles.jsx";
<div style={{ color: ThemeData.light.accent }}>Content</div>

硬编码颜色 - 永远不要硬编码应随主题变化的十六进制值
```
// ❌ WRONG - DO NOT USE
<div style={{ color: "#3CB540" }}>Content</div>
```
JavaScript 主题切换 - 不需要，CSS 会自动处理

不要做什么

❌ 不要导入或使用 ThemeData from themeStyles.jsx
❌ 不要硬编码应适应主题的十六进制颜色
❌ 不要使用通用灰色而没有检查主题兼容性
❌ 不要创建语义颜色（信任评分、错误状态）依赖主题
❌ 不要覆盖故意彩色背景上的白色文本
❌ 不要创建自定义 JavaScript 主题对象

样式框架架构

Livepeer 文档使用一个三层样式框架 designed to work within Mintlify’s constraints while maintaining consistency and maintainability.

Framework Layers

Layer 1: Global CSS (`style.css`)

目的: 主题变量和框架级覆盖 应该放在这里：

✅ CSS 自定义属性（主题变量）
✅ Mintlify 组件覆盖（导航、页脚等）
✅ Frame 模式容器类
✅ 在页面间重复使用 5 次以上的模式的实用类

什么是不属于这里的：

❌ 页面特定样式
❌ 组件特定样式（应位于JSX中）
❌ 一次性样式需求

结构:

/* ============================================
   THEME VARIABLES (CSS Custom Properties)
   ============================================ */
:root { /* Light mode */ }
.dark { /* Dark mode */ }

/* ============================================
   FRAMEWORK OVERRIDES (Mintlify-specific)
   ============================================ */
/* Navigation, footer, frame mode containers */

/* ============================================
   UTILITY CLASSES (Reusable patterns)
   ============================================ */
/* Only for patterns used 5+ times across pages */

第二层: JSX 组件 (`snippets/components/**/*.jsx`)

目的: 自包含组件带有内部样式 规则:

✅ 使用 CSS 自定义属性 (var(--accent), var(--text), 等等.)
✅ 样式必须在组件文件中
✅ 使用<style> 标签进行复杂样式设置（伪类、媒体查询）
✅ 对于简单样式使用内联样式对象
❌ 导入外部 CSS 文件
❌ 硬编码主题颜色（使用 CSS 变量）
❌ 使用 “className 而没有对应的 “<style>” 标签

模式 A：内联样式对象（简单组件）

export const MyComponent = () => {
  return (
    <div style={{
      color: "var(--text)",
      backgroundColor: "var(--card-background)",
      border: "1px solid var(--border)",
      padding: "1rem"
    }}>
      Content
    </div>
  );
};

模式 B：样式标签（复杂组件）

export const MyComponent = () => {
  return (
    <>
      <div className="my-component">
        Content
      </div>
      <style>{`
        .my-component {
          color: var(--text);
          background: var(--card-background);
        }
        .my-component:hover {
          border-color: var(--accent);
        }
      `}</style>
    </>
  );
};

模式 C：样式常量（组件内可重用）

export const MyComponent = ({ variant = "default" }) => {
  const baseStyle = {
    color: "var(--text)",
    padding: "1rem"
  };
  
  const variantStyles = {
    default: { border: "1px solid var(--border)" },
    accent: { border: "1px solid var(--accent)" }
  };
  
  return (
    <div style={{ ...baseStyle, ...variantStyles[variant] }}>
      Content
    </div>
  );
};

第3层：MDX 文件 (`v2/pages/**/*.mdx`)

用途: 仅内容 - ZERO 内联样式 规则:

✅ 为所有样式需求使用组件原语
✅ 使用 Mintlify 全局组件（Card, Tabs，Steps等。
✅ 从 /snippets/components/
❌ NO 内联 style={{}} 属性
❌ NO hardcoded colors
❌ 无自定义 className 属性

之前（❌ 错误）:

<div style={{ display: "flex", gap: "1rem" }}>
  <Card>Content 1</Card>
  <Card>Content 2</Card>
</div>

之后（✅ 正确）：

import { FlexContainer } from '/snippets/components/primitives/layout.jsx';

<FlexContainer gap="1rem">
  <Card>Content 1</Card>
  <Card>Content 2</Card>
</FlexContainer>

决策树：此样式应放在何处？

这是主题颜色吗？ → 添加到style.css 作为 CSS 自定义属性
是否在组件中使用？ → 放入 JSX 组件文件（内联或 <style> 标签）
在 MDX 中需要吗？ → 创建/使用组件原语
是否在全球范围内被使用 5+ 次？ → 添加实用类到 style.css
这是特定于页面的吗？ → 创建一个组件原始（不要放在”style.css）

组件原语库

对于 MDX 文件中的常见样式需求，请使用组件原语/snippets/components/primitives/:

布局: FlexContainer, GridContainer, Spacer
表格: StyledTable，TableRow，TableCell
容器：“BorderedBox，CenteredContainer，FullWidthContainer

查看组件库以获得完整的参考。

排版

标题

使用标准的 Markdown 标题（“#，##，###等）的大多数内容。Mintlify 会自动为其设置样式。对于 frame mode 页面, 请使用自定义标题组件:

import { H1, H2, PageHeader } from "/snippets/components/display/frameMode.jsx";

<PageHeader>Main Title</PageHeader>
<H1>Section Title</H1>
<H2>Subsection Title</H2>

注意： Frame 模式组件内部使用 CSS 自定义属性 - 不需要导入 ThemeData。

文本样式

使用粗体 (**text**) 用于强调
使用斜体 (*text*) 适度使用
使用 code（反引号）用于内联代码
用于多行代码的代码块

数学表达式

Mintlify 支持 LaTeX 用于渲染数学表达式。使用正确的语法以确保方程正确显示。

内联数学

使用单个美元符号 $...$ 用于文本中的内联数学表达式：

The voting power is calculated as $V_i = \frac{B_i}{B_T}$ where $B_i$ is bonded stake.

结果： 投票权计算为

V_i = \frac{B_i}{B_T}

where

B_i

is bonded stake.

Block Equations

Use double dollar signs $$...$$ for standalone equations on their own line:

$$
R_t = S_t \cdot r_t
$$

Result:

R_t = S_t \cdot r_t

常用 LaTeX 语法

表达式	语法	结果
分数	$\frac{a}{b}$	$\frac{a}{b}$
下标	$B_i$	$B_i$
上标	$x^2$	$x^2$
希腊字母	$\alpha, \beta, \theta$	$\alpha, \beta, \theta$
求和	$\sum_{i=1}^{n} x_i$	$\sum_{i=1}^{n} x_i$
平方根	$\sqrt{x}$	$\sqrt{x}$
成比例	$\propto$	$\propto$
大于或小于等于	$\geq, \leq$	$\geq, \leq$

关键：不要使用反斜杠分隔符

错误 - 这会导致 MDX 错误：

{/* ❌ WRONG - backslash delimiters break MDX */}
\(B_i\) for inline math
\[R_t = S_t \cdot r_t\] for block math

正确 - 使用美元符号分隔符：

{/* ✅ CORRECT - dollar sign delimiters */}
$B_i$ for inline math
$$R_t = S_t \cdot r_t$$ for block math

LaTeX 配置

你可以配置 LaTeX 渲染在 docs.json 下 styles.latex 如果需要，可以覆盖自动检测。参见 Mintlify LaTeX 文档以获取详细信息。

间距与布局

一致的间距

在各部分之间使用一致的间距
将相关的内容分组在一起
使用分隔符 (<CustomDivider />) 来分隔主要部分

页面布局

门户 - 使用 CardGroups 作为关键入口点
指南 - 使用步骤进行顺序说明
参考 - 使用表格或折叠面板来整理数据
快速入门 - 使用标签页来区分不同路径（操作系统、链上/链下）

组件用法

何时使用组件

选项卡 - 按上下文分离内容（操作系统、工作流类型、用户类型）
视图 - 根据操作系统或用户路径显示不同的内容
步骤 - 顺序说明流程
卡片组 - 用于门户、中心和相关内容的视觉分组
折叠面板 - 可展开的详细信息部分
要点 - 重要注意事项、技巧、警告和信息框

要点类型

<Info> - 一般信息和技巧
<Tip> - 有帮助的建议
<Warning> - 重要警告
<Danger> - 关键警告
<Note> - 额外上下文

优先使用自定义组件进行链接和导航

偏好: 使用自定义组件来创建链接、卡片、引用和其他视觉上吸引人的元素，而不是普通的 Mintlify 链接。 为什么自定义组件提供更出色的视觉设计、一致的主题、增强的用户体验以及与 Livepeer 文档设计系统的更好集成。 要使用的自定义组件：

链接使用 “<GotoLink>和 “<GotoCard>而不是普通 markdown 链接或 Mintlify <Card> with href
报价: 使用 <Quote> 和 <FrameQuote> 而不是普通的引用块
卡片使用 “<GotoCard> 用于带有更好样式的导航卡片
提示框使用 “<CustomCallout>和 “<TipWithArrow> 以获得增强的视觉提示
外部链接: 使用 <DoubleIconLink> 用于外部链接（GitHub 等）

示例:

{/* ❌ Plain markdown link */}
[Getting Started](/get-started)

{/* ✅ Custom component with better styling */}
import { GotoLink } from '/snippets/components/primitives/links.jsx';
<GotoLink label="Getting Started" relativePath="/get-started" icon="arrow-right" />

{/* ❌ Plain blockquote */}
> This is a quote

{/* ✅ Custom quote component with attribution */}
import { FrameQuote } from '/snippets/components/display/quote.jsx';
<FrameQuote author="John Doe" source="Livepeer Blog" href="https://livepeer.org/blog">
  This is a quote with better visual design.
</FrameQuote>

{/* ❌ Basic Mintlify Card with href */}
<Card title="API Reference" href="/api/reference">
  API documentation
</Card>

{/* ✅ Custom GotoCard with enhanced styling */}
import { GotoCard } from '/snippets/components/primitives/links.jsx';
<GotoCard
  label="API Reference"
  relativePath="/api/reference"
  icon="book"
  text="Complete API documentation with examples"
  cta="View Docs"
/>

何时使用普通链接:

段落中的内联链接（Markdown 链接是可以的）
代码示例或技术引用中的链接
不需要视觉强调的链接

参见组件库用于所有可用的自定义组件。

Mintlify 覆盖与最佳实践

我们的样式框架有意覆盖了一些 Mintlify 的默认建议，以便更好地适应 Mintlify 的约束并保持一致性。

覆盖：“使用 Tailwind 类”

Mintlify 建议: 使用 Tailwind 实用类
我们的方法: ❌ 不要使用 Tailwind - 使用组件原语
原因: 在MDX中使用Tailwind类会增加维护负担并降低语义意义。组件原始功能更易于维护且自我说明。 示例:

{/* ❌ Don't use Tailwind */}
<div className="flex gap-4 items-center">
  <Card>Content</Card>
</div>

{/* ✅ Use component primitives */}
<FlexContainer gap="1rem" align="center">
  <Card>Content</Card>
</FlexContainer>

覆盖：“内联样式适用于快速修复”

Mintlify 建议: 在 MDX 中内联样式是可以接受的
我们的方法: ❌ MDX 中没有内联样式，只有在 JSX 组件中
原因一致性与可维护性。MDX 中的内联样式会增加维护主题一致性的难度，并可能导致视觉上的不一致。 示例：

{/* ❌ Don't use inline styles in MDX */}
<div style={{ display: "flex", gap: "1rem" }}>
  <Card>Content</Card>
</div>

{/* ✅ Use component primitives */}
<FlexContainer gap="1rem">
  <Card>Content</Card>
</FlexContainer>

覆盖：“对所有内容使用全局 CSS”

Mintlify 建议：将所有样式放在 “style.css
我们的方法: ✅ 仅在 ” 中使用主题变量和框架覆盖style.css
原因: Mintlify 仅允许一个全局 CSS 文件。将所有内容放在一起会使维护变得困难。组件特定的样式应放在 JSX 组件中。 输入内容 style.css:

✅ 主题变量 (CSS 自定义属性)
✅ Mintlify 组件覆盖（导航栏、页脚）
✅ 帧模式容器类
✅ 全局使用5次以上的实用类

什么不应该放在 style.css:

❌ 组件特定样式（放在 JSX 中）
❌ 页面特定样式（创建组件原语）
❌ 一次性样式需求（创建组件原语）

覆盖：“组件样式可以是外部的”

Mintlify 建议: 组件的外部 CSS 文件
我们的方法❌ 样式必须位于 JSX 组件文件中
原因_Mintlify 不可靠地支持在组件中导入 CSS。内联样式和<style>组件内的标签工作方式一致。 模式：

{/* ✅ Styles within component */}
export const MyComponent = () => {
  return (
    <>
      <div className="my-component">Content</div>
      <style>{`
        .my-component {
          color: var(--text);
        }
      `}</style>
    </>
  );
};

Mintlify 注意事项与限制

关键限制

1. 导入路径必须是绝对路径

// ✅ Correct - absolute path from repo root
import { MyComponent } from '/snippets/components/MyComponent.jsx';

// ❌ Wrong - relative paths don't work
import { MyComponent } from '../components/MyComponent.jsx';

2. 必须包含文件扩展名

// ✅ Include extension
import { Component } from '/snippets/Component.jsx';

// ❌ May not resolve
import { Component } from '/snippets/Component';

3. 无法导入到组件文件中

您不能将数据或其他组件导入到JSX组件文件中：

// ❌ WRONG - This will fail
// snippets/components/MyComponent.jsx
import { themeColor } from '/snippets/styles/themeStyles.jsx';

export const MyComponent = () => {
  return <div style={{ color: themeColor.light.accent }}>Hello</div>;
};

解决方案：在使用该组件的MDX文件中进行导入：

// ✅ CORRECT
// MyPage.mdx
import { MyComponent } from '/snippets/components/MyComponent.jsx';
import { ThemeData } from '/snippets/styles/themeStyles.jsx';

<MyComponent />
// MyComponent can access ThemeData from parent scope

4. JSX 文件不能导入其他 JSX 文件

Mintlify 不允许 JSX 文件导入其他 JSX 文件。这就是我们使用 MDX-in-MDX 模式的原因。

5. MDX 作用域继承

当将 MDX 文件导入到其他 MDX 文件中时：

✅ 子 MDX 继承父级作用域的 props - 父组件的导入在用作组件 props 时有效
❌ 子 MDX 不能直接继承父作用域进行 JSX 插值 - 用作 ” 的变量{variable} 可能需要重新导入
✅ 子组件可以导入自己的变量 - 如果子组件需要父组件未导入的内容

示例:

// Parent.mdx
import { DOCKER_CODE } from '/snippets/data/gateways/code.jsx'
import ChildView from '/snippets/pages/ChildView.mdx'

<ChildView />

// ChildView.mdx
{/* Can use DOCKER_CODE as props */}
<CustomCodeBlock {...DOCKER_CODE.install} />  {/* ✅ Works */}

{/* But direct interpolation may need re-import */}
<Badge>{latestVersion}</Badge>  {/* ❌ May need import */}

6. React Hooks 是全局的

Mintlify 会全局提供 React hooks - 不需要导入：

// ✅ Works - hooks available without import
export function MyComponent() {
  const [count, setCount] = useState(0);
  useEffect(() => { /* ... */ }, []);
  return <div>{count}</div>;
}

// ❌ Not needed - will cause errors
import React, { useState, useEffect } from 'react';

7. 图标组件行为

关键: Mintlify’s <Icon> 组件将自定义图标渲染为 <img alt="Image"> 元素，NOT 内联 SVG。

// ❌ This will NOT work - color styling has no effect
<span style={{ color: "#3CB540" }}>
  <Icon icon="/path/to/icon.svg" size={20} />
</span>

解决方案： 使用与主题相关的 SVG 文件并包含内部 CSS，或为每个主题使用不同的文件。

8. Mintlify 全局组件

这些组件是全局可用的 - 不要导入它们:

React, Frame, Card, Icon, Steps, Step, Tabs, Tab
Note, Warning, Info, Tip, Danger
Accordion, Columns, CardGroup, CodeBlock, Expandable, Badge, Tooltip

// ✅ Correct - use directly
<Card title="Title">Content</Card>
<Tabs>
  <Tab title="Tab 1">Content</Tab>
</Tabs>

// ❌ Wrong - don't import
import { Card, Tabs } from "@mintlify/components";

严重: Mintlify 全局组件 不能存储在变量中 - 它们必须直接作为 JSX 使用:

// ❌ WRONG - Will cause "ReferenceError: Expandable is not defined"
const componentMap = {
  expandable: Expandable,
  accordion: Accordion
};
const Component = componentMap[component];

// ✅ CORRECT - Use conditional rendering with direct JSX
if (component === "expandable") {
  return <Expandable {...props}>{content}</Expandable>;
}
return <Accordion {...props}>{content}</Accordion>;

9. JSX 注释不会阻止 MDX 解析

重要: JSX 注释 ({/* */}) 在 MDX 文件中 do NOT防止 MDX 解析它们内部的内容。MDX 仍然会尝试评估注释内的 JSX 组件和表达式。

{/* ❌ WRONG - MDX will still try to parse CustomCodeBlock */}
{/* 
<CustomCodeBlock codeString="test" />
*/}

{/* ✅ CORRECT - Remove the entire section, don't comment it */}
{/* Code components temporarily unavailable - see component-bugs.md */}

如果您需要临时禁用组件部分：

删除整个部分 从 MDX 文件中
添加一个解释原因的注释 它被删除了
**文档中docs/PLAN/errors/component-bugs.md**如果是组件问题
不要使用 JSX 注释 将组件用法 “注释掉”

9. 帧模式限制

帧模式 (mode: frame在 frontmatter 中移除了所有默认的 Mintlify 样式。当使用 frame 模式时：

默认的 markdown 标题可能无法正确渲染
使用来自 frameMode.jsx
所有样式必须自定义
Mintlify 组件仍然有效，但会失去默认样式
保留响应式布局基本组件style.css (.frame-mode-container, .frame-mode-hero-full, 帧分页)
在共享 JSX 组件中保持门户/页面特定结构（例如/snippets/components/domain/SHARED/Portals.jsx)
不要在组件样式中直接使用固定的断开常量（例如硬编码96px，20px或固定% 宽度)
优先使用 CSS 变量 + 断点进行帧模式布局，并使用 CSS 自定义属性 (var(--...)) 进行主题设置

导入模式

正确模式：在MDX中导入，在组件中使用

// ✅ MyPage.mdx
import { MyComponent } from '/snippets/components/MyComponent.jsx';
import { DOCKER_CODE } from '/snippets/data/gateways/code.jsx';

<MyComponent />

// ✅ MyComponent.jsx - uses CSS Custom Properties (production-grade)
export const MyComponent = () => {
  return (
    <div style={{ color: "var(--accent)" }}>
      <CustomCodeBlock {...DOCKER_CODE.install} />
    </div>
  );
};

Git工作流程

分支管理

始终从 ” 创建一个新分支docs-v2:

git checkout docs-v2
git pull
git checkout -b docs-plan/XX-task-name

永远不要直接在 ” 上工作:

docs-v2（活跃的文档分支）
main或者master
任何其他代理正在使用的分支

分支命名： 使用模式 docs-plan/XX-task-name 其中 XX 是任务编号。

最佳实践

代码组织

将组件保留在 /snippets/components/ 按用途组织：
- primitives/ - 基础 UI 元素
- layout/ - 布局组件
- display/ - 媒体和嵌入
- content/ - 内容显示
- integrations/ - 外部服务
- domain/ - 领域特定组件
保持数据在 /snippets/data/ 以用于可重用的代码字符串和变量
使用 /snippets/pages/ 用于导入到主页面中的模块化 MDX 内容

写作风格

保持清晰简洁 - 为不同技术背景的用户提供内容
使用示例 - 包括代码示例和现实场景
提供上下文 - 解释原因，而不仅仅是方法
链接相关内容 - 帮助用户发现相关信息
测试两种主题 - 确认内容在浅色和深色模式下看起来都良好

组件指南

仅使用 CSS 自定义属性 - 永远不要使用 ThemeData 或硬编码颜色
从 style.css 引用变量 - 所有主题颜色都在 style.css as CSS variables
Test Components - Ensure components render correctly
正确处理子元素 - 映射时始终将子元素作为数组处理
文档属性 - 为组件 props 添加 JSDoc 注释
提供示例 - 在 ” 中添加示例examples/每个组件的文件夹

组件不可变性

关键规则: snippets/components/ 是不可变的 永远不要修改文件中的snippets/components/ - 这些组件被许多页面使用。任何更改都可能导致现有功能失效。 允许：

创建新组件
修改使用组件的 MDX 文件
修复 MDX 导入和使用

禁止:

修改现有组件文件
更改组件函数签名
添加/移除组件导出
更改组件逻辑

异常: 仅在用户明确请求且在确认影响评估后。 如果一个组件似乎有错误:

注释掉组件部分 在使用它的 MDX 文件中
验证页面是否可以正常渲染没有该部分
如果页面正确渲染 → 组件是问题所在
记录错误 在 docs/PLAN/errors/component-bugs.md 中:
- 组件名称和文件路径
- 控制台中的错误信息
- 发生错误的页面
- 验证注释掉代码可以修复页面
- 组件修复建议（但不要实现）

不要修复组件 - 组件在未经用户明确授权的情况下是不可变的。

文件命名

使用连字符命名文件：my-component.mdx
使用 PascalCase 命名组件：MyComponent
使用能说明用途的名称

测试清单

在提交文档之前:

内容在暗色模式（默认）下显示正确
内容在亮色模式下显示正确
所有链接都有效并指向正确页面
代码示例准确且经过测试
图片已加载并具有适当的替代文本
组件使用主题感知的颜色
没有应根据主题调整的硬编码颜色
组件正确渲染
浏览器开发者工具中没有控制台错误
已检查并修复 MDX 语法错误
所有页面已在无头浏览器中验证（请参阅下面的验证要求）

验证要求

MDX 语法检查

在声明工作完成之前，请检查 MDX 文件：

使用 linting 工具检查所有已修改的 MDX 文件
检查以下内容：
- 未关闭的 JSX 标签
- 无效的导入语法
- 缺少 frontmatter
- 语法错误
在认为工作完成之前修复任何 MDX 错误

无头浏览器验证

在宣布工作完成之前，在无头浏览器中验证每个页面：

使用 Puppeteer 或类似工具加载每个页面
等待网络空闲
检查控制台错误（过滤测试脚本的输出）
验证内容长度 > 500 字符
验证 H1 元素存在
检查 404 错误

过滤误报：

忽略测试脚本中的“require is not defined”
忽略与“puppeteer”相关的错误
忽略“fs已经声明过”的错误
关注实际组件错误

报告必须显示:

页面 URL
内容长度
H1 文本
实际控制台错误列表（如果有）
状态：✅ OK 或 ❌ 错误

URL 结构验证

Mintlify 页面使用完整路径结构:

页面路径在 docs.json: v2/resources/documentation-guide/component-library/primitives
URL: /v2/resources/documentation-guide/component-library/primitives

不要假设URL模式 - 通过测试实际URL进行验证。

Mintlify 主题配置

Mintlify 还支持主题配置在 docs.json:

{
  "theme": "palm",
  "colors": {
    "primary": "#3CB540",
    "light": "#2b9a66",
    "dark": "#3CB540"
  }
}

这控制 Mintlify 的内置组件（按钮、链接等）。对于自定义样式，请始终在 style.css.

预提交钩子

此仓库使用 Git 预提交钩子来自动强制执行风格指南规则。这些钩子是强制性的，违反风格指南的提交将被阻止。

检查内容

预提交钩子会自动检查：

已弃用 ThemeData 用法 - 阻止导入 ThemeData from snippets/styles/themeStyles.jsx
硬编码主题颜色 - 警告不要使用直接的十六进制颜色代码，应使用CSS自定义属性
相对片段导入 - 从 “snippets/” 导入的标志，使用相对路径而不是绝对路径
不必要的导入 - 警告关于 Mintlify 全局可用组件和 React 钩子的显式导入
语法验证 - 检查 MDX、JSON、Shell 和 JavaScript 语法
浏览器验证 - 测试 MDX 页面在无头浏览器中是否实际正确渲染（如果mint dev正在运行)

安装

必须的: 您必须在提交任何代码之前安装钩子：

./.githooks/install.sh

违反规定会发生什么

如果您尝试提交违反样式指南的代码：

提交已 被阻止
您将收到一条详细的错误消息，列出所有违规行为
您必须在再次提交之前修复违规内容

受保护的 `.allowlist` 编辑（仅限人工）

文件受预提交检查保护。.allowlist如果一个人为需要编辑，则必须通过.allowlist，使用：

git commit -m "Update .allowlist" --trailer "allowlist-edit=true"

此覆盖仍会运行所有其他预提交检查。如果人类有意需要允许文件删除，请使用：

git commit -m "Remove obsolete files" --trailer "allow-deletions=true"

此删除覆盖还会运行所有其他预提交检查。

示例错误输出

╔═══════════════════════════════════════════════════════════════╗
║  STYLE GUIDE VIOLATIONS DETECTED - COMMIT BLOCKED           ║
╚═══════════════════════════════════════════════════════════════╝

Found 2 violation(s):

❌ my-component.jsx: Uses deprecated ThemeData - use CSS Custom Properties instead
⚠️  my-page.mdx: Contains hardcoded theme colors - use CSS Custom Properties (var(--accent), etc.)

📖 MANDATORY: Read the Style Guide before committing:
   v2/resources/documentation-guide/style-guide.mdx

浏览器验证

这些钩子包括无头浏览器验证，用于测试MDX文件在浏览器中实际渲染。这可以捕获：

组件中的运行时错误
失败的导入
控制台错误
渲染失败

注意: 浏览器验证需要 mint dev 正在运行。如果未运行，将跳过检查（不会阻止提交）。

全面的测试套件

该存储库包含一个全面的测试套件，用于验证所有样式指南规则及其他内容：

运行测试

# Run all tests
npm test

# Run specific test suites
npm run test:style      # Style guide validation
npm run test:mdx        # MDX syntax validation
npm run test:spell      # UK English spelling
npm run test:quality    # Quality checks (alt text, links, frontmatter)
npm run test:browser    # Browser rendering tests

哪些内容会被测试

样式指南测试 (test:style):

CSS 自定义属性用法（不使用 ThemeData，不使用硬编码颜色）
MDX 文件中没有内联样式
没有 Tailwind 类
绝对导入路径
文件命名规范
组件不可变性警告

MDX 验证 (test:mdx):

Frontmatter 验证
未闭合的 JSX 标签
无效的 import 语法
MDX 作用域继承问题

拼写测试 (test:spell):

英国英语拼写验证
技术术语的自定义词典 (Livepeer, Arbitrum, 等等)
排除代码块和前言

质量检查 (test:quality):

图像替代文本的存在
前导信息的完整性
内部链接验证
SEO 元数据验证

浏览器测试 (test:browser):

页面在无头浏览器中的渲染
控制台错误检测
主题测试（浅色/深色）
内容验证（H1，内容长度）

测试套件在预提交钩子（暂存/快速模式）和 CI/CD 中自动运行。在拉取请求 CI 中，静态检查是按更改的文件作用域进行阻塞处理，而浏览器扫描保持完整的路由覆盖。有关钩子的详细信息，请参阅 Git 钩子文档.

资源

组件库 - 完整组件参考
Mintlify 文档 - 官方 Mintlify 文档
Mintlify 行为指南 - 全面的 Mintlify 常见问题
Git 钩子文档 - 完成预提交钩子文档
style.css - 全局 CSS 自定义属性用于主题设置

下一步

查看组件库以查看可用组件
检查代码片段库存以查看所有可用的代码片段
阅读 Mintlify 行为指南以了解详细的注意事项
查看贡献文档以了解贡献指南
安装 Git 钩子：./.githooks/install.sh

Home

Documentation Guide

Livepeer Concepts

Developer References

Gateway References

Orchestrator References

LPT & Delegator References

Community Resources

Partner Resources

Help Center

Technical References

Changelog

​文档风格指南

​适用于 Mintlify 的生产级样式

​框架：CSS 自定义属性（CSS 变量）

​主题架构

​颜色系统

​使用 CSS 自定义属性

​内联样式（推荐）

​组件级 CSS

​style.css 中的全局 CSS

​主题切换的工作原理

​颜色规则

​已弃用的方法

​不要做什么

​样式框架架构

​Framework Layers

​Layer 1: Global CSS (style.css)

​第二层: JSX 组件 (snippets/components/**/*.jsx)

​第3层：MDX 文件 (v2/pages/**/*.mdx)

​决策树：此样式应放在何处？

​组件原语库

​排版

​标题

​文本样式

​数学表达式

​内联数学

​Block Equations

​常用 LaTeX 语法

​关键：不要使用反斜杠分隔符

​LaTeX 配置

​间距与布局

​一致的间距

​页面布局

​组件用法

​何时使用组件

​要点类型

​优先使用自定义组件进行链接和导航

​Mintlify 覆盖与最佳实践

​覆盖：“使用 Tailwind 类”

​覆盖：“内联样式适用于快速修复”

​覆盖：“对所有内容使用全局 CSS”

​覆盖：“组件样式可以是外部的”

​Mintlify 注意事项与限制

​关键限制

​1. 导入路径必须是绝对路径

​2. 必须包含文件扩展名

​3. 无法导入到组件文件中

​4. JSX 文件不能导入其他 JSX 文件

​5. MDX 作用域继承

​6. React Hooks 是全局的

​7. 图标组件行为

​8. Mintlify 全局组件

​9. JSX 注释不会阻止 MDX 解析

​9. 帧模式限制

​导入模式

​正确模式：在MDX中导入，在组件中使用

​Git工作流程

​分支管理

​最佳实践

​代码组织

​写作风格

​组件指南

​组件不可变性

​文件命名

​测试清单

​验证要求

​MDX 语法检查

​无头浏览器验证

​URL 结构验证

文档风格指南

适用于 Mintlify 的生产级样式

框架：CSS 自定义属性（CSS 变量）

主题架构

颜色系统

使用 CSS 自定义属性

内联样式（推荐）

组件级 CSS

style.css 中的全局 CSS

主题切换的工作原理

颜色规则

已弃用的方法

不要做什么

样式框架架构

Framework Layers

Layer 1: Global CSS (`style.css`)

第二层: JSX 组件 (`snippets/components/**/*.jsx`)

第3层：MDX 文件 (`v2/pages/**/*.mdx`)

决策树：此样式应放在何处？

组件原语库

排版

标题

文本样式

数学表达式

内联数学

Block Equations

常用 LaTeX 语法

关键：不要使用反斜杠分隔符

LaTeX 配置

间距与布局

一致的间距

页面布局

组件用法

何时使用组件

要点类型

优先使用自定义组件进行链接和导航

Mintlify 覆盖与最佳实践

覆盖：“使用 Tailwind 类”

覆盖：“内联样式适用于快速修复”

覆盖：“对所有内容使用全局 CSS”

覆盖：“组件样式可以是外部的”

Mintlify 注意事项与限制

关键限制

1. 导入路径必须是绝对路径

2. 必须包含文件扩展名

3. 无法导入到组件文件中

4. JSX 文件不能导入其他 JSX 文件

5. MDX 作用域继承

6. React Hooks 是全局的

7. 图标组件行为

8. Mintlify 全局组件

9. JSX 注释不会阻止 MDX 解析

9. 帧模式限制

导入模式

正确模式：在MDX中导入，在组件中使用

Git工作流程

分支管理

最佳实践

代码组织

写作风格

组件指南

组件不可变性

文件命名

测试清单

验证要求

MDX 语法检查

无头浏览器验证

URL 结构验证

Mintlify 主题配置

预提交钩子

检查内容

安装

违反规定会发生什么

受保护的 `.allowlist` 编辑（仅限人工）

示例错误输出

浏览器验证

全面的测试套件

运行测试

哪些内容会被测试

资源