Installation

Enhance the reading experience on your Starlight documentation site with smooth, intuitive navigation. This plugin allows users to easily move between pages using visible navigation buttons, customizable keyboard shortcuts, swipe gestures on mobile devices, and smart scroll behavior that keeps the navigation accessible when needed.

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-custom-navigation is a Starlight plugin. Install it by running the following command in your terminal:

   npm

   npm install starlight-custom-navigation

   pnpm

   pnpm add starlight-custom-navigation

   Yarn

   yarn add starlight-custom-navigation

2. Configure the plugin in your Starlight configuration in the astro.config.mjs file.

   astro.config.mjs

   import starlight from '@astrojs/starlight'
   import { defineConfig } from 'astro/config'
   import starlightCustomNavigation from 'starlight-custom-navigation'
   
   export default defineConfig({
     integrations: [
       starlight({
         plugins: [
              // Default configuration
              starlightCustomNavigation()
          ],
         title: 'My Docs',
       }),
     ],
   })

3. Start the development server to preview the plugin in action.

   The plugin will automatically:

   • Show navigation buttons when scrolling
   • Keep buttons visible for 3 seconds after scrolling
   • Hide buttons when not needed
   • Support touch swipe gestures on mobile
   • Enable keyboard shortcuts for navigation