Content Level Selection

Content Level Selection components allow users to customize their documentation experience based on two dimensions: technical expertise and detail level. This system enables a single documentation set to adapt to the needs of different users, from beginners to experts.

Key Features

• Two-Dimensional Filtering: Filter content by both technical level and detail level
• Technical Expertise Levels: Basic, intermediate, and advanced content tiers
• Detail Preference: Toggle between concise (action-oriented) and detailed (explanatory) content
• Global Configuration: Set preferences that apply across all documentation
• Local Overrides: Override global settings for specific sections when needed
• Persistent Settings: Remember user preferences between sessions
• Progressive Enhancement: Maintain core content accessibility while adding optional details

Available Components

The content level selection system includes multiple components:

• ContentLevel: Main component to conditionally render content based on levels
• ContentLevelSelector: Simple UI controls for selecting content levels
• ContentLevelPanel: Expandable panel with detailed configuration options
• ContentLevelProvider: Context provider for state management

Plus convenience components for common use cases:

• Basic, Intermediate, Advanced: Technical level shortcuts
• Concise, Detailed: Detail level shortcuts

Provider Setup

For content level components to work correctly, they must be wrapped in a ContentLevelProvider. You can add this to individual pages:

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

<ContentLevelProvider>
  {/* Your content with level-specific components */}
</ContentLevelProvider>

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

Basic Usage

To create content that only appears at certain technical levels:

import { ContentLevel, Basic, Intermediate, Advanced } from '@site/src/components/MDX';

{/* Using the main component */}
<ContentLevel technicalLevel="basic">
  This content is visible to all users.
</ContentLevel>

{/* Using the shorthand components */}
<Basic>
  This content is visible to all users (basic level).
</Basic>

<Intermediate>
  This content is visible to intermediate and advanced users only.
</Intermediate>

<Advanced>
  This content is visible only to advanced users.
</Advanced>

To create content based on detail preference:

import { Concise, Detailed } from '@site/src/components/MDX';

<Concise>
  This content appears only when concise mode is active.
</Concise>

<Detailed>
  This content appears only when detailed mode is active.
</Detailed>

Combining Dimensions

You can filter content on both dimensions simultaneously:

<ContentLevel technicalLevel="advanced" detailLevel="detailed">
  This content only appears for advanced users who prefer detailed explanations.
</ContentLevel>

Fallback Content

You can provide alternative content to show when the main content is hidden:

<ContentLevel technicalLevel="advanced" fallback={<p>Enable advanced mode to see more options.</p>}>
  <p>These are advanced configuration options...</p>
</ContentLevel>

User Controls

Add content level selectors to allow users to customize their view:

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

<ContentLevelSelector />

For more detailed controls, use the panel component:

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

<ContentLevelPanel defaultExpanded={true} />

Component Props

ContentLevel

Prop	Type	Default	Description
technicalLevel	string	undefined	Technical level requirement ('basic', 'intermediate', 'advanced')
detailLevel	string	undefined	Detail level requirement ('concise', 'detailed')
fallback	ReactNode	null	Content to show when the main content is hidden
showBadge	boolean	false	Whether to show a badge indicating the content level
className	string	''	Additional CSS class for styling

ContentLevelSelector

Prop	Type	Default	Description
showTechnicalLevel	boolean	true	Whether to show technical level controls
showDetailLevel	boolean	true	Whether to show detail level toggle
className	string	''	Additional CSS class for styling

ContentLevelPanel

Prop	Type	Default	Description
title	string	'Content Settings'	Panel title
defaultExpanded	boolean	false	Whether the panel is expanded by default
children	ReactNode	undefined	Additional content to render in the panel
className	string	''	Additional CSS class for styling

ContentLevelProvider

Prop	Type	Default	Description
children	ReactNode	required	Content to be wrapped by the provider
defaultTechnicalLevel	string	'intermediate'	Initial technical level
defaultDetailLevel	string	'detailed'	Initial detail level

Technical Level Logic

The technical level system follows a hierarchical structure:

• Basic: Fundamental content suitable for beginners
• Intermediate: More complex topics requiring some prior knowledge
• Advanced: Expert-level content for experienced users

Content is displayed based on the user's selected level in this way:

• If user selects "basic", they see only basic content
• If user selects "intermediate", they see basic and intermediate content
• If user selects "advanced", they see all content (basic, intermediate, and advanced)

Detail Level Logic

The detail level system offers two distinct modes:

• Concise: Action-oriented content focused on steps and directives
• Detailed: Explanatory content with context, reasons, and background

Content marked with a specific detail level will only display when that exact level is selected.

Integration Examples

Content level selection works well with other progressive disclosure components:

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

<ContentLevel technicalLevel="advanced">
  <h3>Advanced Configuration</h3>
  <ImplementationTime minutes={30} />
  
  <ExperienceToggle>
    <Beginner>
      Here's a simplified explanation...
    </Beginner>
    <Advanced>
      For a more efficient approach...
    </Advanced>
  </ExperienceToggle>
</ContentLevel>

Accessibility Considerations

• Content levels maintain logical document structure
• Controls include proper ARIA attributes
• Technical levels are color-coded but also labeled
• Core content remains accessible to all users

Best Practices

• Layer your content: Structure it so basic information appears first, followed by progressively more advanced details
• Be judicious: Don't overuse level filtering; core content should be accessible to all
• Use appropriate granularity: Filter at section level rather than individual sentences when possible
• Provide context clues: When content is conditionally displayed, ensure transitions remain smooth
• Test different configurations: Ensure your documentation makes sense in all possible level combinations
• Consider user model: Understand that technical expertise and detail preference are separate concerns

Examples

See the examples page for live demonstrations of all content level components and use cases.