Huge News!Announcing our $40M Series B led by Abstract Ventures.Learn More →
Socket
Sign inDemoInstall
Socket
Sign inDemoInstall

astro-sitemap

Package Overview
Dependencies
Maintainers
1
Versions
19
Alerts
File Explorer

Advanced tools

License
Socket logo

Install Socket

Detect and block malicious and high-risk dependencies

Install

astro-sitemap

Generate a sitemap for Astro with more control

  • 0.5.1
  • Source
  • npm
  • Socket score
Version published
Weekly downloads
271
decreased by-24.72%
Maintainers
1
Weekly downloads
 
Created
Source

Help Ukraine now!

astro-sitemap

This Astro integration generates a sitemap.xml for your Astro project during build.

Release License: MIT

Why astro-sitemap?

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:

  • Exclude pages from a sitemap by glob patterns.
  • More control on the sitemap output:
    • manage XML namespaces;
    • lastmod format option;
    • possibility to add a link to custom XSL.
  • Automatically creates a link to the sitemap in the <head> section of generated pages.
  • Flexible configuration: configure the integration with an external config, astro.config.* or a combination of both.
  • Better logging.

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:

  • Split up your large sitemap into multiple sitemaps by a custom limit.
  • Ability to add sitemap specific attributes such as changefreq, lastmod, priority.
  • Final output customization via JS function (sync or async).
  • Localization support. In a build time the integration analyses the pages urls for presence of locale signatures in paths to establish relations between pages.
  • Reliability: all config options are validated.

: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.

Installation

Quick Install

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.

Manual Install

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.

Usage

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!

Example of generated sitemap content

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>
Example of inserted HTML

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">

Configuration

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: ...
  })]
});
canonicalURL
TypeRequiredDefault value
StringNoundefined

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',
  })],
};
filter
TypeRequiredDefault value
(page: String): BooleanNoundefined

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);
    },
  })],
};
exclude
TypeRequiredDefault value
String[]Noundefined

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-*/'],
  })],
};
customPages
TypeRequiredDefault value
String[]Noundefined

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',
    ],
  })],
};
entryLimit
TypeRequiredDefault value
NumberNo45000

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,
  })],
};
changefreq
TypeRequiredDefault value
EnumChangeFreqNoundefined

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,
  })],
};
lastmod
TypeRequiredDefault value
DateNoundefined

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(),
  })],
};
priority
TypeRequiredDefault value
NumberNoundefined

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,
  })],
};
serialize
TypeRequiredDefault value
(item: SitemapItem): SitemapItemLooseundefined
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.

Type `SitemapItem`*
NameTypeRequiredDescription
urlStringYesAbsolute url
changefreqChangeFreqNo
lastmodStringNoISO formatted date
priorityNumberNo
linksLinkItem[]Nofor localization
Type `LinkItem`
NameTypeRequiredDescription
urlStringYesAbsolute URL
langStringYeshreflag, example: 'en-US'
Interface `SitemapItemLoose`

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;
    },
  })],
};
xslUrl
TypeRequiredDefault value
StringNoundefined

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">
...
xmlns
TypeRequiredDefault value
NSArgsNoundefined

Set the XML namespaces by xmlns attributes in <urlset> element.

Interface `NSArgs`
NameTypeRequiredDefaultDescription
xhtmlBooleanNotruexmlns:xhtml="http://www.w3.org/1999/xhtml"
newsBooleanNoxmlns:news="http://www.google.com/schemas/sitemap-news/0.9"
videoBooleanNoxmlns:video="http://www.google.com/schemas/sitemap-video/1.1"
imageBooleanNoxmlns:image="http://www.google.com/schemas/sitemap-image/1.1"
customString[]NoAny 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">
...
lastmodDateOnly
TypeRequiredDefault value
BooleanNoundefined

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(),
  })],
};
createLinkInHead
TypeRequiredDefault value
BooleanNotrue

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.

Localization

Supply the integration config with the i18n option as an object with two required properties:

locales
TypeRequired
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.

defaultLocale
TypeRequired
StringYes

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>

External config file

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
NoNoDefault config used
YesNoOptions parameter used
NoYesExternal config used
YesYesExternal config is merged with options parameter

The external configuration usage example is in this demo repo.

Examples

ExampleSourcePlayground
basicGitHubPlay Online
advancedGitHubPlay Online
i18nGitHubPlay Online

Contributing

You're welcome to submit an issue or PR!

Changelog

See CHANGELOG.md for a history of changes to this integration.

Inspiration

Module based on the awesome sitemap.js package ❤️.

Keywords

FAQs

Package last updated on 22 Mar 2023

Did you know?

Socket

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.

Install

Related posts

Risky Business Podcast: Why Open Source Software Needs Better Malware Tracking

Security News

Risky Business Podcast: Why Open Source Software Needs Better Malware Tracking

In this segment of the Risky Business podcast, Feross Aboukhadijeh and Patrick Gray discuss the challenges of tracking malware discovered in open source softare.

By Sarah Gooding  -  Nov 20, 2024
SocketSocket SOC 2 Logo

Product

  • Package Alerts
  • Integrations
  • Docs
  • Pricing
  • FAQ
  • Roadmap
  • Changelog

About

Packages

npm

Go

Maven

PyPI

Rubygems

Stay in touch

Get open source security insights delivered straight into your inbox.

  • Terms
  • Privacy
  • Security

Made with ⚡️ by Socket Inc