Banner is off-center on larger screen sizes

[Fryuni]

What version of starlight are you using?

0.21.5

What version of astro are you using?

4.6.0

What package manager are you using?

pnpm

What operating system are you using?

Mac, but happens on any OS

What browser are you using?

Chrome, but happens on any browser

Describe the Bug

The banner is not centered correctly on larger screens.

On smaller screens, the banner is aligned with the center of the page and the content. I'd expect that to remain true as the screen-size increases. However, once the content reaches its maximum width, the banner gets off-center since it is actually being centered on the total space between the two sidebars.

Link to Minimal Reproducible Example

https://stackblitz.com/edit/github-alovcj?file=src%2Fcontent%2Fdocs%2Findex.mdx

Participation

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

[delucis]

Oh man, good catch! I… am not sure what the correct fix here is (except for only using banner with the table of contents disabled 😄).

Aligning the text with the page contents looks odd because it is then off-center in relation to the banner background:

But equally cutting off the banner background doesn’t look great:

I’ll admit that the current banner placement was chosen kind of quickly and pragmatically.

Other common locations don’t work super well with Starlight’s layout:

• Above everything else at the top of the page — becomes problematic due to Starlight’s sticky header. If the header scrolled out of view, it could be less disruptive (see Docusaurus for an example). This was also a little API related — we landed on a page-specific banner API to make i18n easier, but the position at the top of the page suggests a global banner more than a page banner:

  

• Above the content pane would be another possibility, more aligned with our “per-page” banner, but that structure has some of the same issues as the previous possibility: given the nav bar is fixed, should the banner scroll? If it does, we probably want to also scroll the table of contents right sidebar up a little when it moves out of the viewport, so there isn’t a strange gap at the top.

  

Probably solving something for this last option would be the best approach if we can do it? It already works on mobile quite OK, so it would just be the details of the desktop behaviour that need fixing. One thing that should also be checked for accessibility is that this would move the banner outside of <main>.

[Fryuni]

I've known this problem for months now, I just kept forgetting to report it. I fixed it on my fork long ago with your last option.

The banner is not fixed as you scroll down the page, so the right sidebar feels like it is floating. That was the best I could do with my limited front-end abilities.

https://fryuni.dev/deep-dive/astro-view-transitions/browser-api/:

[delucis]

Yes, exactly. I think that direction but with the right sidebar scrolling up to look less out of place would make sense. I actually don’t hate the lower ToC, but it would be inconsistent with pages without a banner I guess.

[moonclavedev]

@delucis you touched on this here:

Above everything else at the top of the page — becomes problematic due to Starlight’s sticky header. If the header scrolled out of view, it could be less disruptive (see Docusaurus for an example). This was also a little API related — we landed on a page-specific banner API to make i18n easier, but the position at the top of the page suggests a global banner more than a page banner:

I think the root of this alignment issue comes down to a conflation of two distinct UI patterns:

1. Global Announcement Banner
   This type of banner is typically used for site-wide messages—like critical updates or event announcements. It's usually positioned above the main layout and intentionally spans the full width of the viewport, outside of the content flow. Alignment with content isn't expected or necessary.

2. Page-Level Callout or Notification
   This kind of message is scoped to the current page’s content—like a contextual update or alert. It usually appears within the content container and aligns with the readable column, not the full viewport.

Right now, the current Starlight implementation feels like it’s trying to do both at once, which leads to visual inconsistency—especially on larger screens.

My recommendation would be to decouple these two patterns.

• Introduce a proper global announcement banner via the site config—similar to how Docusaurus handles it: https://docusaurus.io/docs/api/themes/configuration#announcement-bar
• For page-specific messaging, encourage the use of Callout / Aside components that live within the content layout and align naturally with it.

This would simplify the mental model for contributors and designers, and eliminate the awkward layout behavior that happens when trying to center a hybrid solution across varying screen sizes.

I've also been a fan of position:sticky; for fixed headers, as it makes situations like this much easier to deal with: https://dev.to/luisaugusto/stop-using-fixed-headers-and-start-using-sticky-ones-1k30

I also prefer a global banner that is abled to be scrolled out of view (instead of taking up vertical real estate which then relies on a close button to solve).

[trueberryless]

Global banner / Announcement

My recommendation would be to decouple these two patterns.

I agree. A global banner enhancement for Starlight would be great and in my opinion, Chris screenshot demonstrates really good that it would look awesome and convey the "global" banner feeling.

There is also already a discussion for such a topic: #1535

Page-specific banner

Regarding the changes of page-specific banners, I would not completely drop the support of them, alto encouraging users to use Aside components would also be a possibility. However, I think that themes like Starlight Rapide or Starlight Next handle page-specific banner styles quite well and we could adopt Starlight's default styling to aim for something similar.

In my opinion, both themes use the same approach to solve the

cutting off the banner background doesn’t look great
problem:

No rounded corners, no margin:

Rounded corners, margin (makes it look more "inline"):

Conclusion

I think the only caveat for such a decupling solution would be confusion if both banners (global and page-specific) are used on one page.

[KTrain5169]

Conclusion

I think the only caveat for such a decupling solution would be confusion if both banners (global and page-specific) are used on one page.

I think it wouldn't be confusing if both banners are used, it's more or less clear which one is global (the one taking up space before the header component) and which one is page-specific (the one that appears below the header component/right before the actual content), though on smaller screens using both would probably take up too much space.

Alternatively, I think some form of an override toggle at the global/page level could probably work instead (I only put global there in the case that someone might want to override with their page banners on all pages that have a page-level banner).