Allow sidebar to associate subpages with parent pages without explicitly listing them

[sdht0]

What version of starlight are you using?

0.32.5

What is your idea?

Say I have a sidebar entry: { label: 'Developer Guide', link: '/developer-guide' },. Say I also have pages '/developer-guide/build-from-source' and '/developer-guide/formatting-rules'. I want the sidebar to highlight "Developer Guide" when any of these pages are open, without listing these subpages in the sidebar.

Is this currently possible in Starlight? Did not find a way in the docs.

Why is this feature necessary?

I don't want to explicitly list all the subpages, to avoid too deep hierarchies in the sidebar, but still highlight the first parent page that has an entry in the sidebar.

Do you have examples of this feature in other projects?

• activeMatch https://vitepress.dev/reference/default-theme-nav#customize-link-s-active-state

Participation

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

[delucis]

Hi @sdht0! Thanks for sharing that VitePress API — always interesting to see how other tools approach these things.

Currently there’s no dedicated API to highlight parent pages like you want, but you can achieve this with route middleware. For example, based on your developer guide structure:

import { defineRouteMiddleware } from '@astrojs/starlight/route-data';

export const onRequest = defineRouteMiddleware((context) => {
  const { sidebar } = context.locals.starlightRoute;

  for (const entry of sidebar) {
    if (
      // Find the top-level link to the developer guide parent page
      entry.type === 'link' &&
      entry.href === '/developer-guide/' &&
      // If this page is in the developer-guide/ subdirectory, mark the parent page as current.
      context.url.pathname.startsWith('/developer-guide/')
    ) {
      entry.isCurrent = true;
    }
  }
});

Here’s a small example of that running in context: https://stackblitz.com/edit/github-xugkbk2l?file=astro.config.mjs,src%2Froute-data.ts

[delucis]

100% — definitely hacky — just wanted to provide quick solutions given core features can take some time. Thanks again for raising the request as it wasn’t something we’d considered before.

[sdht0]

I think the coolest option would be automatically search for a parent page in the sidebar if no entry is currently highlighted. That way would minimize the cases where opening a subpage removes any sidebar selection, making it look unpolished, leaving the manual tagging work only for the edge cases.

It already seems possible to do with this middleware technique.

[delucis]

Oh yeah, you could do that with the current middleware approach too in theory:

import {
  defineRouteMiddleware,
  type StarlightRouteData,
} from '@astrojs/starlight/route-data';

export const onRequest = defineRouteMiddleware((context) => {
  const { sidebar } = context.locals.starlightRoute;

  // If the sidebar doesn’t contain a link highlighted for this page, find the link most similar
  // to the current page and highlight that.
  if (!hasCurrent(sidebar)) {
    const currentLink = findCurrentLinkCandidate(sidebar, context.url.pathname);
    if (currentLink) {
      currentLink.isCurrent = true;
    }
  }
});

/**
 * Test if a Starlight sidebar contains a highlighted current link.
 */
function hasCurrent(sidebar: StarlightRouteData['sidebar']): boolean {
  for (const entry of sidebar) {
    if (entry.type === 'group') {
      if (hasCurrent(entry.entries)) {
        return true;
      }
    } else if (entry.isCurrent) {
      return true;
    }
  }
  return false;
}

/**
 * Find the best candidate to mark as current for a page.
 * Chooses the link with the highest specificity, e.g. for a page like `/developer-guide/something/`, `/developer-guide/` is preferred over `/`.
 * Specificity is the number of meaningful path segments in a URL, e.g. `/` = 0, `/a` = 1, `/a/b` = 2, etc.
 *
 */
function findCurrentLinkCandidate(
  sidebar: StarlightRouteData['sidebar'],
  pathname: string
): SidebarLink | undefined {
  let candidate: SidebarLink | undefined;
  for (const entry of sidebar) {
    if (entry.type === 'group') {
      const groupCandidate = findCurrentLinkCandidate(entry.entries, pathname);
      if (getRank(groupCandidate?.href) > getRank(candidate?.href)) {
        candidate = groupCandidate;
      }
    } else {
      if (
        pathname.slice(0, entry.href.length) === entry.href &&
        getRank(entry.href) > getRank(candidate?.href)
      ) {
        candidate = entry;
      }
    }
  }
  return candidate;
}

/**
 * Rank the specificity of a URL pathname by number of meaninful segments, e.g. `/` = 0, `/a` = 1, `/a/b` = 2, etc.
 */
function getRank(path: string | undefined): number {
  return path?.split('/').filter(Boolean).length || 0;
}

type SidebarLink = Extract<
  StarlightRouteData['sidebar'][number],
  { type: 'link' }
>;

Here’s a working example on StackBlitz: https://stackblitz.com/edit/github-xugkbk2l-o1hyvyac?file=astro.config.mjs,src%2Froute-data.ts

I think it might be a little tricky in practice as a default, e.g. if you link / in the sidebar, should a /example/ page not in the sidebar highlight the homepage? It’s more expected for nested pages, but seems a bit weirder for something like that potentially. We’re also a bit cautious with sidebar logic as it’s an area that is exponential often (e.g. a site with 4,000 pages has to generate 4,000 x 4,000 links potentially across its sidebars), so it’s something we’ve had to optimize a bit over time for larger sites and anything that would have us iterate over sidebar items multiple times by default could be undesirable. (So we’d likely need to do this while building the sidebar rather than something like my example code above.) But it’s an interesting idea for sure.

[sdht0]

if you link / in the sidebar, should a /example/ page not in the sidebar highlight the homepage

Probably yes? Questions like these are usually left as an exercise for the developer, as configurable options haha.

have us iterate over sidebar items multiple times by default could be undesirable

Yes I already don't like the recursive search. How hard or desirable would it be to maintain a reverse index of url to entry?

[delucis]

How hard or desirable would it be to maintain a reverse index of url to entry?

Internally, I guess not super hard? It’s nested, so I guess you’d need a map something like this to store the full path:

{
  [{ href: '/', ... }]: [0],
  [{ href: '/guides/example-1/', ... }]: [1, 0],
  [{ href: '/guides/example-2/', ... }]: [1, 1],
}