Nav Links

Tip

You can see this in action next to the site title above.

Sometimes you may want to add more links to your Starlight docs outside of the sidebar navigation. Starlight does not currently support this out of the box.

With this utility you can add a list of links to the Astro config and they will be rendered in the navigation bar in both desktop and mobile.

Setup

1. Add a new sidebar entry to the Starlight plugin in astro.config.mjs with any label that will be used in a later step.

   astro.config.mjs

   import { defineConfig } from "astro/config";
   import starlight from "@astrojs/starlight";
   import starlightUtils from "@lorenzo_lewis/starlight-utils";
   
   // https://astro.build/config
   export default defineConfig({
     integrations: [
       starlight({
         sidebar: [{
            label: "leadingNavLinks",
         }],
       }),
     ],
   });

2. Add a list of links to the items object in the newly added sidebar entry using the Starlight Links syntax.

   Currently Group and Autogenerated groups are not supported.

   astro.config.mjs

   import { defineConfig } from "astro/config";
   import starlight from "@astrojs/starlight";
   import starlightUtils from "@lorenzo_lewis/starlight-utils";
   
   // https://astro.build/config
   export default defineConfig({
     integrations: [
       starlight({
         sidebar: [{
            label: "leadingNavLinks",
            items: [
              { label: "Docs", link: "/docs" },
              { label: "References", link: "/references" }
            ]
         }],
       }),
     ],
   });

3. Add the navLinks.leading.useSidebarLabelled entry to the Starlight Utils plugin. Use the label created above for useSidebarLabelled.

   Be sure that you’ve added import starlightUtils from "@lorenzo_lewis/starlight-utils" to the top of the file.

   astro.config.mjs

   import { defineConfig } from "astro/config";
   import starlight from "@astrojs/starlight";
   import starlightUtils from "@lorenzo_lewis/starlight-utils";
   
   // https://astro.build/config
   export default defineConfig({
    integrations: [
      starlight({
        sidebar: [{
           label: "leadingNavLinks",
           items: [
             { label: "Docs", link: "/docs" },
             { label: "References", link: "/references" }
           ]
        }],
        plugins: [
          starlightUtils({
            navLinks: {
              leading: { useSidebarLabelled: "leadingNavLinks" }
            }
          })
        ]
      }),
    ],
   });

4. That’s it! ✨

Tip

The sidebar used for creating nav links will automatically be removed for generating normal sidebars.

Configuration

The sidebar can be enabled by adding the navLinks object to the Starlight Utils configuration.

astro.config.mjs

import { defineConfig } from "astro/config";
import starlight from "@astrojs/starlight";
import starlightUtils from "@lorenzo_lewis/starlight-utils";

// https://astro.build/config
export default defineConfig({
  integrations: [
    starlight({
      plugins: [
        starlightUtils({
          navLinks: {
            leading: { useSidebarLabelled: "leadingNavLinks" },
          },
        }),
      ],
    }),
  ],
});

navLinks

Type: { leading: NavConfig } | undefined

Default: undefined

Enables the navigation links for the respective position.

NavConfig

Type: { useSidebarLabelled: string }

• useSidebarLabelled: The name of the sidebar defined in the Starlight config that should be used for generating the respective nav links.