Keyboard Shortcuts¶

Quick reference for built-in and custom keyboard shortcuts in MkDocs Material.

Built-in Shortcuts¶

MkDocs Material includes several keyboard shortcuts out of the box:

Shortcut	Action
`F` or `S`	Open search dialog
`P`	Navigate to previous page
`N`	Navigate to next page
`/`	Open search (alternative)
`Esc`	Close search dialog or other overlays

Search Shortcuts

Both F and S keys open the search dialog for convenience. Use / if you prefer vim-style navigation.

Custom Keyboard Shortcuts¶

Add Custom Keybindings¶

Create a custom JavaScript file to add additional shortcuts:

docs/javascripts/shortcuts.js

document.addEventListener('keydown', (e) => {
  // Ctrl+K to open search (VS Code style)
  if (e.ctrlKey && e.key === 'k') {
    e.preventDefault();
    document.querySelector('[data-md-component="search-query"]').focus();
  }

  // Ctrl+B to toggle sidebar
  if (e.ctrlKey && e.key === 'b') {
    e.preventDefault();
    document.querySelector('[data-md-toggle="drawer"]').click();
  }

  // G then H for home (vim style)
  if (e.key === 'g' && lastKey === 'g') {
    window.location.href = '/';
  }
  lastKey = e.key;
});

let lastKey = '';

Register Custom Scripts¶

Reference the custom JavaScript in your MkDocs configuration:

mkdocs.yml

extra_javascript:
  - javascripts/shortcuts.js

Shortcut Conflicts

Avoid overriding browser shortcuts (like Ctrl+T) or MkDocs Material built-ins unless intentional.

Platform-Specific Shortcuts¶

macOS¶

Shortcut	Action
`Cmd`+`K`	Custom search (if configured)
`Cmd`+`B`	Custom sidebar toggle (if configured)

Windows/Linux¶

Shortcut	Action
`Ctrl`+`K`	Custom search (if configured)
`Ctrl`+`B`	Custom sidebar toggle (if configured)

Advanced Shortcut Patterns¶

Implement vim-style two-key shortcuts:

docs/javascripts/shortcuts.js

let keySequence = [];
const TIMEOUT = 1000; // Reset after 1 second

document.addEventListener('keydown', (e) => {
  // Ignore if typing in input fields
  if (e.target.matches('input, textarea')) return;

  keySequence.push(e.key);

  // g + h = home
  if (keySequence.join('') === 'gh') {
    window.location.href = '/';
    keySequence = [];
  }

  // g + g = top of page
  if (keySequence.join('') === 'gg') {
    window.scrollTo({ top: 0, behavior: 'smooth' });
    keySequence = [];
  }

  // Reset sequence after timeout
  setTimeout(() => { keySequence = []; }, TIMEOUT);
});

Command Palette¶

Create a command palette with Ctrl+Shift+P:

docs/javascripts/command-palette.js

document.addEventListener('keydown', (e) => {
  if (e.ctrlKey && e.shiftKey && e.key === 'P') {
    e.preventDefault();
    // Show custom command palette
    showCommandPalette();
  }
});

function showCommandPalette() {
  // Implementation for command palette UI
  console.log('Command palette opened');
}

Command Palette

A full command palette implementation requires additional UI components and state management.

Accessibility Considerations¶

Focus Management¶

Ensure keyboard shortcuts work with screen readers:

docs/javascripts/accessible-shortcuts.js

document.addEventListener('keydown', (e) => {
  // Skip shortcuts if using screen reader
  if (e.target.getAttribute('role') === 'dialog') return;

  // Announce shortcut action
  if (e.key === 'f' || e.key === 's') {
    announceToScreenReader('Opening search dialog');
  }
});

function announceToScreenReader(message) {
  const announcement = document.createElement('div');
  announcement.setAttribute('role', 'status');
  announcement.setAttribute('aria-live', 'polite');
  announcement.textContent = message;
  document.body.appendChild(announcement);
  setTimeout(() => announcement.remove(), 1000);
}

Testing Shortcuts¶

Test keyboard shortcuts across browsers:

Chrome/Edge: Built-in DevTools for debugging
Firefox: Web Console for JavaScript errors
Safari: Enable Developer menu for testing

Cross-Browser Testing

Always test custom shortcuts in multiple browsers, as key event handling can vary.