docusaurus-themes

codatio's avatarfrom codatio

Use when swizzling Docusaurus theme components and editing theme elements

⭐18stars🔀41forks📁View on GitHub🕐Updated Jan 9, 2026

When & Why to Use This Skill

This Claude skill streamlines the process of customizing Docusaurus websites by providing expert guidance on 'swizzling' theme components. It enables developers to efficiently modify UI elements like Navbars, Footers, and DocItems using safe 'wrap' or 'eject' methods, ensuring a balance between deep customization and long-term maintainability.

Use Cases

  • Customizing the global Footer or Navbar to align with specific brand identity and layout requirements.
  • Extending the DocItem component to inject custom React elements or metadata into documentation pages.
  • Safely overriding theme components using the --wrap pattern to maintain compatibility with future Docusaurus version upgrades.
  • Identifying and browsing available theme components to determine which elements are safe to swizzle for specific UI changes.
namedocusaurus-themes
# IMPORTANTKeep description on ONE line for Claude Code compatibility
descriptionUse when swizzling Docusaurus theme components and editing theme elements

Docusaurus Swizzle

Quick Start

Swizzle components to customize Docusaurus theme behavior:

npm run swizzle @docusaurus/theme-classic ComponentName -- --wrap

Core Principles

  • Wrap (safe): Extends original component, easier to upgrade
  • Eject (unsafe): Full copy for maximum control, harder to maintain
  • Interactive mode: Use npm run swizzle to browse available components
  • Swizzled components go in src/theme/ComponentName/

Common Patterns

List available components:

npm run swizzle @docusaurus/theme-classic -- --list

Commonly swizzled: Footer, Navbar, DocItem, DocSidebar, TOC

Reference Files

For detailed documentation, see:

Notes

  • Prefer --wrap for minor changes to maintain upgrade compatibility
  • Test thoroughly after swizzling components
  • Check official docs for component-specific swizzle safety ratings