Impossible to cleanly opt out of default sitemap filename

[angelikatyborska]

What version of starlight are you using?

0.36.0

What version of astro are you using?

5.14.1

What package manager are you using?

npm 11.2.0

What operating system are you using?

macos 14.7

What browser are you using?

not relevant to the bug

Describe the Bug

I need to customize the filename of the sitemap generated for my Starlight project. To do so, I am adding @astrojs/sitemap to astro.config.ts myself:

export default defineConfig({
  adapter: vercelAdapter(),
  integrations: [
    sitemap({
      filenameBase: 'sitemap-foobar',
   }),
  ]
})

However, I still want canonical links on my pages, so I do want to include site: 'https://example.com' in the config as well.

Starlight has code that detects that I have already added the sitemap plugin, so it doesn't add the plugin again and so it won't generate a second sitemap. That's good. However, it still adds a link to my page's head that links to the default sitemap-index.xml file (that doesn't exist in my project) because I set site in my config.

I would expect Starlight not to add a link to sitemap-index.xml the page's head if I am explicitly adding the sitemap plugin to the Astro config, especially if I'm using a different filename.

Link to Minimal Reproducible Example

https://idx.google.com/astro-starlight-75283240

Participation

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

[HiDeoo]

Thanks for the feedback 🙌

I would expect Starlight not to add a link to sitemap-index.xml the page's head if I am explicitly adding the sitemap plugin to the Astro config, especially if I'm using a different filename.

Interesting case. I think (and maybe I'm wrong) that in most cases when users manually add the sitemap integration, tweaking the filenameBase option may be a less common use case. I would guess that most users would just tweak other options.

This makes me wonder that if instead of not adding the <link> at all when the sitemap integration is manually added, we should instead dedupe default and custom <link rel="sitemap" ...> tag(s) in the head. This would means that for current users adding the sitemap integration manually, nothing would change and this would not be a breaking change. But for users tweaking the filenameBase option, specifying custom <link rel="sitemap" ...> tag(s) through the Starlight head configuration option would work as expected and only the custom <link rel="sitemap" ...> tag(s) would be included in the head 🤔

[delucis]

This makes me wonder that if instead of not adding the <link> at all when the sitemap integration is manually added, we should instead dedupe default and custom <link rel="sitemap" ...> tag(s) in the head.

That makes sense to me.

It would be nice to be able to detect this more cleanly and even adjust automatically but we can’t see the options passed to additional integrations. One possibility would be allowing setting some sitemap configuration directly in the Starlight config, but that means duplicating docs and could be tricky given not all sitemap options could be supported given how we wire up i18n etc. under the hood.

So agreed, handling a custom head value cleanly seems like a reasonably simple approach for this use case.

[angelikatyborska]

This makes me wonder that if instead of not adding the at all when the sitemap integration is manually added, we should instead dedupe default and custom <link rel="sitemap" ...> tag(s) in the head.

That would mean that I would be forced to add the sitemap link to the head myself to prevent having an incorrect link added by Starlight, right?

This is less than ideal for my project. I would like to have no sitemap link in the head.

For reasons that are outside of my control, I'm serving two Astro projects from one domain. Project A is the "main" one, project B is the Starlight project. Project A serves /robots.txt that references the sitemap index file sitemap-index. The sitemap-index file lists a bunch of different sitemaps, including my sitemap-foobar-index from project B.

I do not want project B's pages to have links in the head claiming that the sitemap is sitemap-foobar-index because that is not true for all the pages served under that one domain (coming from two different projects).

I hope that explanation was understandable - I know this is a crazy use case but it is what it is 🙈

[HiDeoo]

I see, definitely uncommon I would say. Maybe for such a niche use case:

• Still ship a change deduping sitemap links in the head (as I think it's still a good idea).

• Relying on a route data middleware to filter out the sitemap link entirely in your specific case (which would not require any change to the head config at all for you):

  // src/routeData.ts
  import { defineRouteMiddleware } from '@astrojs/starlight/route-data';
  
  export const onRequest = defineRouteMiddleware((context) => {
  	const { starlightRoute } = context.locals;
  
  	starlightRoute.head = starlightRoute.head.filter(
  		(entry) => entry.tag !== 'link' || entry.attrs?.rel !== 'sitemap'
  	);
  });

[angelikatyborska]

I had no idea I can do that in the middleware - I'll give it a try. Thank you!