astro-sitemap
Advanced tools
This Astro integration generates a sitemap.xml for your Astro project during build.
The sitemap.xml file provides information about structure of your website, about its content: pages, images, videos and relations between them. See Google's advice on sitemap to learn more.
The astro-sitemap integration does everything the official @astrojs/sitemap integration does but much more.
Advantages of astro-sitemap over @astrojs/sitemap:
lastmod format option;<head> section of generated pages.astro.config.* or a combination of both.Part of the functionality of astro-sitemap has become a minor update of the official integration @astrojs/sitemap from v0.1.2 to version 0.2.0.
Shared functionality with the official @astrojs/sitemap:
changefreq, lastmod, priority.:exclamation: Both official and astro-sitemap integrations don't support SSR.
:exclamation: This integration uses astro:build:done hook (the official @astrojs/sitemap does the same). This hook exposes only generated page paths. Thus, in the current version of Astro, both integrations don't have the ability to analyze the page source, frontmatter, etc. They can add changefreq, lastmod and priority attributes only in a batch or nothing.
The experimental astro add command-line tool automates the installation for you. Run one of the following commands in a new terminal window. (If you aren't sure which package manager you're using, run the first command.) Then, follow the prompts, and type "y" in the terminal (meaning "yes") for each one.
# Using NPM
npx astro add astro-sitemap
# Using Yarn
yarn astro add astro-sitemap
# Using PNPM
pnpx astro add astro-sitemap
Then, restart the dev server by typing CTRL-C and then npm run astro dev in the terminal window that was running Astro.
Because this command is new, it might not properly set things up. If that happens, log an issue on Astro GitHub and try the manual installation steps below.
First, install the astro-sitemap package using your package manager. If you're using npm or aren't sure, run this in the terminal:
npm install --save-dev astro-sitemap
Then, apply this integration to your astro.config.* file using the integrations property:
astro.config.mjs
import sitemap from 'astro-sitemap';
export default {
// ...
integrations: [sitemap()],
}
Then, restart the dev server.
The astro-sitemap integration requires a deployment / site URL for generation. Add your site's URL under your astro.config.* using the site property.
astro.config.mjs
import { defineConfig } from 'astro/config';
import sitemap from 'astro-sitemap';
export default defineConfig({
// ...
site: 'https://example.com',
integrations: [sitemap()],
});
Now, build your site for production via the astro build command. You should find your sitemap under dist/sitemap-index.xml and dist/sitemap-0.xml!
sitemap-index.xml
<?xml version="1.0" encoding="UTF-8"?>
<sitemapindex xmlns="http://www.sitemaps.org/schemas/sitemap/0.9">
<sitemap>
<loc>https://example.com/sitemap-0.xml</loc>
</sitemap>
</sitemapindex>
sitemap-0.xml
<?xml version="1.0" encoding="UTF-8"?>
<urlset xmlns="http://www.sitemaps.org/schemas/sitemap/0.9" xmlns:xhtml="http://www.w3.org/1999/xhtml">
<url>
<loc>https://example.com/</loc>
</url>
<url>
<loc>https://example.com/second-page/</loc>
</url>
</urlset>
All pages generated at build time will contain a link to the sitemap in the <head> section:
<link rel="sitemap" type="application/xml" href="/sitemap-index.xml">
To configure this integration, pass an object to the sitemap() function call in astro.config.mjs.
astro.config.mjs
...
export default defineConfig({
integrations: [sitemap({
filter: ...
})]
});
| Type | Required | Default value |
|---|---|---|
String | No | undefined |
Absolute URL. The integration needs canonicalURL or site from astro.config. If both values are provided, only canonicalURL will be used by the integration.
astro.config.mjs
import sitemap from 'astro-sitemap';
export default {
site: 'https://example.com',
integrations: [sitemap({
canonicalURL: 'https://another-domain.com',
})],
};
| Type | Required | Default value |
|---|---|---|
(page: String): Boolean | No | undefined |
Function to filter generated pages to exclude some paths from the sitemap.
astro.config.mjs
import sitemap from 'astro-sitemap';
export default {
site: 'https://example.com',
integrations: [sitemap({
filter(page) {
return !/exclude-this/.test(page);
},
})],
};
| Type | Required | Default value |
|---|---|---|
String[] | No | undefined |
The exclude option is an array of glob patterns to exclude static routes from the generated sitemap.
astro.config.mjs
import sitemap from 'astro-sitemap';
export default {
site: 'https://example.com',
integrations: [sitemap({
exclude: ['404', 'blog-*/'],
})],
};
| Type | Required | Default value |
|---|---|---|
String[] | No | undefined |
Absolute URL list. It will be merged with generated pages urls.
You should also use customPages to manually list sitemap pages when using an SSR adapter. Currently, integration 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.
astro.config.mjs
import sitemap from 'astro-sitemap';
export default {
site: 'https://example.com',
integrations: [sitemap({
customPages: [
'https://example.com/virtual-one.html',
'https://example.com/virtual-two.html',
],
})],
};
| Type | Required | Default value |
|---|---|---|
Number | No | 45000 |
Number of entries per one sitemap file.
The integration creates a separate sitemap-${i}.xml file for each batch of 45000 and adds this file to index - sitemap-index.xml.
See more on Google.
astro.config.mjs
import sitemap from 'astro-sitemap';
export default {
site: 'https://example.com',
integrations: [sitemap({
entryLimit: 10000,
})],
};
| Type | Required | Default value |
|---|---|---|
EnumChangeFreq | No | undefined |
This option corresponds to the <changefreq> tag in the Sitemap XML specification..
How frequently the page is likely to change.
Ignored by Google.
Available values:
export enum EnumChangefreq {
DAILY = 'daily',
MONTHLY = 'monthly',
ALWAYS = 'always',
HOURLY = 'hourly',
WEEKLY = 'weekly',
YEARLY = 'yearly',
NEVER = 'never',
}
astro.config.mjs
import sitemap from 'astro-sitemap';
export default {
site: 'https://example.com',
integrations: [sitemap({
changefreq: EnumChangeFreq.WEEKLY,
})],
};
| Type | Required | Default value |
|---|---|---|
Date | No | undefined |
This option corresponds to the <lastmod> tag in the Sitemap XML specification..
The date of page last modification.
astro.config.mjs
import sitemap from 'astro-sitemap';
export default {
site: 'https://example.com',
integrations: [sitemap({
lastmod: Date(),
})],
};
| Type | Required | Default value |
|---|---|---|
Number | No | undefined |
This option corresponds to the <priority> tag in the Sitemap XML specification..
The priority of this URL relative to other URLs on your site. Valid values range from 0.0 to 1.0.
Ignored by Google.
astro.config.mjs
import sitemap from 'astro-sitemap';
export default {
site: 'https://example.com',
integrations: [sitemap({
priority: 0.9,
})],
};
| Type | Required | Default value |
|---|---|---|
(item: SitemapItem): SitemapItemLoose | undefined | Promise< SitemapItemLoose |
Function to process an array of sitemap entries just before writing them to disk. Async or sync.
The undefined return value excludes the passed entry from the sitemap.
| Name | Type | Required | Description |
|---|---|---|---|
url | String | Yes | Absolute url |
changefreq | ChangeFreq | No | |
lastmod | String | No | ISO formatted date |
priority | Number | No | |
links | LinkItem[] | No | for localization |
| Name | Type | Required | Description |
|---|---|---|---|
url | String | Yes | Absolute URL |
lang | String | Yes | hreflag, example: 'en-US' |
The SitemapItemLoose interface is a base for the SitemapItem.
It has the properties video, img and many more.
More details about SitemapItemLoose interface see in the sitemap.js repo readme and types source code.
astro.config.mjs
import sitemap from 'astro-sitemap';
export default {
site: 'https://example.com',
integrations: [sitemap({
serialize(item) {
if (/exclude-this/.test(item.url)) {
return undefined;
}
if (/special-page/.test(item.url)) {
item.changefreq = 'daily';
item.lastmod = new Date();
item.priority = 0.9;
}
return item;
},
})],
};
| Type | Required | Default value |
|---|---|---|
String | No | undefined |
Absolute URL of XSL file to style XML or transform it to other format. Ignored by search engines.
astro.config.mjs
import sitemap from 'astro-sitemap';
export default {
site: 'https://example.com',
integrations: [sitemap({
xslUrl: 'https://example.com/style.xsl',
})],
};
Example of XML output
<?xml version="1.0" encoding="UTF-8"?>
<?xml-stylesheet type="text/xsl" href="https://example/style.xsl"?>
<urlset xmlns="http://www.sitemaps.org/schemas/sitemap/0.9" xmlns:xhtml="http://www.w3.org/1999/xhtml">
...
| Type | Required | Default value |
|---|---|---|
NSArgs | No | undefined |
Set the XML namespaces by xmlns attributes in <urlset> element.
| Name | Type | Required | Default | Description |
|---|---|---|---|---|
xhtml | Boolean | No | true | xmlns:xhtml="http://www.w3.org/1999/xhtml" |
news | Boolean | No | xmlns:news="http://www.google.com/schemas/sitemap-news/0.9" | |
video | Boolean | No | xmlns:video="http://www.google.com/schemas/sitemap-video/1.1" | |
image | Boolean | No | xmlns:image="http://www.google.com/schemas/sitemap-image/1.1" | |
custom | String[] | No | Any custom namespace. Elements of array'll be used as is without any validation. |
astro.config.mjs
import sitemap from 'astro-sitemap';
export default {
site: 'https://example.com',
integrations: [sitemap({
xmlns: {
xhtml: true,
news: true,
image: true,
video: true,
custom: [
'xsi:schemaLocation="http://www.sitemaps.org/schemas/sitemap/0.9 http://www.sitemaps.org/schemas/sitemap/0.9/sitemap.xsd"',
'xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"',
],
},
})],
};
Example of XML output
<?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" xsi:schemaLocation="http://www.sitemaps.org/schemas/sitemap/0.9 http://www.sitemaps.org/schemas/sitemap/0.9/sitemap.xsd" xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance">
...
| Type | Required | Default value |
|---|---|---|
Boolean | No | undefined |
If its value is true, the lastmod field in the XML output will contain a date part only.
astro.config.mjs
import sitemap from 'astro-sitemap';
export default {
site: 'https://example.com',
integrations: [sitemap({
lastmodDateOnly: true,
lastmod: Date(),
})],
};
| Type | Required | Default value |
|---|---|---|
Boolean | No | true |
Create a link on the sitemap in <head> section of generated pages.
The final output reprocessing is used for this. It can impact build time for large sites.
astro.config.mjs
import sitemap from 'astro-sitemap';
export default {
site: 'https://example.com',
integrations: [sitemap({
createLinkInHead: false,
})],
};
:bulb: See detailed explanation of sitemap specific options on sitemap.org.
Supply the integration config with the i18n option as an object with two required properties:
| Type | Required |
|---|---|
Record<String, String> | Yes |
Key/value - pairs. The key is used to look up the locale part of the page path. The value is a language attribute, only English alphabet and hyphen allowed.
See more on MDN.
| Type | Required |
|---|---|
String | Yes |
defaultLocale value must exist as one of the locales keys.
astro.config.mjs
import sitemap from 'astro-sitemap';
export default {
site: 'https://example.com',
integrations: [sitemap({
i18n: {
// All URLs that don't contain `es` or `fr` after `https://example.com/` will be treated as default locale, i.e. `en`
defaultLocale: 'en',
locales: {
en: 'en-US', // The `defaultLocale` value must present in `locales` keys
es: 'es-ES',
fr: 'fr-CA',
},
},
})],
};
Example of XML output
<?xml version="1.0" encoding="UTF-8"?>
<urlset xmlns="http://www.sitemaps.org/schemas/sitemap/0.9" xmlns:xhtml="http://www.w3.org/1999/xhtml">
<url>
<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://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://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://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>
...
</urlset>
You can configure the integration using the external file sitemap.config.* (js, cjs, mjs, ts). Put it in the application root folder (see about root in official docs).
The external config must contain the default export statement:
// ESM
export default {
...
};
or
// CommonJS
module.exports = {
...
};
How does the integration internally resolve a config?
| Options parameter provided? | External config exists? | Result |
|---|---|---|
| No | No | Default config used |
| Yes | No | Options parameter used |
| No | Yes | External config used |
| Yes | Yes | External config is merged with options parameter |
The external configuration usage example is in this demo repo.
| Example | Source | Playground |
|---|---|---|
| basic | GitHub | Play Online |
| advanced | GitHub | Play Online |
| i18n | GitHub | Play Online |
You're welcome to submit an issue or PR!
See CHANGELOG.md for a history of changes to this integration.
Module based on the awesome sitemap.js package ❤️.
FAQs
Generate a sitemap for Astro with more control
The npm package astro-sitemap receives a total of 225 weekly downloads. As such, astro-sitemap popularity was classified as not popular.
We found that astro-sitemap demonstrated a not healthy version release cadence and project activity because the last version was released a year ago. It has 1 open source maintainer collaborating on the project.
Did you know?
Socket for GitHub automatically highlights issues in each pull request and monitors the health of all your open source dependencies. Discover the contents of your packages and block harmful activity before you install or update your dependencies.
Security News
In this segment of the Risky Business podcast, Feross Aboukhadijeh and Patrick Gray discuss the challenges of tracking malware discovered in open source softare.
Research
Security News
A threat actor's playbook for exploiting the npm ecosystem was exposed on the dark web, detailing how to build a blockchain-powered botnet.
Security News
NVD’s backlog surpasses 20,000 CVEs as analysis slows and NIST announces new system updates to address ongoing delays.