Skip to content

fix(sitemap): add API references to config options #12304

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 4 commits into from
Sep 12, 2025
Merged

fix(sitemap): add API references to config options #12304

Changes from 2 commits
Commits
Show all changes
4 commits
Select commit Hold shift + click to select a range
2feaee1
fix(integrations-guide/sitemap): add API references on Configuration
ArmandPhilippot Sep 11, 2025
4730406
move read more links inside text
ArmandPhilippot Sep 11, 2025
228cfdc
fix: use backticks around config options headings
ArmandPhilippot Sep 12, 2025
f1b6335
Merge branch 'main' into fix/integrations-guide/sitemap-add-api-refer…
ArmandPhilippot Sep 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
53 changes: 47 additions & 6 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 @@ -195,6 +195,11 @@ export default defineConfig({

### filter

<p>

**Type:** `(page: string) => boolean`
</p>

All pages are included in your sitemap by default. By adding a custom `filter` function, you can filter included pages by URL.

```js title="astro.config.mjs" ins={8}
Expand Down Expand Up @@ -235,6 +240,11 @@ export default defineConfig({

### customPages

<p>

**Type:** `string[]`
</p>

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.
Expand Down Expand Up @@ -282,6 +292,12 @@ export default defineConfig({

### entryLimit

<p>

**Type:** `number`<br />
**Default:** `45000`
</p>

The maximum number entries per sitemap file. The default value is 45000. A sitemap index and multiple sitemaps are created if you have more entries. See this [explanation of splitting up a large sitemap](https://developers.google.com/search/docs/advanced/sitemaps/large-sitemaps).

```js title="astro.config.mjs" ins={8}
Expand All @@ -300,6 +316,12 @@ export default defineConfig({

### changefreq, lastmod, and priority

<p>

**Type:** `{ changefreq?: ChangeFreq; lastmod?: Date; priority?: number; }`
<Since v="0.2.0" pkg="@astrojs/sitemap" />
</p>

These options correspond to the `<changefreq>`, `<lastmod>`, and `<priority>` tags in the [Sitemap XML specification.](https://www.sitemaps.org/protocol.html)

Note that `changefreq` and `priority` are ignored by Google.
Expand All @@ -326,6 +348,11 @@ export default defineConfig({

### serialize

<p>

**Type:** `(item: SitemapItem) => SitemapItem | Promise<SitemapItem | undefined> | undefined`
</p>

A function called for each sitemap entry just before writing to a disk. This function can be asynchronous.

It receives as its parameter a `SitemapItem` object that can have these properties:
Expand Down Expand Up @@ -370,16 +397,17 @@ export default defineConfig({

### i18n

To localize a sitemap, pass an object to this `i18n` option.
<p>

This object has two required properties:
**Type:** `{ defaultLocale: string; locales: Record<string, string>; }`
</p>

* `defaultLocale`: `String`. Its value must exist as one of `locales` keys.
* `locales`: `Record<String, String>`, key/value - pairs. The key is used to look for a locale part in a page path. The value is a language attribute, only English alphabet and hyphen allowed.
To [localize a sitemap](https://developers.google.com/search/docs/advanced/crawling/localized-versions#all-method-guidelines), pass an object to this `i18n` option.

[Read more about language attributes](https://developer.mozilla.org/en-US/docs/Web/HTML/Global_attributes/lang).
This object has two required properties:

[Read more about localization](https://developers.google.com/search/docs/advanced/crawling/localized-versions#all-method-guidelines).
* `defaultLocale`: Its value must exist as one of `locales` keys.
* `locales`: key/value - pairs. The key is used to look for a locale part in a page path. The value is a [language attribute](https://developer.mozilla.org/en-US/docs/Web/HTML/Global_attributes/lang), only English alphabet and hyphen allowed.

```js title="astro.config.mjs" ins={8-15}
import { defineConfig } from 'astro/config';
Expand Down Expand Up @@ -435,6 +463,12 @@ The resulting sitemap looks like this:

### xslURL

<p>

**Type:** `string`<br />
<Since v="3.2.0" pkg="@astrojs/sitemap" />
</p>

The URL of an XSL stylesheet to style and prettify your sitemap.

The value set can be either a path relative to your configured `site` URL for a local stylesheet, or can be an absolute URL link to an external stylesheet.
Expand All @@ -455,6 +489,13 @@ export default defineConfig({

### filenameBase

<p>

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

The name prefix string used when generating the sitemap XML files. The default value is `sitemap`.

This option may be useful when integrating an Astro site into a domain with preexisting sitemap files.
Expand Down