xml-sitemap

Utilities for quickly making custom XML sitemaps

Table of Contents

• Install
• Usage
  • Build a sitemap from scratch
  • Setting a host
  • Updating and reading sitemap info
  • Editing an existing sitemap
  • Set lastmod values from files
• API
• Licence

Install

Add it to a project with npm:

$ npm install xml-sitemap --save

Then just require it in your project:

var XmlSitemap = require('xml-sitemap');
var sitemap = new XmlSitemap();

Usage

For more info on anything check out the docs.

Build a sitemap from scratch

All methods that don't return values return the sitemap, so you can chain them all together.

var sitemap = new XmlSitemap();

// add some urls
sitemap.add('http://domain.com/')

  .add('http://domain.com/another-page', {
    lastmod: 'now',
    priority: 0.8
  })

  .add({
    url: 'http://domain.com/sitemapz-rule',
    changefreq: 'never',
    lastmod: '1999-12-31'
  });

We could have made the same sitemap with a single array:

var sitemap = new XmlSitemap()
  .add([
    'http://domain.com/',
    {
      url: 'http://domain.com/another-page',
      lastmod: 'now',
      priority: 0.8
    },
    {
      loc: 'http://domain.com/sitemapz-rule',
      changefreq: 'never',
      lastmod: '1999-12-31'
    }
  ]);

Setting a host

Setting a host with .setHost(url) allows for all methods to accept relative links. .setHost accepts a string or an object with options. Building the above with a host set:

var sitemap = new XmlSitemap()
  .setHost('http://domain.com/')    // allows relative links, automatically adds host url
  .add([
    {
      url: '/another-page',
      lastmod: 'now',
      priority: 0.8
    },
    {
      loc: '/sitemapz-rule',
      changefreq: 'never',
      lastmod: '1999-12-31'
    }
  ]);

Updating and reading sitemap info

Update and read some info from the sitemap we built above:

// update some values
sitemap.update('http://domain.com/', new Date())
  .setOptionValue('http://domain.com/sitemapz-rule', 'priority', 1);

// an array of the urls is in sitemap.urls
sitemap.urls
//=> [ 'http://domain.com/', 'http://domain.com/magic', 'http://domain.com/another-page', 'http://domain.com/sitemapz-rule' ]

// and the xml is in sitemap.xml
require('fs').writeFileSync('sitemap.xml', sitemap.xml);

// we can also read info from the sitemap
sitemap.hasUrl('http://domain.com/another-page');
//=> true

sitemap.getOptionValue('http://domain.com/', 'lastmod');
//=> {today's date!}

sitemap.getOptionValue('http://domain.com/magic', 'lastmod');
//=> {today's date!}

sitemap.getOptionValue('http://domain.com/another-page', 'lastmod');
//=> null

Editing an existing sitemap

We can read in an existing sitemap (like the one we made above!) and modify it on the fly.

// get the XML as a string
var xmlString = require('fs').readFileSync('sitemap.xml');
// and pass it to the constructor
var sitemap = new XmlSitemap(xmlString)
  .setHost('http://domain.com/');

sitemap.hasUrl('/magic');
//=> true

// modify it
sitemap.remove('/another-page')
  .setOptionValues('/magic', {
    lastmod: '2012-12-21',
    priority: 0.9
  });

sitemap.hasUrl('/another-page');
//=> false
sitemap.getOptionValue('/magic', 'priority');
//=> '0.9'

// quickly update lastmod vlaues
sitemap.getOptionValue('/magic', 'lastmod');
//=> '2012-12-21'

sitemap.update('/magic');
sitemap.getOptionValue('/magic', 'lastmod');
//=> {today's date}

Set lastmod values from files

For easily updating a url's lastmod, we can link a file to it. Here are a few ways to link the file:

var filename = 'path/to/file.html'; // last modified on '2012-12-21'

// link by adding a filename to the 'file' key to its options when adding it
sitemap.add({
  url: 'http://domain.com/',
  file: filename
});

// or after it is already in the sitemap
sitemap.linkFile('http://domain.com/', filename);

// the lastmod has been updated accordingly in both cases
sitemap.getOptionValue('http://domain.com/', 'lastmod');
//=> '2012-12-21'

// linked files are listed in sitemap.files
sitemap.files
//=> {'http://domain.com/': 'path/to/file.html'}

Linked files automatically update the lastmod of their respective urls when updateAll() is called. So you can link many files to urls already in the sitemap by assigning the files object and then updating all.

sitemap.files = {
  url1: filename1,
  url2: filename2,
  ...
};
sitemap.updateAll();

To update a lastmod from a file without linking it, use sitemap.updateFromFile(url, filepath). Unlink a file with sitemap.unlinkFile(url).

API

Read the full documentation on the API here.

Licence

MIT © 2016 Robert Pirtle