Getting Started

A Starlight plugin to quickly and easily document keyboard shortcuts:

• Custom keyboard types, e.g. platform-specific, keyboard layout-specific, etc.
• Global or standalone keyboard type picker to switch between different types of keyboard shortcuts
• Preferred keyboard type persisted across pages
• Improved accessibility for screen readers

Check out the demo page for a preview of the plugin in action.

Prerequisites

You will need to have a Starlight website set up. If you don’t have one yet, you can follow the “Getting Started” guide in the Starlight docs to create one.

Installation

1. Starlight Kbd is a Starlight plugin. Install it using your favorite package manager:

   npm

   npm i starlight-kbd

   pnpm

   pnpm add starlight-kbd

   yarn

   yarn add starlight-kbd

   ni

   ni starlight-kbd

2. Configure the plugin in your Starlight configuration in the astro.config.mjs file by specifying the type of keyboard shortcuts you want to use.

   The following example shows how to configure two types of keyboard shortcuts: macOS and Windows.

   astro.config.mjs

   // @ts-check
   import starlight from '@astrojs/starlight'
   import { defineConfig } from 'astro/config'
   import starlightKbd from 'starlight-kbd'
   
   export default defineConfig({
     integrations: [
       starlight({
         plugins: [
           starlightKbd({
             types: [
               { id: 'mac', label: 'macOS', default: true },
               { id: 'windows', label: 'Windows' },
             ],
           }),
         ],
         title: 'My Docs',
       }),
     ],
   })

3. Use the provided <Kbd> component to document keyboard shortcuts.

   src/content/docs/index.mdx

   ---
   title: My docs
   ---
   
   Welcome to my project!
   
   import { Kbd } from 'starlight-kbd/components'
   
   Use <Kbd mac="Command+S" windows="Control+S" /> to get started.

4. Start the development server to preview the new shortcut and the keyboard type picker added next to the theme picker.

   Using the previous example, the preview should look like this:

   Preview

   Welcome to my project! Use Command + S CommandS Control + S ControlS Control + S ControlS to get started.

   See it in action

   You can also use the keyboard type picker at the top of this page to switch between the different types of keyboard shortcuts.

Check the configuration reference for more information on the available options, the <Kbd> component reference for more information on how to use it, and the shortcut syntax guide for details on how to write keyboard shortcuts.