Configurable navbar

[LuHugo]

What version of starlight are you using?

0.10.2

What is your idea?

As the title says, we need a configurable navigation bar menu.
The navbar option can be added to the starlight configuration item. navbar contains the data needed to generate the menu。
For example：

export default defineConfig({
  integrations: [starlight({
       ...
	navbar: {
                showSearch: false,
                showLocale: false,
		items: [
			{
				label: "Home",
				to: "/",
				position: "left",
				activeBaseRegex: '/',
				type: "link",
			},
			{
				label: "Reference",
				to: "/reference",
				position: "left",
				activeBaseRegex: '/reference',
				type: "dropdown",
				items: [MenuItem]
			}
		]
	}
  })]
});

Why is this feature necessary?

Can organize website navigation more freely

Do you have examples of this feature in other projects?

• docusaurus navbar
• vuepress navbar

Participation

• I am willing to submit a pull request for this issue.

[delucis]

Thanks for the issue @LuHugo! We’ll soon release #709, which will make it quite easy to add a custom Astro component to the navbar for use cases like this. I’d love for us to wait and see whether that works well for people or whether we still need a custom configuration-based API.

[d1onys1us]

hello @delucis thanks for the feature impl. perhaps describing my issue (related to this) may help in getting support for how to achieve what i want:

• lets say i add a custom link to the navbar by overriding the social icons component, this link is just a link to the "Docs"
• this is because finding the "docs" is difficult on mobile if most people are used to it being in the navbar instead of a CTA

however, the overridden component disappears because i think there is some logic that hides it once the mobile breakpoint is hit. is there a way to customize that behavior as well?

the end goal is basically the ability to have some links in the navbar that persist on mobile view.

[d1onys1us]

i'd like to add some more context for others. i do know that i can remove the "splash" page from the frontmatter, which in some sense removes the need for links in the navbar because the user is already obviously "within" the docs. you can see an example here on the astro docs https://docs.astro.build/en/getting-started/ (attached a picture below).

In this case the "astro icon" and the "docs icon" on the upper left corner are separate links. so i believe (haven't tested it) you can just add a link in this fashion, and it will persist even in the mobile view. this could be a way to achieve what was described above.

anyways, not a make it or break it feature for me, so curious on others' thoughts. my general take is that it would be nice to give the flexibility if we're able to figure out a design for the dropdown that still feels intuitive / non-cluttered.

[levino]

I’d love for us to wait and see whether that works well for people or whether we still need a custom configuration-based API.

It does not work well for me. I want to use starlight on a page with other, non-starlight pages (using additional content collections, so they cannot be simply markdown files.). I am able to add links from the navigation menu to these pages by overriding the Header component. However this feels way too heavy to just add a couple of additional navigation entries.

But the real problem is, that I fail to use the @astrojs/starlight/index.astro as a template for my other pages. Of course I want to use the same navigation header for my other pages so I do not have to implement it twice. However the component needs specific props and I am failing to produce these.

Please again have a look at how docusaurus has solved this very conveniently for the users. Basically the idea should be that you have pages AND docs AND a blog etc. So instead of "taking over everything" starlight should be more of an additional feature / part of the page. Right now its usage basically cripples my site in the sense that I can only use markdown. Maybe this could be solved by refactoring the index.astro file to use some kind of Template.astro and exporting this component for the users.

[delucis]

Hey @levino, sounds like you’re describing #1175! Hopefully we can ship that soon.

[levino]

If anyone is interested, I started some work on a package with working title "shipyard". The idea is to separate the layout and design from the content collection specifications as I proposed in #1175. Unfortunately I think that unless the tight coupling is removed in starlight, starlight is kinda broken by design. At least if one wants to build something more complex than just a documentation website. "Shipyard" is supposed to eventually become a collection of building blocks to build new websites with astro fast, with or without a docs section.

I am aware that the amount of work necessary to build this package on my own is significant and I probably will fail without help. So I thought I would leave this here. If someone wants to give me a hand, I am more than willing to accept their help.

[sagargurtu]

This is a much needed basic feature in Starlight. Many other static site generators offer a way to add navbar menu items with dropdowns. Some examples:

• Vitepress
• Docusaurus