Customization & Components

starlight-fumadocs provides a premium, Mintlify-inspired aesthetic out of the box, with deeply integrated styling for all core Starlight components. This guide explains how the design system works and how you can customize it.

Component Upgrades

This theme automatically upgrades standard Starlight UI components to a premium aesthetic without requiring any extra configuration.

Tables

Markdown tables are redesigned for high data readability and responsiveness:

Responsive Layout: Automatically stretches to 100% width on desktop. On mobile, it gracefully transforms into a swipable horizontal carousel.
Clean Aesthetic: Vertical dividers are removed in favor of clean horizontal rules.
Interactive: Features subtle alternating row backgrounds (zebra striping) and a distinct row hover illumination effect.

Component	Default Starlight	Theme Upgraded
Tables	Block layout, heavy borders	Full-width, horizontal rules, zebra
Code Blocks	Colorful macOS dots	Monochrome dots, inset shadows
Cards	Solid backgrounds	Glassmorphic gradient, float effect
Steps	Basic timeline	2px connector, 2rem cutout circles

Code Blocks

Terminal Frames: Automatically feature sleek, monochrome macOS-style window controls (dots) instead of distracting colorful circles.
Layout: Deep inset shadows in dark mode and floating shadows in light mode, with perfectly integrated copy buttons.

# Notice the sleek, monochrome window controls on the left!
echo "This theme is incredibly minimal."

Cards & Link Cards

When using Starlight’s <Card> or <LinkCard> components:

Glassmorphism: Cards use a subtle translucent gradient background.
Interactive: Hovering over a card slightly elevates it (translateY(-2px)) and illuminates the border with your theme’s primary accent color.

Hover Me

This card uses a glassy gradient background. Hover over it to see the elevation effect.

Interactive Link Card This entire card is clickable and illuminates on hover.

Steps

The <Steps> component is upgraded into a prominent vertical timeline:

Features a sharp 2px vertical timeline connector.
Large, perfectly centered step indicator circles use a CSS box-shadow cutout trick to prevent the timeline from bleeding through.

First Step Start by installing the theme using your preferred package manager.
Second Step Configure your astro.config.mjs to include the plugin.
Final Step Enjoy your deeply integrated, premium documentation site!

Badges

Starlight <Badge> components are transformed into modern pills:

They use vibrant translucent backgrounds with matching solid borders instead of heavy, solid-color blocks.
The default variant uses a clean, muted slate-grey tint, perfect for unobtrusive tags.

Examples:

New Feature
Deprecated
Note
Draft

Design Tokens

The theme uses a centralized token system tailored for a sleek, modern look. The most important tokens are the --mint-* variables, which control surfaces, borders, and rounded corners globally.

:root {
  /* Control the global roundness (e.g., 8px for modern, 4px for sharp) */
  --mint-radius: 8px;
  --mint-radius-lg: 12px;

  /* Surfaces and borders */
  --mint-surface: rgba(255, 255, 255, 0.05);
  --mint-surface-hover: rgba(255, 255, 255, 0.08);
  --mint-border: rgba(255, 255, 255, 0.07);
  --mint-border-strong: rgba(255, 255, 255, 0.12);
}

Cascade Layers

To ensure your overrides work perfectly, starlight-fumadocs uses the @layer fuma-theme cascade layer.

Any custom CSS you write outside of a layer will automatically override the theme. If you use layers in your own project, simply ensure your overrides layer comes after fuma-theme:

/* Define the order of precedence */
@layer starlight, fuma-theme, my-overrides;

@layer my-overrides {
  /* Your custom styles here */
}

Elastic Worm Glide (TOC)

The Table of Contents features a custom, high-performance “snake” physics engine.

Visual Styling

The colors automatically adapt to your theme’s light and dark mode tokens, but you can override them manually:

:root {
  /* The vertical rail background and curve line */
  --mint-border: rgba(255, 255, 255, 0.07);

  /* The active gliding snake indicator */
  --glide-indicator-color: var(--sl-color-accent);
}

The theme features a premium Root Navigation switcher (breadcrumb-style) at the top of the sidebar. You can customize the icons and colors for each documentation group.

starlight-fumadocs is fully compatible with starlight-plugin-icons. If you want to use icons in your sidebar items (folders and files), simply install the plugin:

npm install starlight-plugin-icons
Configure it in astro.config.mjs:

import { starlightIconsPlugin, starlightIconsIntegration } from "starlight-plugin-icons";

export default defineConfig({
  integrations: [
    starlightIconsIntegration(),
    starlight({
      plugins: [starlightIconsPlugin()],
    }),
  ],
});

You can specify icons and colors for your top-level groups in the starlightFumadocs plugin options.

