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

Co-authored-by: Yan <[email protected]>
Co-authored-by: Emanuele Stoppa <[email protected]>
Co-authored-by: Sarah Rainsberger <[email protected]>
Co-authored-by: ArmandPhilippot <[email protected]>
Co-authored-by: bjohansebas <[email protected]>

Author: 6 people

src/content/docs/en/guides/integrations-guide/sitemap.mdx

@@ -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.
 
@@ -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()],
   // ...
 });
@@ -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>
 ```
@@ -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>
 ```
@@ -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/',
     }),
   ],
 });
@@ -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
 
-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'],
     }),
   ],
 });
@@ -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,
@@ -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',
@@ -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) {
@@ -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',
@@ -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>
 ...
 ```
@@ -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'
@@ -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