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).

How it works?

---

• The plugin automatically detects and enhances all Expressive Code blocks on your pages,
• The fullscreen overlay adapts to your page’s background color for seamless integration,
• You can customize the fullscreen button icons by providing your own SVG paths,
• Animation duration is validated and constrained to ensure optimal performance (150-700ms),
• Focus management ensures accessibility compliance with proper keyboard navigation.

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,
• 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.