Skip to content

docs(en/sitemap.mdx): describe customSitemaps #11563

New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Merged
merged 8 commits into from
Aug 12, 2025
Merged

docs(en/sitemap.mdx): describe customSitemaps #11563

Changes from all commits
Commits
Show all changes
8 commits
Select commit Hold shift + click to select a range
4f53f16
docs(en/sitemap.mdx): describe customSitemaps
gouravkhunger Apr 29, 2025
7d8094b
fix: grammar
gouravkhunger Jun 17, 2025
8a6f793
Merge branch 'main' into custom-sitemaps
ematipico Jul 25, 2025
2fb2dfd
sarah light style edit, plus update url to example.com page-wide
sarah11918 Jul 25, 2025
5a38307
import the Since component
sarah11918 Jul 25, 2025
adbc8c5
since component version for the sitemap package
sarah11918 Jul 25, 2025
72f8718
typo fix
sarah11918 Jul 25, 2025
228c7a7
Merge branch 'main' into custom-sitemaps
sarah11918 Aug 12, 2025
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
104 changes: 67 additions & 37 deletions src/content/docs/en/guides/integrations-guide/sitemap.mdx
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -9,6 +9,7 @@ category: other
i18nReady: true
---
import PackageManagerTabs from '~/components/tabs/PackageManagerTabs.astro';
import Since from '~/components/Since.astro';

This **[Astro integration][astro-integration]** generates a sitemap based on your pages when you build your Astro project.

Expand Down Expand Up @@ -93,7 +94,7 @@ import { defineConfig } from 'astro/config';
import sitemap from '@astrojs/sitemap';

export default defineConfig({
site: 'https://stargazers.club',
site: 'https://example.com',
integrations: [sitemap()],
// ...
});
Expand All @@ -112,7 +113,7 @@ For extremely large sites, there may also be additional numbered files like `sit
<?xml version="1.0" encoding="UTF-8"?>
<sitemapindex xmlns="http://www.sitemaps.org/schemas/sitemap/0.9">
<sitemap>
<loc>https://stargazers.club/sitemap-0.xml</loc>
<loc>https://example.com/sitemap-0.xml</loc>
</sitemap>
</sitemapindex>
```
Expand All @@ -121,10 +122,10 @@ For extremely large sites, there may also be additional numbered files like `sit
<?xml version="1.0" encoding="UTF-8"?>
<urlset xmlns="http://www.sitemaps.org/schemas/sitemap/0.9" xmlns:news="http://www.google.com/schemas/sitemap-news/0.9" xmlns:xhtml="http://www.w3.org/1999/xhtml" xmlns:image="http://www.google.com/schemas/sitemap-image/1.1" xmlns:video="http://www.google.com/schemas/sitemap-video/1.1">
<url>
<loc>https://stargazers.club/</loc>
<loc>https://example.com/</loc>
</url>
<url>
<loc>https://stargazers.club/second-page/</loc>
<loc>https://example.com/second-page/</loc>
</url>
</urlset>
```
Expand Down Expand Up @@ -201,10 +202,10 @@ import { defineConfig } from 'astro/config';
import sitemap from '@astrojs/sitemap';

export default defineConfig({
site: 'https://stargazers.club',
site: 'https://example.com',
integrations: [
sitemap({
filter: (page) => page !== 'https://stargazers.club/secret-vip-lounge/',
filter: (page) => page !== 'https://example.com/secret-vip-lounge/',
}),
],
});
Expand All @@ -219,32 +220,61 @@ import { defineConfig } from 'astro/config';
import sitemap from '@astrojs/sitemap';

