Features

The Starlight Code Block Fullscreen plugin enhances your documentation experience by providing fullscreen functionality for code blocks.

Note

Once installed, the plugin will automatically add a fullscreen toggle button to your Expressive Code blocks. Users can:

• Click the fullscreen button to expand code blocks to fullscreen view,
• Use the Escape key to exit fullscreen mode (configurable),
• Or use the browser back button to exit fullscreen mode (configurable).

Fullscreen Mode

---

Transform any code block into a distraction-free fullscreen view with a single click. The fullscreen mode provides:

• Enhanced readability: Code blocks expand to fill the entire screen,
• Dark overlay: Minimizes distractions with a semi-transparent background,
• Optimized zoom: Automatically applies configurable zoom levels for better code visibility.

Example Code Block

// This code block will have a fullscreen button
function greetUser(name) {
  console.log(`Hello, ${name}!`);
  return `Welcome to the documentation`;
}

Usage Examples

---

Basic Navigation

1. Focus a code block: Use TAB to navigate to any code block on the page,
2. Enter fullscreen: Press Enter or click the fullscreen button,
3. Navigate in fullscreen: Use TAB to move through the code content,
4. Exit fullscreen: Press Escape, use the back button, or click the exit button.

Multi-Block Navigation

1. Cycle through blocks: Use TAB to move between different code blocks,
2. Quick activation: Press Enter on any focused code block to enter fullscreen,
3. Seamless switching: Exit one block and immediately navigate to another.

State Management

The plugin provides advanced state management to ensure a reliable user experience:

• Session persistence: Remembers user preferences during the session using localStorage
• Scroll position: Automatically saves and restores scroll position when exiting fullscreen
• Intelligent zoom management: Detects and stores initial browser zoom levels, applies configured fullscreen zoom, and restores original zoom when exiting
• History integration: Proper browser history management for back button support
• Focus state management: Maintains focus context and provides proper focus restoration for accessibility

⌨️ Keyboard Navigation

The plugin provides comprehensive keyboard support for enhanced accessibility and user experience:

Fullscreen Controls

• Escape key: Quickly exit fullscreen mode (configurable),
• Browser back button: Use your browser’s back button to exit fullscreen (configurable),
• Tab navigation: Full keyboard navigation support within fullscreen mode.

Code Block Cycling

Navigate between multiple code blocks on the same page using keyboard shortcuts:

• TAB Key: Cycle forward through all code blocks with fullscreen buttons on the current page,
• Enter Key: Activate the fullscreen mode for the currently focused code block,
• Shift + TAB: Cycle backward through code blocks (standard browser behavior).

This feature is particularly useful when you have multiple code examples and want to quickly navigate between them without using the mouse.

Customizable Icons

Personalize the fullscreen experience with custom SVG icons:

• Enter fullscreen icon: Customize the icon displayed when not in fullscreen mode,
• Exit fullscreen icon: Customize the icon displayed when in fullscreen mode,
• SVG path support: Use any valid SVG path for complete design flexibility,
• Consistent styling: Icons automatically inherit your Starlight site’s color scheme.

Button Placement

• Titled blocks only: Add buttons only to code blocks with titles (default)
• All blocks: Include untitled code blocks with the addToUntitledBlocks option

Smooth Animations

Enhance the user experience with polished animations and transitions:

• Configurable duration: Adjust animation speed with values between 150-700ms (default: 200ms),
• Automatic validation: Invalid duration values are automatically corrected to ensure optimal performance.