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.
Some of functionality from astro-sitemap v0.2.2 became an update for the official integration @astrojs/sitemap from v0.1.2 to v0.2.0.
From now you can use the official integration in most cases.
Shared functionality with the official @astrojs/sitemap:
changefreq, lastmod, priority.astro-sitemap key extras:
lastmod format option;<head> section of generated pages.:exclamation: Both integrations, the official and astro-sitemap don't support SSR.
There are two ways to add astro-sitemap integration to your Astro project.
You should run astro add command in your project directory. This command after prompt will install required dependencies and apply changes to astro.config.*.
# Using NPM
npx astro add astro-sitemap
# Using Yarn
yarn astro add astro-sitemap
# Using PNPM
pnpx astro add astro-sitemap
If you run into any troubles, feel free to log an issue on my GitHub.
First, install the astro-sitemap integration like so:
# Using NPM
npm install --save-dev astro-sitemap
# Using Yarn
yarn add -D astro-sitemap
# Using PNPM
pnpm add -D astro-sitemap
Then apply this integration to your astro.config.*. All details below in Getting started.
The astro-sitemap integration requires a deployment / site URL for generation. Add your site's URL under your astro.config.* using the site property.
:exclamation: Provide the experimental property to your astro.config.*, because only official @astrojs/* integrations are currently supported by Astro. Set the experimental.integrations value to true.
Then, apply this integration to your astro.config.* file using the integrations property.
astro.config.mjs
// astro.config.mjs
import { defineConfig } from 'astro/config';
import sitemap from 'astro-sitemap';
export default defineConfig({
// ...
site: 'https://example.com',
// Important!
// Only official '@astrojs/*' integrations are currently supported by Astro.
// Add 'experimental.integrations: true' to make 'astro-sitemap' working
// with 'astro build' command.
experimental: {
integrations: true,
},
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!
Generated sitemap content for two pages website:
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 during build will contain in <head> section a link to sitemap:
<link rel="sitemap" type="application/xml" href="/sitemap-index.xml">
You can also check Astro Integration Documentation for more on integrations.
| Name | Type | Required | Default | Description |
|---|---|---|---|---|
filter | (page: String):Boolean | No | Function to filter generated pages to exclude some paths from a sitemap. | |
customPages | String[] | No | 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! | |
canonicalURL | String | No | Absolute URL. The integration needs site from astro.config or canonicalURL. If both values are provided then only canonicalURL will be used by the integration. | |
entryLimit | Number | No | 45000 | Number of entries per sitemap file, a sitemap index and multiple sitemaps are created if you have more entries. See more on Google |
changefreq | ChangeFreq | No | Sitemap specific. Ignored by Google. How frequently the page is likely to change. Available values: always|hourly|daily|weekly|monthly| yearly|never | |
lastmod | Date | No | Sitemap specific. The date of page last modification. | |
priority | Number | No | Sitemap specific. Ignored by Google. The priority of this URL relative to other URLs on your site. Valid values range from 0.0 to 1.0 | |
serialize | (item: SitemapItem):SitemapItemLoose|undefined|Promise< SitemapItemLoose|undefined> | No | Function to process an array of sitemap entries just before writing them to disk. Async or sync. Modified behavior compared to the official integration: undefined return value excludes the passed entry from sitemap. |
| i18n | object | No | | |
| defaultLocale| String | Yes | | Its value has to be exist as one the locales keys. |
| locales | Record<String, String> | Yes | | 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. See more on MDN |
:bulb: See detailed explanation of sitemap specific options on sitemap.org.
:exclamation: This integration uses 'astro:build:done' hook (official @astrojs/sitemap does the same). The hook exposes only generated page paths. So with present version of Astro the integration has no abilities to analyze a page source, frontmatter etc. The integration can add changefreq, lastmod and priority attributes only in a batch or nothing.
| 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' |
| Name | Type | Required | Default | Description |
|---|---|---|---|---|
exclude | String[] | No | The exclude option is an array of glob patterns to exclude static routes from the generated sitemap. | |
xslUrl | String | No | Absolute URL of XSL file to style XML or transform it to other format. Ignored by search engines. | |
xmlns | NSArgs | No | Set the XML namespaces by xmlns attributes in <urlset> element. | |
lastmodDateOnly | Boolean | No | If it's true the XML output will contain a date part only. | |
createLinkInHead | Boolean | No | true | Create a link on the sitemap in <head> of generated pages.The final output reprocessing is used for this. It could impact on a build time for large sites. |
| 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. |
The SitemapItemLoose interface is a base for the SitemapItem.
It has properties video, img and many others.
More details about SitemapItemLoose interface see in the sitemap.js repo readme and types source code.
Sample of astro.config.mjs
// astro.config.ts
import { defineConfig } from 'astro/config';
import sitemap from 'astro-sitemap';
export default defineConfig({
site: 'https://your-awesome-site.com',
experimental: {
integrations: true,
},
integrations: [
sitemap({
/**
* These options are the same with the official integration `@astrojs/sitemap`
*/
// exclude pages from sitemap
filter: (page: string) => !/exclude-this/.test(page),
// Absolute urls of extra pages
customPages: [
// extra pages for sitemap
'https://example.com/virtual-one.html',
'https://example.com/virtual-two.html',
],
// Here the `canonicalURL` is provided.
// It will be used during sitemap generation instead of `site` value.
canonicalURL: 'https://example.com',
// This function is called just before a sitemap writing to disk.
// You have more control on resulting output.
// sync or async
serialize(item: SitemapItem): SitemapItem {
if (/special-page/.test(item.url)) {
item.changefreq = 'daily';
item.lastmod = new Date();
item.priority = 0.9;
}
return item;
},
// The integration creates a separate `sitemap-${i}.xml` file for each batch of 45000 and adds this file to index - `sitemap-index.xml`.
entryLimit: 1000, // default - 45000
// sitemap specific
changefreq: 'yearly',
lastmod: new Date('May 01, 2019 03:24:00'),
priority: 0.2,
/**
* `astro-sitemap` integration extra options
*/
exclude: ['404', 'blog-*/']
// print date not time
lastmodDateOnly: false,
// style to transform to another format, ignored by search engines
xslUrl: 'https://example.com/style.xsl',
// set the xml namespace
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"',
],
},
// Create or not a link to sitemap in '<head>' section of generated pages
createLinkInHead: true, // default - true
}),
],
});
Generated sitemap content for this configuration:
<?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: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">
...
<url>
<loc>https://example.com/</loc>
<lastmod>2019-05-01</lastmod>
<changefreq>yearly</changefreq>
<priority>0.2</priority>
</url>
...
<url>
<loc>https://example.com/virtual-one.html</loc>
<lastmod>2019-05-01</lastmod>
<changefreq>yearly</changefreq>
<priority>0.2</priority>
</url>
...
<url>
<loc>https://example.com/some-special-path.html</loc>
<lastmod>2022-06-07</lastmod>
<changefreq>daily</changefreq>
<priority>0.9</priority>
</url>
...
Supply the integration config with the i18n options. The integration will check generated page paths on presence of locale keys in paths.
Read more about localization on Google in Advanced SEO.
Let's have the following integration config:
...
canonicalURL: 'https://example.com', // You could provide the `site` option in astro.config instead of `canonicalURL`.
i18n: {
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',
fr: 'fr-CA',
}
}
...
The sitemap content will be:
...
<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>
...
You could configure the integration with external file sitemap.config.* (js, cjs, mjs). Put it to the application root folder (see about root in official docs).
The external config must contain a default export statement:
// ESM
export default {
...
};
or
// CommonJS
module.exports = {
...
};
:exclamation: The current version of integration doesn't support typescript configs.
| 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.
:exclamation: Important Notes
Only official @astrojs/* integrations are currently supported by Astro.
There are two possibilities to make astro-sitemap integration working with current version of Astro.
Set the experimental.integrations option to true in your astro.config.*.
// astro.config.mjs
export default defineConfig({
// ...
experimental: {
integrations: true,
},
});
Or use the --experimental-integrations flag for build command.
astro build --experimental-integrations
Module based on the awesome sitemap.js package ❤️.
FAQs
Generate a sitemap for Astro with more control
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
MITRE's 2024 CWE Top 25 highlights critical software vulnerabilities like XSS, SQL Injection, and CSRF, reflecting shifts due to a refined ranking methodology.
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.