xast-util-sitemap
!Buildbuild-badgebuild
!Coveragecoverage-badgecoverage
!Downloadsdownloads-badgedownloads
!Sizesize-badgesize
!Sponsorssponsors-badgecollective
!Backersbackers-badgecollective
!Chatchat-badgechatxast utility to build a
sitemap.xmlsitemap-site.Contents
* [`sitemap(data)`](#sitemapdata)
* [`Entry`](#entry)
* [`Alternate`](#alternate-1)What is this?
This package helps you build asitemap.xmlsitemap-site.
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 onlyesm. In Node.js (version 16+), install with npm:npm install xast-util-sitemapIn Deno with
esm.shesmsh:import {sitemap} from 'https://esm.sh/xast-util-sitemap@2'In browsers with
esm.shesmsh:<script type="module">
import {sitemap} from 'https://esm.sh/xast-util-sitemap@2?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 identifiersitemapapi-sitemap.
There is no default export.sitemap(data)
Build a sitemap.Parameters
data(Array<Entry | string>)
— entries to build a sitemap for
(see [`Entry`][api-entry], strings are equivalent to `{url: string}`)Returns
Sitemap (Rootroot).Entry
Entries represent a single URL and describe them with metadata (TypeScript
type).Fields
url
Full URL (<loc>loc; string, required, example: https://example.org/).modified
Value indicating when the page last changed (<lastmod>lastmod; Date or
value for new Date(x), optional).lang
BCP 47bcp47 tag indicating the language of the page (string, required w/
alternate, example: 'en-GB').alternate
Translations of the page, where each key is a BCP 47bcp47 tag and each
value an Alternateapi-alternate (Record<string, Alternate>, optional,
example: {nl: 'https://example.nl/'}).Alternate resources “inherit” fields (
modified) from the entry they are
described in.Alternate
Alternative content, typically a translation (TypeScript type).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/'}
}
]Type
type Alternate = Omit<Entry, 'alternate' | 'lang'> | stringTypes
This package is fully typed with TypeScript. It exports the additional typesAlternateapi-alternate and
Entryapi-entry.Compatibility
Projects maintained by the unified collective are compatible with maintained versions of Node.js.When we cut a new major release, we drop support for unmaintained versions of Node. This means we try to keep the current release line,
xast-util-sitemap@^2,
compatible with Node.js 16.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 thesitemap.xml file is also an ownerRelated
— serialize xast to XML— build feeds (RSS, Atom)— create xast treesContribute
Seecontributing.mdcontributing in syntax-tree/.githubhealth for
ways to get started.
See support.mdsupport for ways to get help.This project has a code of conductcoc. By interacting with this repository, organization, or community you agree to abide by its terms.
