Fix: document sitemap + SSR use case (#3689)

* fix: offer suggestion for SSR sitemap users

* docs: add customPages to README

* chore: changeset

.changeset/sixty-mirrors-bake.md

@@ -0,0 +1,5 @@
+---
+'@astrojs/sitemap': patch
+---
+
+Add warning log for sitemap + SSR adapter, with suggestion to use customPages configuration option

packages/integrations/sitemap/README.md

@@ -119,6 +119,27 @@ export default {
 
 The `page` function parameter is the full URL of your rendered page, including your `site` domain. Return `true` to include a page in your sitemap, and `false` to remove it.
 
+### customPages
+
+You may have custom routes to add to your sitemap. To append these to your sitemap, pass an array of valid URLs including the base origin:
+
+__astro.config.mjs__
+
+```js
+import sitemap from '@astrojs/sitemap';
+
+export default {
+  site: 'https://stargazers.club',
+  integrations: [
+    sitemap({
+      customPages: ['https://stargazers.biz/careers'],
+    }),
+  ],
+}
+```
+
+💡 You should also use `customPages` to manually list sitemap pages when using an SSR adapter. Currently, we cannot detect your site's pages unless you are building statically. To avoid an empty sitemap, list all pages (including the base origin) with this configuration option!
+
 ### canonicalURL
 
 If present, we use the `site` config option as the base for all sitemap URLs. Use `canonicalURL` to override this.

packages/integrations/sitemap/src/index.ts

@@ -99,7 +99,12 @@ const createPlugin = (options?: SitemapOptions): AstroIntegration => {
 					}
 
 					if (pageUrls.length === 0) {
-						logger.warn(`No data for sitemap.\n\`${OUTFILE}\` is not created.`);
+						// offer suggestion for SSR users
+						if (typeof config.adapter !== 'undefined') {
+							logger.warn(`No pages found! We can only detect sitemap routes for "static" projects. Since you are using an SSR adapter, we recommend manually listing your sitemap routes using the "customPages" integration option.\n\nExample: \`sitemap({ customPages: ['https://example.com/route'] })\``);
+						} else {
+							logger.warn(`No pages found!\n\`${OUTFILE}\` not created.`);
+						}
 						return;
 					}