Guided Learning Paths

The Guided Learning Path components provide a structured, step-by-step learning experience for documentation readers. These components help users navigate complex topics in a progressive, manageable way, with built-in progress tracking.

Key Features

• Sequential Learning: Present information in logical, bite-sized steps
• Progress Tracking: Visualize progress and track completion
• State Persistence: Remember completed steps between sessions
• Navigational Controls: Simple next/previous navigation
• Step Completion: Mark steps as complete as users progress
• Estimated Time: Show time estimates for each step

Available Components

The guided learning system includes multiple components:

• GuidedLearningPath: Main container for a multi-step learning sequence
• LearningStep: Individual step within a learning path
• NextStepLink: Link to the next logical content in a learning journey
• GuidedLearningProvider: Context provider for state management

Basic Usage

import { GuidedLearningProvider, GuidedLearningPath, LearningStep } from '@site/src/components/MDX';

<GuidedLearningProvider>
  <GuidedLearningPath id="api-basics" title="Getting Started with the API">
    <LearningStep 
      title="Set Up Your Environment" 
      description="Configure your development environment for API access"
      estimatedMinutes={10}
    >
      [Step content goes here]
    </LearningStep>
    
    <LearningStep 
      title="Authentication" 
      description="Learn how to authenticate with the API"
      estimatedMinutes={15}
    >
      [Step content goes here]
    </LearningStep>
    
    <LearningStep 
      title="Make Your First Request" 
      description="Learn the basics of API requests"
      estimatedMinutes={20}
    >
      [Step content goes here]
    </LearningStep>
  </GuidedLearningPath>
</GuidedLearningProvider>

Provider Setup

For guided learning path components to work correctly, they must be wrapped in a GuidedLearningProvider. You can add this to individual pages:

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

<GuidedLearningProvider>
  {/* Your guided learning content */}
</GuidedLearningProvider>

Or, for site-wide support, add the provider to your theme layout in src/theme/Layout.js.

Creating Learning Steps

Each LearningStep component represents a single step in the learning journey:

<LearningStep 
  title="Step Title" 
  description="Optional description of this step"
  estimatedMinutes={15}
>
  <p>This can contain any content, including:</p>
  <ul>
    <li>Text explanations</li>
    <li>Code examples</li>
    <li>Images</li>
    <li>Interactive components</li>
  </ul>
</LearningStep>

Step Navigation

The GuidedLearningPath component automatically adds navigation controls to move between steps. These controls include:

• Previous button: Go back to the previous step
• Mark Complete button: Mark the current step as completed
• Next button: Advance to the next step

Users can mark steps as complete to track their progress, which is stored in localStorage and preserved between sessions.

Linking Between Learning Paths

Use the NextStepLink component to guide users from one learning path to another:

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

<NextStepLink
  title="Advanced API Techniques"
  description="Learn more advanced API concepts and usage patterns"
  to="/docs/api/advanced"
  buttonText="Start Advanced Guide"
/>

This creates a visually distinct "next step" card that directs users to related content.

Component Props

GuidedLearningProvider

Prop	Type	Default	Description
children	ReactNode	required	Content to be wrapped by the provider

GuidedLearningPath

Prop	Type	Default	Description
id	string	required	Unique identifier for this learning path
title	string	required	Title displayed at the top of the learning path
children	ReactNode	required	LearningStep components that form the path
className	string	''	Additional CSS class for styling
onComplete	function	null	Callback function when all steps are completed

LearningStep

Prop	Type	Default	Description
title	string	required	Title of this step
description	string	''	Brief description of what the step covers
estimatedMinutes	number	0	Estimated time to complete (in minutes)
children	ReactNode	required	Content of the step
className	string	''	Additional CSS class for styling
pathId	string	(auto)	Automatically provided by parent GuidedLearningPath
stepNumber	number	(auto)	Automatically provided by parent GuidedLearningPath

NextStepLink

Prop	Type	Default	Description
title	string	required	Title of the next learning path or content
description	string	''	Brief description of the next step
to	string	required	URL to navigate to
buttonText	string	'Continue'	Text for the action button
className	string	''	Additional CSS class for styling

Customization

Styling

To customize the appearance of guided learning components, you can:

1. Use the className prop: Add custom CSS classes to any component
2. Override CSS variables: Modify Docusaurus theme variables like --ifm-color-primary
3. Copy and modify the styles: Create a custom version of the components with modified styles

Advanced Customization

For more advanced customization, you can:

1. Create a wrapper component: Wrap the guided learning components with custom logic
2. Use the context hook: Import useGuidedLearning to access and manipulate state
3. Create specialized variants: Build on top of the base components for specific use cases

Accessibility Considerations

The guided learning components are designed with accessibility in mind:

• Proper heading structure maintained
• ARIA attributes for interactive elements
• Keyboard navigation support
• Sufficient color contrast
• Screen reader announcements for step changes

Best Practices

• Keep steps focused: Each step should cover a single concept or task
• Add time estimates: Help users plan their learning time
• Use consistent structure: Maintain similar patterns between steps
• Include visual elements: Break up text with diagrams or examples
• Provide feedback: Show progress clearly as users advance
• Test with real users: Verify your learning paths with actual beginners

Usage with Experience Toggle

Guided Learning Paths work well with the Experience Toggle component:

import { ExperienceProvider, ExperienceToggle, GuidedLearningProvider, GuidedLearningPath, LearningStep } from '@site/src/components/MDX';

<ExperienceProvider>
  <GuidedLearningProvider>
    <ExperienceToggle
      beginnerContent={
        <GuidedLearningPath id="beginner-guide" title="Beginner's Guide">
          {/* Simplified steps for beginners */}
        </GuidedLearningPath>
      }
      advancedContent={
        <GuidedLearningPath id="advanced-guide" title="Advanced Guide">
          {/* More detailed steps for advanced users */}
        </GuidedLearningPath>
      }
    />
  </GuidedLearningProvider>
</ExperienceProvider>

Examples

See guided-learning-examples.mdx for live examples and code samples.