export default defineConfig({
site: 'https://stargazers.club',
site: 'https://example.com',
integrations: [
sitemap({
filter: (page) =>
page !== 'https://stargazers.club/secret-vip-lounge-1/' &&
page !== 'https://stargazers.club/secret-vip-lounge-2/' &&
page !== 'https://stargazers.club/secret-vip-lounge-3/' &&
page !== 'https://stargazers.club/secret-vip-lounge-4/',
page !== 'https://example.com/secret-vip-lounge-1/' &&
page !== 'https://example.com/secret-vip-lounge-2/' &&
page !== 'https://example.com/secret-vip-lounge-3/' &&
page !== 'https://example.com/secret-vip-lounge-4/',
}),
],
});
```

### customPages
Copy link
Member

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Noting that this content is NOT part of the attached feature PR, but since the new entry was modelled on it, and I didn't exactly love the old one, I've updated both together to match a preferred structure.

Bonus points: if anyone can find when customPages was added, it would be amazing (but not necessary!) to include the since/version for that entry, too.

Copy link
Member

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

I found the implementation PR (withastro/astro#3315) but it seems changesets wasn't a thing yet, it's from 2022.

I looked at changelogs (both in sitemap and core) and I can't find anything. It seems it predates Astro v1.0.0! In CHANGELOG-v1.md the oldest PR is around 4225 (while the implementation is 3315). And looking at PRs number in the sitemap changelog, it seems this was implemented around the v0.1.0 of the integration! (4225 is the first PR in 1.0.2 and there is no PR number before that).

So maybe it's fine to omit Since for customPages? 😅

Copy link
Member

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Excellent, thank you for hunting! Yes, our typical M.O. is to only put things that were introduced after v1, so it's fine!

Copy link
Member

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Rereading what I wrote, I noticed I mixed up the numbers between the tabs... 😅 In the sitemap changelog, the implementation PR should be between 0.0.2 and 0.1.1. But the outcomes seem the same, it's old and predates Astro v1!


In some cases, a page might be part of your deployed site but not part of your Astro project. If you'd like to include a page in your sitemap that *isn't* created by Astro, you can use this option.
An array of externally-generated pages to be included in the generated sitemap file.

Use this option to include pages in your sitemap that are a part of your deployed site but are not created by Astro.

```js title="astro.config.mjs" ins={8}
import { defineConfig } from 'astro/config';
import sitemap from '@astrojs/sitemap';

export default defineConfig({
site: 'https://example.com',
integrations: [
sitemap({
customPages: ['https://example.com/external-page1', 'https://example.com/external-page2'],
}),
],
});
```

### customSitemaps

<p>

**Type:** `string[]`<br />
**Default:** `[]`<br />
<Since v="3.5.0" pkg="@astrojs/sitemap" />
</p>

An array of externally-generated sitemaps to be included in the `sitemap-index.xml` file along with the generated sitemap entries.

Use this option to include external sitemaps in the `sitemap-index.xml` file created by Astro for sections of your deployed site that have their own sitemaps not created by Astro. This is helpful when you host multiple services under the same domain.

```js title="astro.config.mjs" ins={8}
import { defineConfig } from 'astro/config';
import sitemap from '@astrojs/sitemap';

export default defineConfig({
site: 'https://stargazers.club',
site: 'https://example.com',
integrations: [
sitemap({
customPages: ['https://stargazers.club/external-page', 'https://stargazers.club/external-page2'],
customSitemaps: ['https://example.com/blog/sitemap.xml', 'https://example.com/shop/sitemap.xml'],
}),
],
});
Expand All @@ -259,7 +289,7 @@ import { defineConfig } from 'astro/config';
import sitemap from '@astrojs/sitemap';

