Enhanced Experience Toggle

The Enhanced Experience Toggle component allows you to present different content based on the user's experience level, going beyond Docusaurus' native tab component by providing:

1. Global preference storage (user's selection persists across pages)
2. Enhanced styling tailored to experience levels
3. Context-aware content rendering
4. Accessibility improvements
5. User profile integration

Available Components

This system includes multiple components to meet different needs:

• ExperienceToggle: The main component for displaying different content based on experience level
• Beginner/Advanced: Shorthand components for conditional rendering
• ExperienceSettingsPanel: A comprehensive settings panel for users to control their experience
• GlobalExperienceToggle: A compact toggle for navbar integration
• ProfileAwareExperience: Automatic experience level detection from user profiles

Basic Usage

import { ExperienceToggle } from '@site/src/components/MDX/ExperienceToggle';

<ExperienceToggle
  beginnerContent={<p>This is simplified content for beginners.</p>}
  advancedContent={<p>This includes technical details for advanced users.</p>}
/>

MDX Shorthand

For convenience, you can also use the shorthand syntax in MDX files:

<Beginner>
  This content is visible only when "Beginner" mode is active.
  
  - Simplified explanations
  - Step-by-step guidance
  - Visual examples
</Beginner>

<Advanced>
  This content is visible only when "Advanced" mode is active.
  
  - Technical implementation details
  - Performance considerations
  - Edge cases and advanced patterns
</Advanced>

Experience Settings Panel

The Settings Panel provides a more comprehensive interface for users to adjust their experience level:

import { ExperienceSettingsPanel } from '@site/src/components/MDX/ExperienceToggle';

<ExperienceSettingsPanel />

This component:

• Shows detailed descriptions of each experience level
• Creates a consistent place for users to change settings
• Works automatically with the global state system
• Can be placed on landing pages or getting started guides

Props

ExperienceToggle Component

Prop	Type	Default	Description
beginnerContent	ReactNode	required	Content to display in beginner mode
advancedContent	ReactNode	required	Content to display in advanced mode
defaultMode	string	'beginner'	Initial mode if user hasn't set a preference
showToggle	boolean	true	Whether to show the toggle controls
className	string	''	Additional CSS class for the container

Beginner/Advanced Components

Prop	Type	Default	Description
children	ReactNode	required	Content to display when the respective mode is active
fallback	ReactNode	null	Content to display when the respective mode is NOT active (if null, nothing is shown)
hideToggle	boolean	false	Whether to hide the toggle UI above this component
className	string	''	Additional CSS class for the container

ExperienceSettingsPanel Component

Prop	Type	Default	Description
className	string	''	Additional CSS class for the container

Examples

Basic Toggle

<ExperienceToggle
  beginnerContent={
    <div>
      <h3>Getting Started</h3>
      <p>Welcome! This guide will help you understand the basics.</p>
      <ol>
        <li>Install the package using npm or yarn</li>
        <li>Import the component into your project</li>
        <li>Add it to your JSX/TSX code</li>
      </ol>
    </div>
  }
  advancedContent={
    <div>
      <h3>Advanced Implementation</h3>
      <p>Configuration options and performance optimizations:</p>
      <pre>
        <code>
          {`
const config = {
  optimization: true,
  cacheStrategy: 'memory',
  timeout: 500
};

// Initialize with custom config
initialize(config);
          `}
        </code>
      </pre>
    </div>
  }
/>

With Fallback Content

The fallback prop allows you to show alternative content when a mode isn't selected:

<Beginner fallback={<p>Switch to beginner mode to see simplified instructions</p>}>
  <p>Here are the basic steps to get started...</p>
</Beginner>

<Advanced fallback={<p>Switch to advanced mode to see technical details</p>}>
  <p>Technical implementation details and optimizations...</p>
</Advanced>

Context-Aware Sections

You can place multiple toggle components on a single page, and they'll all stay in sync:

<h2>Installation</h2>
<Beginner>
  <p>Install using our simple installer package</p>
</Beginner>
<Advanced>
  <p>Install using package manager with these configuration options</p>
</Advanced>

<h2>Configuration</h2>
<Beginner>
  <p>Basic configuration with default settings</p>
</Beginner>
<Advanced>
  <p>Advanced configuration options for performance tuning</p>
</Advanced>

Settings Panel

Place the settings panel at the top of key documentation pages:

<h1>API Documentation</h1>

<p>This documentation adapts to your experience level.</p>

<ExperienceSettingsPanel />

<h2>Getting Started</h2>
// Content that adapts to user's chosen experience level follows...

Global Preference Management

The Experience Toggle components use the browser's localStorage to remember the user's preference across pages and visits.

Your documentation site can also include a global settings panel that allows users to set their experience level site-wide.

Navbar Integration

You can add a global experience toggle to your site's navigation bar by adding a custom navbar item to your docusaurus.config.js:

module.exports = {
  // ... other config
  themeConfig: {
    navbar: {
      items: [
        // ... other navbar items
        {
          type: 'custom-experienceToggle',
          position: 'right',
        },
      ],
    },
  },
};

This will add a persistent toggle that affects all experience-aware content throughout the site.

Integration with Docusaurus

The Experience Toggle components are designed to work seamlessly with Docusaurus MDX pages. They incorporate Docusaurus theme styles for consistency and can be used alongside other Docusaurus components like admonitions or details/summary.

Provider Setup

The components require an ExperienceProvider to work. This is automatically set up via a custom Root.js component that wraps the entire Docusaurus application.

// src/theme/Root.js
import React from 'react';
import { ExperienceProvider } from '@site/src/components/MDX/ExperienceToggle';

export default function Root({ children }) {
  return (
    <ExperienceProvider>
      {children}
    </ExperienceProvider>
  );
}

Dark Mode Support

All experience toggle components automatically adjust to Docusaurus' dark mode settings:

• Color schemes adapt to light/dark themes
• Contrast ratios are maintained in both modes
• Visual indicators remain clear in all lighting conditions

Accessibility Considerations

The Experience Toggle components are built with accessibility in mind:

1. Proper ARIA attributes for screen readers
2. Keyboard navigation support
3. Sufficient color contrast for toggle elements
4. Focus indicators for interactive elements

Best Practices

• Use sparingly: Don't overuse toggles, as they can fragment content
• Ensure completeness: Each experience level should provide a complete understanding
• Be consistent: Use the same level of detail for the same experience level throughout your documentation
• Provide context: Make it clear what information is being excluded in simpler views
• Consider defaults: Choose appropriate default experience levels for different documentation sections
• Strategic placement: Add the settings panel to key entry points in your documentation

User Profile Integration

The experience toggle system can automatically set the appropriate experience level based on the user's profile data. When a user completes their profile with years of experience information, the documentation will adapt accordingly:

• Users with 0-5 years of experience automatically see beginner-focused content
• Users with 5+ years of experience automatically see advanced-focused content
• Users can always manually override this selection using any toggle component

This integration creates a seamless experience right from the start, without requiring users to configure their documentation preferences separately.

Implementation Details

The system uses the ProfileAwareExperience component to check the user's stored profile information:

// Automatically included in src/theme/Root.js
import { ExperienceProvider } from '@site/src/components/MDX/ExperienceToggle';
import ProfileAwareExperience from '@site/src/components/MDX/ExperienceToggle/ProfileAwareExperience';

export default function Root({ children }) {
  return (
    <ExperienceProvider>
      <ProfileAwareExperience />
      {children}
    </ExperienceProvider>
  );
}

When a user explicitly sets their preference using any toggle, that manual selection takes precedence over profile-based settings.