Mintlify uses CSS Custom Properties (CSS Variables) as the production-grade styling framework. This is the official, supported approach for theming in Mintlify documentation.
The documentation uses CSS Custom Properties defined in style.css at the repository root. This is the ONLY production-grade approach for styling Mintlify documentation.DO NOT USE:
The Livepeer documentation uses a three-layer styling framework designed to work within Mintlify’s constraints while maintaining consistency and maintainability.
Mintlify auto-loads all .css files in the repository root. Any classes defined in any .css file are available globally in all MDX files. The repo uses style.css as the single source of truth for all design tokens and framework overrides.Mintlify also auto-loads all .js files from the content directory on every page. Be aware of this for security – do not place scripts in the content directory unless they are intended to run on every page.
Mintlify ships Tailwind CSS v3 and it is available in both MDX files and JSX components. However:
Arbitrary values are NOT supported – w-[200px], bg-[#3CB540] will not work
Predefined classes only – flex, gap-4, grid-cols-2, p-4, rounded etc.
Responsive prefixes work – md:grid-cols-2, lg:grid-cols-3
Dark mode prefixes work – dark:hidden, dark:block, dark:bg-gray-800
When to use Tailwind: Layout structure (flex, grid, spacing, visibility toggling). Tailwind responsive classes (md:, lg:) are the recommended approach for responsive layouts.When NOT to use Tailwind: Colours (use CSS Custom Properties instead – Tailwind arbitrary values are not supported, and our colour system uses --lp-* tokens).
Layout shift warning: Mintlify explicitly warns that using the style prop (inline styles) can cause a layout shift on page load, especially on custom mode pages. Use Tailwind CSS classes or CSS Custom Properties in style.css instead of style={{}} to avoid shifts or flickering.
When a component needs pseudo-classes, media queries, or must override Mintlify built-in component styles, use a scoped <style> block with a generated ID:
Rule: Single-property CSS variable usage inline is acceptable (e.g. style={{ color: "var(--lp-color-accent)" }}). Multi-property layout styles must use a component or Tailwind classes.
<Icon icon="ethereum" /> is a standard FontAwesome icon – no custom component needed.The full semantic icon reference lives at docs-guide/tooling/reference-maps/icon-map.mdx with usage guidance and scan counts.
Green is context-dependent: in solutions it means “Livepeer Product”, in gateways it means “Dual workload”, in pricing it means “ETH(wei)”. Context determines meaning.
Use standard Markdown headings (#, ##, ###, etc.) for most content. Mintlify automatically styles these.For frame mode pages, use custom heading components:
Preference: Use custom components for links, cards, quotes, and other visually appealing elements instead of plain Mintlify links.Why: Custom components provide better visual design, consistent theming, enhanced user experience, and better integration with the Livepeer documentation design system.Custom Components to Use:
Links: Use <GotoLink> and <GotoCard> instead of plain markdown links or Mintlify <Card> with href
Quotes: Use <Quote> and <FrameQuote> instead of plain blockquotes
Cards: Use <GotoCard> for navigation cards with better styling
Callouts: Use <CustomCallout> and <TipWithArrow> for enhanced visual callouts
External Links: Use <DoubleIconLink> for external links (GitHub, etc.)
Examples:
{/* ❌ Plain markdown link */}[Getting Started](/get-started){/* ✅ Custom component with better styling */}import { GotoLink } from '/snippets/components/elements/links/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/displays/quotes/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/elements/links/Links.jsx';<GotoCard label="API Reference" relativePath="/api/reference" icon="book" text="Complete API documentation with examples" cta="View Docs"/>
When to Use Plain Links:
Inline links within paragraphs (markdown links are fine)
Our styling framework intentionally overrides some Mintlify default recommendations to work better within Mintlify’s constraints and maintain consistency.
Mintlify suggests: Use Tailwind utility classes Our approach: ❌ Don’t use Tailwind - use component primitives Reason: Tailwind classes in MDX create maintenance burden and reduce semantic meaning. Component primitives are more maintainable and self-documenting.Example:
{/* ❌ 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>
Override: “Inline styles are fine for quick fixes”
Mintlify suggests: Inline styles acceptable in MDX Our approach: ❌ No inline styles in MDX, only in JSX components Reason: Consistency and maintainability. Inline styles in MDX make it harder to maintain theme consistency and create visual inconsistencies.Example:
{/* ❌ 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>
Mintlify suggests: Put all styles in style.css Our approach: ✅ Only theme variables and framework overrides in style.css Reason: Mintlify only allows one global CSS file. Putting everything there makes it unmaintainable. Component-specific styles belong in JSX components.What goes in style.css:
Mintlify suggests: External CSS files for components Our approach: ❌ Styles must be within JSX component files Reason: Mintlify doesn’t support CSS imports in components reliably. Inline styles and <style> tags within components work consistently.Pattern:
// ✅ Correct - absolute path from repo rootimport { MyComponent } from '/snippets/components/MyComponent.jsx';// ⚠️ Avoid - relative paths resolve but are harder to validate and grepimport { MyComponent } from '../components/MyComponent.jsx';
✅ Child MDX inherits parent scope for props - Parent’s imports work when used as component props
❌ Child MDX may NOT inherit parent scope for direct JSX interpolation - Variables used as {variable} may need re-import
✅ Child can import its own variables - If the child needs something the parent doesn’t import
Example:
// Parent.mdximport { 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 */}
Mintlify provides React hooks globally - no imports needed:
// ✅ Works - hooks available without importexport function MyComponent() { const [count, setCount] = useState(0); useEffect(() => { /* ... */ }, []); return <div>{count}</div>;}// ❌ Not needed - will cause errorsimport React, { useState, useEffect } from 'react';
CRITICAL: JSX comments ({/* */}) in MDX files do NOT prevent MDX from parsing the content inside them. MDX will still try to evaluate JSX components and expressions within comments.
{/* ❌ 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 */}
If you need to temporarily disable a component section:
Remove the entire section from the MDX file
Add a comment explaining why it was removed
Document in docs/PLAN/errors/component-bugs.md if it’s a component bug
Do NOT use JSX comments to “comment out” component usage
CRITICAL RULE: Components in snippets/components/ are IMMUTABLENEVER modify files in snippets/components/ - These components are used across many pages. Any changes could break existing functionality.Allowed:
Creating new components
Modifying MDX files that use components
Fixing MDX imports and usage
Forbidden:
Modifying existing component files
Changing component function signatures
Adding/removing component exports
Changing component logic
Exception: Only if explicitly requested by user AND after confirming impact assessment.If a component appears to have a bug:
Comment out the component section in the MDX file where it’s used
Verify the page renders without that section
If page renders correctly → Component is the issue
Document the error in docs/PLAN/errors/component-bugs.md with:
Component name and file path
Error message from console
Page where error occurs
Verification that commenting out fixes the page
Recommendation for component fix (but do not implement)
DO NOT fix the component - Components are immutable without explicit user permission.
This repository uses Git pre-commit hooks to automatically enforce the style guide rules. These hooks are mandatory and will block commits that violate the style guide.
# Run all testsnpm test# Run specific test suitesnpm run test:style # Style guide validationnpm run test:mdx # MDX syntax validationnpm run test:spell # UK English spellingnpm run test:quality # Quality checks (alt text, links, frontmatter)npm run test:browser # Browser rendering tests
CSS Custom Properties usage (no ThemeData, no hardcoded colours)
No inline styles in MDX files
No em dashes in English v2 docs prose (use – or rewrite the sentence)
No Tailwind classes
Absolute import paths
File naming conventions
Component immutability warnings
MDX Validation (test:mdx):
Frontmatter validation
Unclosed JSX tags
Invalid import syntax
MDX scope inheritance issues
Spelling Tests (test:spell):
UK English spelling validation
Custom dictionary for technical terms (Livepeer, Arbitrum, etc.)
Excludes code blocks and frontmatter
Quality Checks (test:quality):
Image alt text presence
Frontmatter completeness
Internal link validation
SEO metadata validation
Browser Tests (test:browser):
Page rendering in headless browser
Console error detection
Theme testing (light/dark)
Content validation (H1, content length)
The test suite runs automatically in pre-commit hooks (staged/fast mode) and in CI/CD.
In pull request CI, static checks are changed-file scoped for blocking, while browser sweeps keep full-route coverage.For full details on the hooks, see the Git Hooks Documentation.