export default defineConfig({
site: 'https://stargazers.club',
site: 'https://example.com',
integrations: [
sitemap({
entryLimit: 10000,
Expand All @@ -283,7 +313,7 @@ import { defineConfig } from 'astro/config';
import sitemap from '@astrojs/sitemap';

export default defineConfig({
site: 'https://stargazers.club',
site: 'https://example.com',
integrations: [
sitemap({
changefreq: 'weekly',
Expand Down Expand Up @@ -319,7 +349,7 @@ import { defineConfig } from 'astro/config';
import sitemap from '@astrojs/sitemap';

export default defineConfig({
site: 'https://stargazers.club',
site: 'https://example.com',
integrations: [
sitemap({
serialize(item) {
Expand Down Expand Up @@ -356,11 +386,11 @@ import { defineConfig } from 'astro/config';
import sitemap from '@astrojs/sitemap';

export default defineConfig({
site: 'https://stargazers.club',
site: 'https://example.com',
integrations: [
sitemap({
i18n: {
defaultLocale: 'en', // All urls that don't contain `es` or `fr` after `https://stargazers.club/` will be treated as default locale, i.e. `en`
defaultLocale: 'en', // All urls that don't contain `es` or `fr` after `https://example.com/` will be treated as default locale, i.e. `en`
locales: {
en: 'en-US', // The `defaultLocale` value must present in `locales` keys
es: 'es-ES',
Expand All @@ -377,28 +407,28 @@ The resulting sitemap looks like this:
```xml title="sitemap-0.xml"
...
<url>
<loc>https://stargazers.club/</loc>
<xhtml:link rel="alternate" hreflang="en-US" href="https://stargazers.club/"/>
<xhtml:link rel="alternate" hreflang="es-ES" href="https://stargazers.club/es/"/>
<xhtml:link rel="alternate" hreflang="fr-CA" href="https://stargazers.club/fr/"/>
<loc>https://example.com/</loc>
<xhtml:link rel="alternate" hreflang="en-US" href="https://example.com/"/>
<xhtml:link rel="alternate" hreflang="es-ES" href="https://example.com/es/"/>
<xhtml:link rel="alternate" hreflang="fr-CA" href="https://example.com/fr/"/>
</url>
<url>
<loc>https://stargazers.club/es/</loc>
<xhtml:link rel="alternate" hreflang="en-US" href="https://stargazers.club/"/>
<xhtml:link rel="alternate" hreflang="es-ES" href="https://stargazers.club/es/"/>
<xhtml:link rel="alternate" hreflang="fr-CA" href="https://stargazers.club/fr/"/>
<loc>https://example.com/es/</loc>
<xhtml:link rel="alternate" hreflang="en-US" href="https://example.com/"/>
<xhtml:link rel="alternate" hreflang="es-ES" href="https://example.com/es/"/>
<xhtml:link rel="alternate" hreflang="fr-CA" href="https://example.com/fr/"/>
</url>
<url>
<loc>https://stargazers.club/fr/</loc>
<xhtml:link rel="alternate" hreflang="en-US" href="https://stargazers.club/"/>
<xhtml:link rel="alternate" hreflang="es-ES" href="https://stargazers.club/es/"/>
<xhtml:link rel="alternate" hreflang="fr-CA" href="https://stargazers.club/fr/"/>
<loc>https://example.com/fr/</loc>
<xhtml:link rel="alternate" hreflang="en-US" href="https://example.com/"/>
<xhtml:link rel="alternate" hreflang="es-ES" href="https://example.com/es/"/>
<xhtml:link rel="alternate" hreflang="fr-CA" href="https://example.com/fr/"/>
</url>
<url>
<loc>https://stargazers.club/es/second-page/</loc>
<xhtml:link rel="alternate" hreflang="es-ES" href="https://stargazers.club/es/second-page/"/>
<xhtml:link rel="alternate" hreflang="fr-CA" href="https://stargazers.club/fr/second-page/"/>
<xhtml:link rel="alternate" hreflang="en-US" href="https://stargazers.club/second-page/"/>
<loc>https://example.com/es/second-page/</loc>
<xhtml:link rel="alternate" hreflang="es-ES" href="https://example.com/es/second-page/"/>
<xhtml:link rel="alternate" hreflang="fr-CA" href="https://example.com/fr/second-page/"/>
<xhtml:link rel="alternate" hreflang="en-US" href="https://example.com/second-page/"/>
</url>
...
```
Expand Down Expand Up @@ -434,7 +464,7 @@ import { defineConfig } from 'astro/config';
import sitemap from '@astrojs/sitemap';

export default defineConfig({
site: 'https://stargazers.club',
site: 'https://example.com',
integrations: [
sitemap({
filenameBase: 'astronomy-sitemap'
Expand All @@ -443,7 +473,7 @@ export default defineConfig({
});
```

The given configuration will generate sitemap files at `https://stargazers.club/astronomy-sitemap-0.xml` and `https://stargazers.club/astronomy-sitemap-index.xml`.
The given configuration will generate sitemap files at `https://example.com/astronomy-sitemap-0.xml` and `https://example.com/astronomy-sitemap-index.xml`.

## Examples

Expand Down