Fumadocs Layout Fix | Custom Cap BD

Problem

The Fumadocs documentation layout was rendering sidebars (left navigation and right table of contents) directly at the top of the viewport, causing them to overlap with the custom 64px header component.

Visual Issue

Right sidebar (TOC) search input touching header edge
Left sidebar navigation starting at top without spacing
Content area not accounting for header height

Root Cause

Fumadocs uses fixed positioning for its sidebar and TOC elements. The custom <Header /> component (64px tall) was rendered before <DocsLayout>, but Fumadocs' default CSS positioned sidebars at top: 0, causing them to slide under the header.

Solution

CSS Override Approach

Added comprehensive CSS overrides to globals.css targeting all possible Fumadocs layout elements:

/* globals.css */
:root {
  --fd-nav-height: 64px;
}

/* Left sidebar (navigation) */
[data-sidebar],
aside[data-sidebar],
.fd-sidebar,
aside.fd-sidebar,
[class*="sidebar"] aside,
div[class*="Layout_aside"] {
  top: var(--fd-nav-height) !important;
  height: calc(100vh - var(--fd-nav-height)) !important;
}

/* Right sidebar (table of contents) */
[data-toc],
aside[data-toc],
.fd-toc,
aside.fd-toc,
[class*="toc"] aside,
div[class*="Layout_toc"] {
  top: var(--fd-nav-height) !important;
  height: calc(100vh - var(--fd-nav-height)) !important;
}

/* Target Fumadocs Layout container */
[data-fumadocs-layout],
.fd-layout,
main[class*="fd-"] {
  padding-top: var(--fd-nav-height) !important;
}

Implementation Details

File Changes

src/app/globals.css (lines 9-51): Added Fumadocs layout fixes
src/app/docs/layout.tsx: No changes needed (initial pt-16 attempt was insufficient)

Key Techniques

CSS Variable: --fd-nav-height: 64px for maintainability
Multiple Selectors: Covers all possible Fumadocs class/data attribute combinations
Important Flag: Overrides Fumadocs' default positioning
Dynamic Height: calc(100vh - 64px) ensures full viewport coverage below header

Testing Checklist

Left sidebar starts below header (no overlap)
Right sidebar TOC search input has proper spacing
Content area scrolls correctly
Mobile responsive behavior maintained
Dark mode styling preserved
Sidebar collapse/expand animation works

src/app/docs/layout.tsx - Fumadocs layout configuration
src/shared/components/layout/header.tsx - Custom header component (h-16 / 64px)
src/app/globals.css - Global CSS overrides
package.json - Fumadocs UI version: 16.0.1

Future Improvements

If Fumadocs updates their CSS architecture, this fix may need adjustment. Consider:

Using Fumadocs' native header configuration if they add support
Monitoring Fumadocs changelog for layout API changes
Creating a shared CSS variable file for header heights across the app

Date Implemented

2025-10-28

Author

absrasel (via Claude Code)