Adding Top Menu Links

By default, Astro Starlight features a streamlined header with only social menu icons and a theme switching menu. If you want to add some links to the header for navigating the site, you can do this by overriding the SocialIcons component in the header with a custom header component.

Create a custom header component

Create a new component that adds navigation links to the header and retains the default social icons and theme toggle:

src/components/HeaderActions.astro

---
import Default from "@astrojs/starlight/components/SocialIcons.astro";
---

<div class="header-actions-wrapper">
    <!-- Top Nav Menu Items matching Theme Selector styling -->
    <nav class="nav-links" aria-label="Main navigation">
        <a href="/">Home</a>
        <a href="/about/me">About</a>
        <a href="/articles/overview">Articles</a>
    </nav>

    <!-- Retain default social icons & theme toggle -->
    <Default><slot /></Default>
</div>

<style>
    .header-actions-wrapper {
        display: flex;
        align-items: center;
        gap: 1rem;
    }

    .nav-links {
        display: flex;
        align-items: center;
        gap: 1rem;
    }

    .nav-links a {
        display: flex;
        align-items: center;
        padding: 0.5rem 0; /* Padding only on top/bottom for a clean hit-box */
        font-size: var(--sl-text-sm);
        font-weight: 500;
        text-decoration: none;
        color: var(--sl-color-gray-3);
        transition: color 0.15s ease;
    }

    /* Only changes the text color on hover/focus—no background box */
    .nav-links a:hover,
    .nav-links a:focus-visible {
        color: var(--sl-color-white);
    }

    @media (max-width: 50rem) {
        .nav-links {
            display: none;
        }
    }
</style>

Register the component override

Update your astro.config.mjs file to override the SocialIcons component with you custom header component:

astro.config.mjs

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

export default defineConfig({
  integrations: [
    starlight({
      components: {
        SocialIcons: './src/components/HeaderActions.astro',
      },
    }),
  ],
});