Configuration

Configuration Options

The Starlight custom navigation plugin accepts an object with the following options. You can customize these options to fit your needs. The default values are provided for each option.

`linkLabels`

Type: object
Default: { show: true, showOnHover: true, buttonRadiusNoLabel: 24 }
Description: Controls the appearance and behavior of navigation button labels.

`linkLabels.show`

Type: boolean
Default: true
Description: Whether to show labels on navigation buttons.

`linkLabels.showOnHover`

Type: boolean
Default: true
Description: Whether to show labels in tooltips when hovering over buttons.

`linkLabels.buttonRadiusNoLabel`

Type: number
Default: 24
Description: Button radius in pixels when labels are hidden.

`navShortcuts`

Type: object
Default: { previous: { key: 'ArrowLeft', modifier: 'ctrl' }, next: { key: 'ArrowRight', modifier: 'ctrl' } }
Description: Configure keyboard shortcuts for page navigation.

`navShortcuts.previous`

Type: object
Default: { key: 'ArrowLeft', modifier: 'ctrl' }
Description: Configuration for the “previous page” shortcut.

`navShortcuts.previous.key`

Type: string
Default: 'ArrowLeft'
Description: The key to use for the “previous page” shortcut.

`navShortcuts.previous.modifier`

Type: 'ctrl' | 'alt' | 'shift' | 'meta'
Default: 'ctrl'
Description: The modifier key to use with the shortcut.

`navShortcuts.next`

Type: object
Default: { key: 'ArrowRight', modifier: 'ctrl' }
Description: Configuration for the “next page” shortcut.

`navShortcuts.next.key`

Type: string
Default: 'ArrowRight'
Description: The key to use for the “next page” shortcut.

`navShortcuts.next.modifier`

Type: 'ctrl' | 'alt' | 'shift' | 'meta'
Default: 'ctrl'
Description: The modifier key to use with the shortcut.

`buttonIcon`

Type: object
Default: { svgPath: 'M4 16L12 8L20 16', strokeWidth: 2 }
Description: Customize the SVG path and stroke width for navigation button icons.

`buttonIcon.path`

Type: string
Default: 'M4 16L12 8L20 16'
Description: The SVG path data for the navigation button icons.

`buttonIcon.strokeWidth`

Type: number
Default: 2
Description: The width of the stroke for the navigation button icons.

`scrollBehavior`

Type: object
Default: { hideDelay: 3000, hideThreshold: 100 }
Description: Configure the scroll behavior of navigation buttons.

`scrollBehavior.hideDelay`

Type: number
Default: 3000
Description: Time in milliseconds before hiding the navigation buttons after scrolling stops.

`scrollBehavior.hideThreshold`

Type: number
Default: 100
Description: Scroll position in pixels at which the navigation buttons will be hidden after the delay.

Example Configuration

Here’s a complete example showing all available options:

import { starlight } from '@astrojs/starlight'
import { defineConfig } from 'astro/config'
import starlightCustomNavigation from 'starlight-custom-navigation'

export default defineConfig({
  integrations: [
    starlight({
      plugins: [
        starlightCustomNavigation({
          // Link label configuration
          linkLabels: {
            show: true,
            showOnHover: true,
            buttonRadiusNoLabel: 24
          },
          // Keyboard shortcuts
          navShortcuts: {
            previous: { key: 'ArrowLeft', modifier: 'ctrl' },
            next: { key: 'ArrowRight', modifier: 'ctrl' }
          },
          // Custom button icon
          buttonIcon: {
            svgPath: 'M4 16L12 8L20 16',
            strokeWidth: 3
          },
          // Scroll behavior
          scrollBehavior: {
            hideDelay: 3000,
            hideThreshold: 100
          }
        }),
      ],
      title: 'My Docs',
    }),
  ],
})