astro-sitemap

v1.0.0

Published

8 months ago

Generate a sitemap for Astro with more control

Downloads

834

0High
0Medium
0Low

alextim

astro-integration astro astro-component seo sitemap sitemap.xml i18n

astro-sitemap

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

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

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.

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!

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

Configuration

To configure this integration, pass an object to the sitemap() function call in astro.config.mjs.

:bulb: For this integration to work correctly, it is recommended to use the mjs or js configuration file extensions.

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,
  })],
};

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

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.

Localization

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>

Examples

| Example | Source | Playground | | ------------- | -------------------------------------------------------------------------------------- | ----------------------------------------------------------------------------------------------------------- | | basic | GitHub | Play Online | | advanced | GitHub | Play Online | | i18n | GitHub | Play 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 ❤️.

Published

Vulnerabilities

Links

Maintainers

Keywords

Readme

astro-sitemap

Why astro-sitemap?

Installation

Usage

Configuration

Localization

Examples

Contributing

Changelog

Inspiration