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.

[dionysuzx]

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.

[dionysuzx]

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.

[levino]

Thank you for taking the time to come back to me on this. I am aware of the capabilities of astro and I think mostly of starlight. However docusaurus has simply made some very clever design choices which makes it not only suitable for documentation websites but also standalone pages, blogs or a combination of all these features within one page. The only missing pieces from docusaurus are:

• server side rendering for per route authentication
• support of content collections for bulk page generation

But is a mean tool to build content-driven websites real fast. What does such a software need?

• A simple and consistent design / layout which supports usual pages, docs pages and blog pages
• Auto generated navigation if desired (for blog and docs)
• Configurable theming and navigation

Starlight provides the configurable theming and the auto generated navigation. However it always brings "docs" which a lot of people might not need. They simply want a blog. Why not use starlight for this too? Currently they have to jump hoops to add a blog functionality to starlight and the addon (at least last time I checked) had to do some heavy plumbing in order to get things working.

It would just help to separate concerns like in docusaurus where there is first the simple basic layout and page generation and then docs etc. come as plugins. Docs and blog come with the boilerplate code during scaffolding, so no problem with user experience. I really think that docusaurus made a lot of the api decisions very nicely (maybe by luck, maybe by skill, I cannot say) and that starlight would benefit from adopting their api. It could then become a general purpose page builder and make docusaurus obsolete.

[delucis]

Aha, thanks for the details. So IIUC you’re saying that the basic templating concepts are good (page layout, standardised nav bar, routing, dark/light theme, search, etc.) but you’d like more flexibility in the type of pages available to make using it for other purposes easier while still maintaining a consistent layout, components etc.?

[levino]

I find starlight is pretty far in this regard. One can make arbitrary pages and reuse the starlight layout. The only missing puzzle piece is a configurable "global" navigation (a navigation which shows on all pages and behaves nicely on mobile, where it potentially needs to integrate with the docs navigation for lack of space).

However I had a look of how this functionality is implemented, and my analyses is that it was done with much pain simply because of the architecture choices that were made for starlight, most importantly the tight coupling of the "docs functionality" and the "layout and design". Instead of "decorating the docs pages" one has to "undecorate the non-docs pages" which feels suboptimal to me.

[levino]

Also maybe for understanding the background a bit: I am using docusaurus to build community pages for small clubs (think gardening, sports). They often want to write down some rules, maybe have a list of people responsible for certain areas etc. and I use "docs" for that. Then they want to record their meeting notes, give updates on certain topics, etc. and I use "blog" for that. And then they want some general pages like "about", "imprint" etc. Maybe they also have multiple sections in the club so each section needs their own docs or something but the blog is for the whole club.

Also I wanted to integrate some more content based functionality in one of these sites, which is a garden planning tool where one can use one content collection to specify a group of plants for a bed and then see when do to what. This stuff simply does not work with docusaurus, so I switched to astro but then I had to bother with all the design stuff and the navigation generation for the docs etc. I saw starlight and thought: Cool, it is all there already, but unfortunately some crucial things (like having a navigation menu for the about and the imprint) does not work. This is why I more or less rewrote starlight from scratch https://github.com/levino/levinkeller.de/tree/main/shipyard. It is a very poor attempt at achieving what you guys have done, but in my opinion it fixes a big mistake that was made when starlight was initially created. If this mistake was fixed, it would have far greater potential to be a page builder for any website (which would all look pretty much the same, but who cares? Done is better than perfect, hm?)

[delucis]

Thank you! I appreciate all the context and detailed feedback.

Starlight's origin is from building out our docs template to be easier to use and adapt for more people, but for sure that led to some decisions that are restrictive to other uses (and there are also a few spots — like in any software project probably — where we cut a corner or two to get things working for the intended use case that also make customisations harder than they could be).

I hope we'll be able to address some of these pain points in the future.

[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

[vauxia]

I got a basic site up and running quickly, but this issue has been bogging me down me down for hours. I agree this is a very basic feature, and it should not be difficult for new users.

As far as I can tell, there is no way to add navbar items. You can, however, override an adjacent component (theme selector, title, etc) and shoehorn in some links before/after the otherwise-unrelated component.

From a software organization/architecture standpoint, this is yucky and indirect.

From an onboarding perspective, it creates a lot of pain and confusion for a new user task that should be very simple. ( For instance, I am now trying to troubleshoot an error in the Search component because I overrode the SiteTitle component, because I wanted to add some general links in a universally expected place on the page..? )

[delucis]

Thanks for the feedback!

[jarodtaylor]

This is the situation I ran into. I was able to create multiple sidebars using the link provided by @delucis in #687 comment. Works wonderfully using the component overrides!

My problem now is I'd like navigation links in the Header to go to these different sections of the site. This allows us to break out our documentation into sections like (API, Apps & Services, Theming, etc). Otherwise, the sidebar will be massive.

I tried to override the Header.astro component, but as described above, it slots my Navigation Links outside of the rest of the header elements. Similar to @vauxia I tried doing this in the other Header components (e.g. SiteTitle.astro) but even that has its issues.

[jbergstroem]

I also found the complexity of adding top level items with a sidebar that shows the state of said page instead of the top level sidebar much higher than expected. There is a plugin for that but it will not work once you start overriding components. I don't mind adapting my overridden components from starlight, but then to merge this with plugin-specific logic you ultimately end up just rebuilding it for yourself.