feat(sitemap): add configurable XML namespaces support #12250
Conversation
✅ Deploy Preview for astro-docs-2 ready!Built without sensitive environment variables
To edit notification comments on pull requests, go to your Netlify project configuration. |
Lunaria Status Overview🌕 This pull request will trigger status changes. Learn moreBy default, every PR changing files present in the Lunaria configuration's You can change this by adding one of the keywords present in the Tracked Files
Warnings reference
|
|
Hello! Thank you for opening your first PR to Astro’s Docs! 🎉 Here’s what will happen next:
|
ascorbic
added
add new content
Co-authored-by: Yan <[email protected]>
There was a problem hiding this comment.
Thank you for adding these docs @jdcolombo ! I've suggested some ideas for slight language polishing to make this more in the style of Astro docs. And, I'd love for you to help provide a bit of guidance on when/why someone would use this to help the reader understand/decide when this might be right for them!
| **Type:** `{ news?: boolean; xhtml?: boolean; image?: boolean; video?: boolean; }` | ||
| **Default:** `{ news: true, xhtml: true, image: true, video: true }` | ||
|
|
||
| Controls which XML namespaces are included in the sitemap generation. |
There was a problem hiding this comment.
Can we have a sentence here that explains why someone might want to do this? (See the other entries on this page like customPages)
I can see from your implementation PR that you have said "This allows users to exclude unused namespaces like xmlns:news for cleaner sitemap files." Is that the main practical reason to have this option? These are namespaces that Astro would otherwise include, but now we have a configuration to NOT include them? And, is "looking cleaner" the advantage, or is there an associated performance advantage to having less included in the XML? Are there negative consequences they are trying to avoid? Is this personal preference? How do they decide?
Also, just more for my own understanding, is there a particular reason you've chosen these 4 options? Are there more that might eventually be added? In some cases, we'd even make separate namespace.video entries with a smaller sub section for each one. I think we can get away without that here, but we may consider doing that at some point, especially if there are enough of them that just looking at the type to figure out which ones are available seems a little difficult to read.
I think you have nicely describe what this does, but our docs often try to have a tiny bit of the why so that people know when they might choose to use this config option!
Also, there is no standard set of XML namespaces, I believe? But, there's probably a list of ones that are generated by Astro by default (otherwise, why would we need a PR to allow you to exclude some of them?) I'm assuming that there are some/more that are NOT configurable to be removed? I don't know that we need to list them all, but it might be more appropriate to describe this feature as namespaces that are excluded, not included! (Since there are more included by default that you do not set and cannot explicitly include?) Something maybe like this for a first sentence (but make this accurate):
An object of XML namespaces to exclude from the generated sitemap.
What would you suggest here so that this entry sounds more like the other config options?
There was a problem hiding this comment.
Why someone would want to exclude namespaces:
The main practical reasons are:
- Excluding unused namespaces reduces XML bloat
- Smaller sitemap files are faster to parse by search engines
- Some SEO analysis tools prefer minimal sitemaps without unused declarations
- Particularly relevant for sites with very large sitemaps
Regarding the 4 namespace options:
These are the standard XML namespaces that Astro includes by default in sitemaps.
- xmlns:news - Google News sitemaps
- xmlns:xhtml - Multilingual/alternate language links
- xmlns:image - Image sitemaps
- xmlns:video - Video sitemaps
You're right that we could potentially add more namespaces in the future, and separate subsections might be worth considering as the list grows.
Suggested documentation revision:
### `namespaces`
<p>
**Type:** `{ news?: boolean; xhtml?: boolean; image?: boolean; video?: boolean; }` <br />
**Default:** `{ news: true, xhtml: true, image: true, video: true }` <br />
<Since v="3.6.0" pkg="@astrojs/sitemap" />
</p>
An object of XML namespaces to exclude from the generated sitemap.
Excluding unused namespaces can help create cleaner, more focused sitemaps that are faster for search engines to parse and use less bandwidth. For example, if your site doesn't have news content, videos, or multiple languages, you can exclude those namespaces to reduce XML bloat.
By default, all configurable namespaces (`news`, `xhtml`, `image`, and `video`) are included in your generated sitemap XML. To exclude a namespace from your sitemap generation, add a `namespaces` configuration object and set individual options to `false`:
```js title="astro.config.mjs" ins={8-14}
import { defineConfig } from 'astro/config';
import sitemap from '@astrojs/sitemap';
export default defineConfig({
site: 'https://example.com',
integrations: [
sitemap({
// Only include image and video namespaces
namespaces: {
news: false,
xhtml: false,
// image and video will be true by default
}
})
]
});
Co-authored-by: Sarah Rainsberger <[email protected]>
Co-authored-by: Sarah Rainsberger <[email protected]>
|
|
||
| Excluding unused namespaces can help create cleaner, more focused sitemaps that are faster for search engines to parse and use less bandwidth. For example, if your site doesn't have news content, videos, or multiple languages, you can exclude those namespaces to reduce XML bloat. | ||
|
|
||
| By default, all configurable namespaces (`news`, `xhtml`, `image`, and `video`) are included in your generated sitemap XML. To exclude a namespace from your sitemap generation, add a `namespaces` configuration object and set individual options to `false`: |
There was a problem hiding this comment.
| By default, all configurable namespaces (`news`, `xhtml`, `image`, and `video`) are included in your generated sitemap XML. To exclude a namespace from your sitemap generation, add a `namespaces` configuration object and set individual options to `false`: | |
| By default, all configurable namespaces (`news`, `xhtml`, `image`, and `video`) are included in your generated sitemap XML. To exclude one or more of these namespaces from your sitemap generation, add a `namespaces` configuration object and set individual options to `false`: |
| // Only include image and video namespaces | ||
| namespaces: { | ||
| news: false, | ||
| xhtml: false, | ||
| // image and video will be true by default |
There was a problem hiding this comment.
| // Only include image and video namespaces | |
| namespaces: { | |
| news: false, | |
| xhtml: false, | |
| // image and video will be true by default | |
| namespaces: { | |
| news: false, | |
| xhtml: false, |
I think this code snippet works even without the comments! I had originally thought about keeping one or the other, but I'm not sure it's needed.
|
|
||
| An object of XML namespaces to exclude from the generated sitemap. | ||
|
|
||
| Excluding unused namespaces can help create cleaner, more focused sitemaps that are faster for search engines to parse and use less bandwidth. For example, if your site doesn't have news content, videos, or multiple languages, you can exclude those namespaces to reduce XML bloat. |
There was a problem hiding this comment.
| Excluding unused namespaces can help create cleaner, more focused sitemaps that are faster for search engines to parse and use less bandwidth. For example, if your site doesn't have news content, videos, or multiple languages, you can exclude those namespaces to reduce XML bloat. | |
| Excluding unused namespaces can help create more focused sitemaps that are faster for search engines to parse and use less bandwidth. For example, if your site doesn't have news content, videos, or multiple languages, you can exclude those namespaces to reduce XML bloat. |
I love this paragraph, thank you so much for adding it! I think we can stick to just "more focused" to keep this... more focused! 😂
This pull request adds documentation for the new
namespacesconfiguration option to the sitemap integration guide. The update explains the purpose, type, and default values for this option, and provides a usage example.Sitemap integration documentation update:
namespacesoption, including its type, default values, and its role in controlling which XML namespaces are included during sitemap generation.astro.config.mjsshowing how to configure thenamespacesoption for the sitemap integration.Updated docs for withastro/astro#14285
Related issues & labels (optional)