docusaurus-themes

Original source / Raw SKILL.md

---
name: docusaurus-themes
# IMPORTANT: Keep description on ONE line for Claude Code compatibility
# prettier-ignore
description: Use when swizzling Docusaurus theme components and editing theme elements
---

# Docusaurus Swizzle

## Quick Start

Swizzle components to customize Docusaurus theme behavior:

```bash
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:**

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

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

## Reference Files

For detailed documentation, see:

- [references/commands.md](references/commands.md) - All swizzle commands and options
- [references/components.md](references/components.md) - Component-specific guides

## Notes

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

<!--
PROGRESSIVE DISCLOSURE GUIDELINES:
- Keep this file ~50 lines total (max ~150 lines)
- Use 1-2 code blocks only (recommend 1)
- Keep description <200 chars for Level 1 efficiency
- Move detailed docs to references/ for Level 3 loading
- This is Level 2 - quick reference ONLY, not a manual

LLM WORKFLOW (when editing this file):
1. Write/edit SKILL.md
2. Format (if formatter available)
3. Run: claude-skills-cli validate <path>
4. If multi-line description warning: run claude-skills-cli doctor <path>
5. Validate again to confirm
-->


---

## Referenced Files

> The following files are referenced in this skill and included for context.

### references/commands.md

```markdown
# Docusaurus Swizzle Commands Reference

## Basic Commands

### Interactive Swizzling

Browse and select components interactively:

```bash
npm run swizzle
```

This will prompt you to:

1. Select a theme (e.g., @docusaurus/theme-classic)
2. Choose a component to swizzle
3. Select wrap or eject mode

### List Available Components

See all swizzlable components from a theme:

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

### Safe Swizzle (Wrap)

Wrap a component to add customizations while keeping the original:

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

**When to use wrap:**

- You want to add functionality without replacing the original
- You need to preserve upgrade compatibility
- You're making minor customizations

### Unsafe Swizzle (Eject)

Eject to fully replace and customize a component:

```bash
npm run swizzle @docusaurus/theme-classic ComponentName -- --eject
```

**When to use eject:**

- You need full control over component internals
- You're making significant structural changes
- You understand you'll need to manually merge updates

## Command Options

- `--wrap` - Safe swizzle mode (wraps original component)
- `--eject` - Unsafe swizzle mode (copies full source)
- `--list` - List all available components to swizzle
- `--typescript` - Generate TypeScript files (default)
- `--javascript` - Generate JavaScript files

## File Locations

After swizzling, components are created in:

- `src/theme/ComponentName/` - Directory-based components (with index.tsx)
- `src/theme/ComponentName.tsx` - Single-file components

## Examples

### Example: Swizzle Footer

```bash
npm run swizzle @docusaurus/theme-classic Footer -- --eject
```

After running this, edit the footer in `src/theme/Footer/index.tsx`.

### Example: Wrap Navbar

```bash
npm run swizzle @docusaurus/theme-classic Navbar -- --wrap
```

This creates a wrapper in `src/theme/Navbar/index.tsx` that imports and extends the original.

### Example: List and Choose

```bash
# First, see what's available
npm run swizzle @docusaurus/theme-classic -- --list

# Then swizzle the component you need
npm run swizzle @docusaurus/theme-classic DocItem -- --wrap
```

## Troubleshooting

**Component not found:**

- Ensure you're using the correct theme package name
- Run `--list` to see available components

**TypeScript errors after swizzling:**

- Check that you have the correct type definitions installed
- Ensure your tsconfig.json includes the src/theme directory

**Changes not appearing:**

- Clear the `.docusaurus` cache: `npm run clear`
- Restart the development server

```

### references/components.md

```markdown
# Common Docusaurus Components to Swizzle

## Layout Components

### Footer

**Path:** `src/theme/Footer/`
**Use case:** Customize footer content, links, copyright, social media icons

**Example customization:**

```tsx
import React from 'react';
import Footer from '@theme-original/Footer';

export default function FooterWrapper(props) {
  return (
    <>
      <Footer {...props} />
      <div className="custom-footer-section">{/* Add custom footer content */}</div>
    </>
  );
}
```

### Navbar

**Path:** `src/theme/Navbar/`
**Use case:** Modify navigation bar appearance, add custom elements, change behavior

**Common modifications:**

- Add custom logo behavior
- Insert additional navigation items
- Modify mobile menu behavior

### Layout

**Path:** `src/theme/Layout/`
**Use case:** Wrap all pages with custom providers, analytics, or global components

## Documentation Components

### DocItem

**Path:** `src/theme/DocItem/`
**Use case:** Customize documentation page layout, add custom elements to doc pages

**Common modifications:**

- Add custom headers or footers to docs
- Insert advertisements or announcements
- Add custom metadata display

### DocSidebar

**Path:** `src/theme/DocSidebar/`
**Use case:** Adjust sidebar behavior, styling, and interaction

**Common modifications:**

- Custom sidebar item rendering
- Add search functionality to sidebar
- Change collapsible behavior

### TOC (Table of Contents)

**Path:** `src/theme/TOC/`
**Use case:** Modify table of contents display, add custom elements

**Common modifications:**

- Add "Edit this page" links
- Customize heading filtering
- Add custom TOC actions

## Blog Components

### BlogPostPage

**Path:** `src/theme/BlogPostPage/`
**Use case:** Customize blog post layout and structure

### BlogListPage

**Path:** `src/theme/BlogListPage/`
**Use case:** Modify blog list view, pagination, filtering

## Code Components

### CodeBlock

**Path:** `src/theme/CodeBlock/`
**Use case:** Customize code block rendering, add features like copy button customization

### MDXComponents

**Path:** `src/theme/MDXComponents/`
**Use case:** Override or extend default MDX components used in markdown

## Best Practices by Component

### Safe to Wrap (Low Risk)

- Footer - Usually safe to wrap for adding content
- Navbar - Wrapping is often sufficient for minor changes
- Layout - Good candidate for wrapping to add providers

### Consider Ejecting (When Needed)

- CodeBlock - Often need full control for custom highlighting
- DocItem - May need eject for significant layout changes
- BlogPostPage - Eject for custom post templates

## Swizzle Safety Levels

Docusaurus marks components with safety levels:

- **Safe**: Safe to swizzle, low breaking change risk
- **Unsafe**: May break with Docusaurus updates
- **Forbidden**: Cannot be swizzled (internal components)

Check safety level:

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

Components are marked with their safety level in the list output.

## Component Hierarchies

Understanding component relationships helps you choose what to swizzle:

```
Layout (top-level wrapper)
├── Navbar
├── DocPage
│   ├── DocSidebar
│   └── DocItem
│       └── TOC
└── Footer
```

**Tip:** Swizzle at the lowest level that meets your needs to minimize maintenance burden.

## Examples by Use Case

### Use Case: Add Custom Analytics

**Component:** Layout
**Mode:** Wrap
**Why:** Wrapping Layout lets you add providers without replacing core functionality

### Use Case: Custom Footer Design

**Component:** Footer
**Mode:** Eject
**Why:** Significant design changes usually require full control

### Use Case: Add Version Badge to Docs

**Component:** DocItem
**Mode:** Wrap
**Why:** Can inject custom elements without modifying core doc rendering

### Use Case: Custom Syntax Highlighting

**Component:** CodeBlock
**Mode:** Eject
**Why:** Deep integration with highlighting engine requires full access

```