starlightFumadocs({
  rootNav: {
    groups: {
      "Getting Started": {
        icon: "open-book", // Starlight built-in icon
        color: "#facc15", // Custom theme color for this group
        description: "New to the project?",
      },
      Advanced: {
        icon: "i-ph:palette-duotone", // Plugin-based icon (optional)
        color: "#3b82f6",
      },
    },
  },
});

Automatic Fallbacks

The theme is designed to look premium out-of-the-box without any manual configuration:

Text Icons: If no icon is provided, the switcher automatically renders the first letter of the group’s label.
Theme Colors: If no color is provided, a curated color from the palette is automatically assigned.

Accessibility

The theme includes a unified focus ring system for accessibility. You can customize the focus ring’s color globally:

:focus-visible {
  outline: 2px solid var(--sl-color-accent);
  outline-offset: 2px;
}

Key Features & Components

starlight-fumadocs includes several advanced features that bring a highly interactive experience to your Starlight site.

The theme automatically transforms your sidebar based on the current page. It identifies the top-level folder (group) and filters the sidebar to show only the items within that group. This creates a “sub-site” feel where each major section of your docs has its own dedicated navigation context.

Interactive Breadcrumbs

A custom breadcrumb system is automatically injected at the top of your pages.

It maps your sidebar hierarchy into a clickable trail.
It supports deep-linking back to top-level folder groups.

Adaptive Header

The sticky, glassmorphic header has intelligent visibility logic:

Landing Pages: On Hero or Splash pages (where no sidebar is present), the header remains visible on desktop for branding and search access.
Documentation Pages: On pages with a sidebar, the header hides on desktop and merges into the sidebar rail for a cleaner, focused reading experience.

Fullscreen Code Blocks

All code blocks (powered by Expressive Code) automatically receive a fullscreen toggle button.

Zoom Controls: Use the on-screen buttons or your mouse wheel to adjust the code font size (60% to 500%).
State Persistence: Your preferred zoom level is saved in local storage.

Browser Preview Component

Use the <BrowserPreview /> component to showcase live demos or website previews with desktop, tablet, and mobile toggles.

import { BrowserPreview } from 'starlight-fumadocs/components';

<BrowserPreview url="https://example.com" title="My App" height="500px" />

D2 Diagrams

The theme includes native support for D2 diagrams via astro-d2.

Theme Awareness: Diagrams automatically adjust their colors based on light/dark mode.
Responsive Layout: Centered and padded containers that match the aesthetic.

Custom Callouts

Use the <Callout /> component for highlighted notes.

Types: info, warning, error, success, idea.
Design: Minimalist indicators and theme-aware functional colors.

import { Callout } from 'starlight-fumadocs/components';

<Callout type="idea">This is a cool idea!</Callout>

Advanced Customization

Adding Content Below the TOC (Connect Section)

You can easily inject a custom section (like a “Connect” block with GitHub and LinkedIn links) at the bottom of your right sidebar. Because starlight-fumadocs safely handles component overrides, you just override Starlight’s TableOfContents component.

Create a file at src/components/ConnectTOC.astro:

---
import Default from 'starlight-fumadocs/overrides/TableOfContents.astro';
import { Icon } from '@astrojs/starlight/components';
---

<!-- 1. Render the premium Glide TOC first -->
<Default {...Astro.props} />

<!-- 2. Add your custom content below it -->
<div class="connect-section">
  <h3>Connect</h3>
  <ul>
    <li>
      <a href="https://github.com/yourusername" target="_blank">
        <Icon name="github" /> GitHub
      </a>
    </li>
  </ul>
</div>

<style>
  .connect-section {
    margin-top: 2rem;
    padding-top: 1.5rem;
    border-top: 1px solid var(--sl-color-hairline);
  }
  h3 {
    font-size: 0.875rem;
    font-weight: 600;
    color: var(--sl-color-white);
    margin-bottom: 1rem;
  }
  ul {
    list-style: none;
    padding: 0;
    margin: 0;
    display: flex;
    gap: 1rem;
  }
  a {
    display: flex;
    align-items: center;
    gap: 0.375rem;
    color: var(--sl-color-gray-3);
    text-decoration: none;
    font-size: 0.8125rem;
    font-weight: 500;
    transition: color 0.15s ease;
  }
  a:hover {
    color: var(--sl-color-white);
  }
</style>

export default defineConfig({
  integrations: [
    starlight({
      plugins: [starlightFumadocs()],
      components: {
        TableOfContents: './src/components/ConnectTOC.astro',
      },
    }),
  ],
});

Functional Colors

You can override the functional color palette in your CSS:

:root {
  --fuma-color-info: oklch(62.3% 0.214 259.815);
  --fuma-color-success: oklch(72.3% 0.219 149.579);
}

Geist Typography

The theme is natively optimized for Geist Sans and Geist Mono. If you wish to use them, ensure they are installed in your project:

:root {
  --sl-font: "Geist Sans", var(--sl-font-system);
  --sl-font-mono: "Geist Mono", var(--sl-font-system-mono);
}