unified

Project: syntax-tree/xast-util-sitemap

Package: xast-util-sitemap@1.3.0

  1. Dependents: 0
  2. xast utility to build a sitemap
  1. util 147
  2. utility 143
  3. unist 131
  4. xml 10
  5. xast 8
  6. xast-util 7

xast-util-sitemap

Build Coverage Downloads Size Sponsors Backers Chat

xast utility to build a sitemap.xml.

Contents

What is this?

This package helps you build a sitemap.xml. It supports localization as suggested by Google.

When should I use this?

This package focusses on a small set of widely used parts of sitemaps. It has a few good options instead of overwhelming with everything that could be done. If you do need more things, well: this utility gives you a syntax tree, which you can change.

This proejct is intended for sites with up to 50k URLs and a resulting serialized contents of up to 50MB. Wrapping this project into something that generates sitemap index files is left as an exercise to the reader.

You don’t always need a sitemap. See Google’s recommendations for whether you need a sitemap

You should place sitemaps in the root of your site and reference them in robots.txt. You might also report sitemap changes to Google.

Install

This package is ESM only. In Node.js (version 12.20+, 14.14+, 16.0+, or 18.0+), install with npm:

npm install xast-util-sitemap

In Deno with esm.sh:

import {sitemap} from 'https://esm.sh/xast-util-sitemap@1'

In browsers with esm.sh:

<script type="module">
  import {sitemap} from 'https://esm.sh/xast-util-sitemap@1?bundle'
</script>

Use

import {sitemap} from 'xast-util-sitemap'
import {toXml} from 'xast-util-to-xml'

const tree = sitemap([
  'https://example.com/alpha/',
  {url: 'https://example.com/bravo/'},
  {url: 'https://example.com/charlie/', modified: new Date(2018, 1, 2, 3)},
  {
    url: 'https://example.com/delta/',
    lang: 'en',
    alternate: {
      nl: 'https://example.com/dirk/',
      'fr-BE': 'https://example.com/désiré/'
    }
  }
])

console.log(toXml(tree))

Yields (pretty printed):

<?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/alpha/</loc>
  </url>
  <url>
    <loc>https://example.com/bravo/</loc>
  </url>
  <url>
    <loc>https://example.com/charlie/</loc>
    <lastmod>2018-02-02T02:00:00.000Z</lastmod>
  </url>
  <url>
    <loc>https://example.com/delta/</loc>
    <xhtml:link rel="alternate" hreflang="en" href="https://example.com/delta/" />
    <xhtml:link rel="alternate" hreflang="nl" href="https://example.com/dirk/" />
    <xhtml:link rel="alternate" hreflang="fr-BE" href="https://example.com/d%C3%A9sir%C3%A9/" />
  </url>
  <url>
    <loc>https://example.com/dirk/</loc>
    <xhtml:link rel="alternate" hreflang="en" href="https://example.com/delta/" />
    <xhtml:link rel="alternate" hreflang="nl" href="https://example.com/dirk/" />
    <xhtml:link rel="alternate" hreflang="fr-BE" href="https://example.com/d%C3%A9sir%C3%A9/" />
  </url>
  <url>
    <loc>https://example.com/d%C3%A9sir%C3%A9/</loc>
    <xhtml:link rel="alternate" hreflang="en" href="https://example.com/delta/" />
    <xhtml:link rel="alternate" hreflang="nl" href="https://example.com/dirk/" />
    <xhtml:link rel="alternate" hreflang="fr-BE" href="https://example.com/d%C3%A9sir%C3%A9/" />
  </url>
</urlset>

API

This package exports the identifier sitemap. There is no default export.

sitemap(data)

Build a sitemap.

data

URLs to build a sitemap for. data is an Array<url | Entry>. url is string and equivalent to an {url: url} entry.

Returns

xast root (Root).

Entry

Entries represent a single URL and describe them with metadata.

entry.url

Full URL (<loc>; string, required, example: https://example.org/)

entry.modified

Value indicating when the page last changed (<lastmod>; Date or value for new Date(x), optional).

entry.lang

BCP 47 tag indicating the language of the page (string, required w/ alternate, example: 'en-GB').

entry.alternate

Translations of the page, where each key is a BCP 47 tag and each value an entry (Record<string, url | Entry>, optional, example: {nl: 'https://example.nl/'}).

Alternate resources “inherit” fields (modified) from the entry they are described in. To define different fields, either use a full entry object:

[
  {
    url: 'https://example.com/delta/',
    modified: '05 October 2011 14:48 UTC',
    lang: 'en',
    alternate: {nl: {url: 'https://example.com/dirk/', modified: '20 January 2020 00:00 UTC'}}
  }
]

Or define them separately:

[
  {
    url: 'https://example.com/delta/',
    modified: '05 October 2011 14:48 UTC',
    lang: 'en',
    alternate: {nl: 'https://example.com/dirk/'}
  },
  {
    url: 'https://example.com/dirk/',
    modified: '20 January 2020 00:00 UTC',
    // `xast-util-sitemap` is smart enough to know about the next two already,
    // but they’re shown here for clarity.
    lang: 'nl',
    alternate: {en: 'https://example.com/delta/'}
  }
]

Types

This package is fully typed with TypeScript. It exports the additional types Alternate and Entry.

Compatibility

Projects maintained by the unified collective are compatible with all maintained versions of Node.js. As of now, that is Node.js 12.20+, 14.14+, 16.0+, and 18.0+. Our projects sometimes work with older versions, but this is not guaranteed.

Security

XML can be a dangerous language: don’t trust user-provided data. Sitemaps also indicate “ownership” of URLs: crawlers assume that the origin of the sitemap.xml file is also an owner

Contribute

See contributing.md in syntax-tree/.github for ways to get started. See support.md for ways to get help.

This project has a code of conduct. By interacting with this repository, organization, or community you agree to abide by its terms.

License

MIT © Titus Wormer