Component Override Test

Overview

This page demonstrates the MyST Awesome Theme's component override system. The navigation menu on the left and table of contents on the right are using custom components that override the default theme components.

Custom Components Active: This page is using custom NavigationMenu and TableOfContents components with enhanced styling and functionality.

How It Works

The component override system uses resolver components that can accept either the default component or a custom component via props. This allows for flexible theming while maintaining compatibility with existing layouts.

Component Resolvers

Resolver components like NavigationMenuResolver and TableOfContentsResolver act as wrappers that can dynamically choose between default and custom components:

// Using default component
<NavigationMenuResolver items={navItems} />

// Using custom component
import CustomNavigationMenu from './custom/CustomNavigationMenu.astro';
<NavigationMenuResolver component={CustomNavigationMenu} items={navItems} />

Custom Components

Custom components implement the same interface as the default components but can provide completely different styling and functionality. They receive the same props and are expected to render the same content structure.

Navigation Menu Override

The custom navigation menu used on this page features several enhancements over the default component:

Features

• Gradient Background: A beautiful gradient from brand to success colors
• Enhanced Icons: Solid icons throughout for better visual impact
• Animated Interactions: Smooth hover animations and transforms
• Custom Header: Branded header with sparkles icon
• Footer Indicator: Shows when custom theme is active
• Glassmorphism Effects: Backdrop blur and transparency effects

Styling

The custom navigation uses CSS custom properties from Web Awesome while adding its own design system on top. Key styling features include:

Colors Layout Animations

• Linear gradients for backgrounds
• Brand and success color combinations
• Semi-transparent overlays
• High contrast for accessibility

• Card-based design with borders
• Flexible spacing with CSS Grid
• Responsive breakpoints
• Proper focus management

• Staggered fade-in animations
• Hover transform effects
• Smooth color transitions
• Reduced motion support

Table of Contents Override

The custom table of contents on the right side of this page demonstrates advanced features not available in the default component:

Progress Tracking

The custom TOC includes a reading progress indicator that shows how much of the content has been scrolled through. This provides users with a visual indication of their progress through the document.

Card Design

Unlike the default flat design, the custom TOC uses a card-based layout with shadows, borders, and a gradient background. Features include:

• Card Container: Uses Web Awesome's card component
• Progress Bar: Visual reading progress indicator
• Level Indicators: Dots showing heading hierarchy
• Numbered Items: Optional numbering for TOC items
• Animated Entrance: Items slide in with staggered timing

Usage Examples

Here are some examples of how to use the component override system:

Direct Import Method

---
import DocsLayout from 'myst-awesome/layouts/DocsLayout.astro';
import CustomNavigationMenu from './custom/CustomNavigationMenu.astro';
---

<DocsLayout>
  <CustomNavigationMenu
    slot="navigation"
    items={navItems}
  />
</DocsLayout>

Resolver Method (Future Enhancement)

---
// Use custom navigation but default TOC
import CustomNavigationMenu from './custom/CustomNavigationMenu.astro';
---

<DocsLayout>
  <NavigationMenuResolver
    slot="navigation"
    component={CustomNavigationMenu}
    items={navItems}
  />
  <TableOfContentsResolver
    slot="aside"
    items={tocItems}
  />
</DocsLayout>

Best Practices

When creating custom components for the override system:

Interface Compatibility: Ensure your custom components accept the same props as the default components they're replacing. Web Awesome Dependencies: Remember to import any Web Awesome components your custom components use in their script blocks. Accessibility: Maintain the same accessibility features as the default components, including ARIA attributes and keyboard navigation.