How to Add Links to Starlight's Navbar

Enhancing the navigation of your Starlight-powered site is a great way to improve usability and guide users to important resources. In this guide, I’ll walk you through how to dynamically add links to Starlight’s navbar by creating a custom component and updating your configuration.

Step 1: Create the Links Data File

First, create a JSON file to store the links you want to display in the navbar. Save this file as src/data/links.json.

[
  {
    "id": 1,
    "text": "Starlight",
    "link": "https://starlight.astro.build/"
  },
  {
    "id": 2,
    "text": "Astro",
    "link": "https://astro.build/"
  }
]

This file contains an array of link objects, each with an id, text, and link property.

Step 2: Override the SiteTitle Component

Next, create a custom component to display the links in the navbar. Save this file as src/starlightOverrides/SiteTitle.astro.

---
import Default from '@astrojs/starlight/components/SiteTitle.astro';

import type { Props } from '@astrojs/starlight/props';
import links from '../data/links.json';
---

<div>
    <Default {...Astro.props} />
    <ul>
      {links.map(link => (
        <li key={link.id}>
          <a href={link.link}>{link.text}</a>
        </li>
      ))}
    </ul>
</div>

<style>
  div {
    display: flex;
    align-items: center;
    gap: var(--sl-nav-gap);
  }
  ul {
    display: flex;
    list-style: none;
    padding: 0;
    gap: var(--sl-nav-gap);
  }
  a {
    text-decoration: none;
    font-weight: 600;
    color: var(--sl-color-text-accent);
  }

  a:hover,
  a:focus {
    color: var(--sl-color-white);
  }

  [aria-current="page"],
  [aria-current="page"]:hover,
  [aria-current="page"]:focus {
    font-weight: 600;
  }

  @media (min-width: 50rem) {
    a {
      font-size: var(--sl-text-sm);
    }
  }
</style>

This component:

Imports the links.json file.
Iterates over the links using the map function to dynamically generate the list items.
Styles the links and ensures they integrate seamlessly with the existing design.

Step 3: Update the Configuration

Finally, update your astro.config.mjs file to use the custom SiteTitle component.

// @ts-check
import { defineConfig } from 'astro/config';
import starlight from '@astrojs/starlight';

// https://astro.build/config
export default defineConfig({
  integrations: [
    starlight({
      title: 'My Docs',
      social: {
        github: 'https://github.com/withastro/starlight',
      },
      components: {
        SiteTitle: './src/starlightOverrides/SiteTitle.astro',
      },
      sidebar: [
        {
          label: 'Guides',
          items: [
            // Each item here is one entry in the navigation menu.
            { label: 'Example Guide', slug: 'guides/example' },
          ],
        },
        {
          label: 'Reference',
          autogenerate: { directory: 'reference' },
        },
      ],
    }),
  ],
});

The components property specifies the custom SiteTitle component path, overriding the default behavior.

Conclusion

By following these steps, you can easily add dynamic links to Starlight’s navbar. This approach allows you to manage your links in a centralized JSON file and ensures a seamless integration with your site’s design. Happy coding!

← Back to blog

Table of contents

How to Add Links to Starlight's Navbar

Step 1: Create the Links Data File

Step 2: Override the SiteTitle Component

Step 3: Update the Configuration

Conclusion