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.
There is already the official integration @astrojs/sitemap which works excellent.
For what another one?
The official integration has a functionality which is not enough in some cases.
Key benefits of astro-sitemap integration:
changefreq, lastmod, priority.<head> section of generated pages.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: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://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):<br/>Boolean | No | undefined | The same as official. Function to filter generated pages to exclude some paths from a sitemap |
customPages | String[] | No | undefined | The same as official. Absolute url list. It will be merged with generated pages urls. |
canonicalURL | String | No | undefined | The same as official. Absolute url. The integration needs site from astro.config or canonicalURL. If both provided only canonicalURL will be used. |
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 |
createLinkInHead | Boolean | No | true | Create a link on the sitemap in <head> of generated pages. |
serialize | (item: SitemapItem):<br />SitemapItem | No | undefined | Function to process an array of SiteMap items just before writing to disk. Async or sync. |
changefreq | ChangeFreq | No | undefined | 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 | undefined | Sitemap specific. The date of page last modification. |
priority | Number | No | undefined | 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 |
| i18n | object | No | undefined | Provide this object to start |
defaultLocale | String | Yes | Its value has to be exists as one of 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 | Date | No | |
priority | Number | No | |
links | LinkItem[] | No | for localization |
| Name | Type | Required | Description |
|---|---|---|---|
url | String | Yes | Absolute url |
lang | String | Yes | example 'en' |
hreflang | String | No | example 'en-us' |
Sample of astro.config.mjs
// astro.config.ts
import { defineConfig } from 'astro/config';
import sitemap from 'astro-sitemap';
export default defineConfig({
site: 'https://example.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), // default - undefined
// Absolute urls of extra pages
customPages: [ // default - undefined
// extra pages for sitemap
'https://sample.com/virtual-one.html',
'https://sample.com/virtual-two.html',
],
// if `canonicalURL` is provided it will be used instead of `site` value
canonicalURL: 'https://sample.com', // default - undefined
/**
* `astro-sitemap` integration options
*/
// This function is called just before a sitemap writing to disk.
// You have more control on resulting output.
// async supported.
serialize(item: SitemapItem): SitemapItem { // default - undefined
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: 10000, // default - 45000
// Create or not a link to sitemap in '<head>' section of generated pages
createLinkInHead: true, // default - true
// sitemap specific
changefreq: 'yearly', // default - undefined
lastmod: new Date('May 01, 2019 03:24:00'), // default - undefined
priority: 0.2, // default - undefined
}),
],
});
Generated sitemap content for this configuration:
...
<url>
<loc>https://example.com/</loc>
<lastmod>2019-05-01T03:24:00.000Z</lastmod>
<changefreq>yearly</changefreq>
<priority>0.2</priority>
</url>
...
<url>
<loc>https://example.com/virtual-one.html</loc>
<lastmod>2019-05-01T03:24:00.000Z</lastmod>
<changefreq>yearly</changefreq>
<priority>0.2</priority>
</url>
...
<url>
<loc>https://example.com/some-special-path.html</loc>
<lastmod>2022-06-07T13:34:35.096Z</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
The astro-sitemap is based on the official integration @astrojs/sitemap. Many thanks to the Astro team for their work!
FAQs
Generate a sitemap for Astro with more control
The npm package astro-sitemap receives a total of 261 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
A Stanford study reveals 9.5% of engineers contribute almost nothing, costing tech $90B annually, with remote work fueling the rise of "ghost engineers."
Research
Security News
Socket’s threat research team has detected six malicious npm packages typosquatting popular libraries to insert SSH backdoors.
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.