assemble / assemble-sitemap

Assemble pipeline plugin for generating sitemaps for one or more collections.

assemble-sitemaps

Assemble pipeline plugin for generating one or more sitemaps, for one more more collections, to one or more destination paths.

• Install
• Usage
• Docs
  • Defining sitemap data
  • Sitemap tags
  • Generate a sitemap
  • Set the destination
  • Sitemap for a specific collection
  • Sitemap for multiple collections
  • Multiple sitemaps
• FAQ
• Release history
  • v1.0.0 - 2017/07/20
• About

(TOC generated by verb using markdown-toc)

Install

Install with npm:

$ npm install --save assemble-sitemaps

Usage

var sitemap = require('assemble-sitemaps');
var assemble = require('assemble');
var app = assemble();

// register the plugin
app.use(sitemap());

This library uses handlebars-helper-sitemap to generate the actual sitemaps, you can use that helper directly if you need to do something different than this plugin. See that lib for more details.

Docs

Generates sitemaps like the following.

<?xml version="1.0" encoding="UTF-8"?>
<urlset xmlns="http://www.sitemaps.org/schemas/sitemap/0.9">
  <url>
    <loc>https://breakdance.io/index.html</loc>
    <lastmod>2017-02-11</lastmod>
    <changefreq>daily</changefreq>
    <priority>0.8</priority>
  </url>
  <url>
    <loc>https://breakdance.io/docs.html</loc>
    <lastmod>2017-02-02</lastmod>
    <changefreq>daily</changefreq>
    <priority>0.8</priority>
  </url>
  <url>
    <loc>https://breakdance.io/about.html</loc>
    <lastmod>2017-02-02</lastmod>
    <changefreq>daily</changefreq>
    <priority>0.8</priority>
  </url>
</urlset>

Defining sitemap data

Global data

The only required value is sitemap.url, which will be prefixed to all of the relative paths for each <loc> tag:

app.data('sitemap.url', 'https://breakdance.io');

Item data

An item is represents a single URL in the sitemap (since you might be generating a sitemap that includes multiple collections, like "pages" and "posts", item is used to avoid ambiguity.

You can set item.data using yaml-front matter, or using any gulp or assemble plugin that does this, or an assemble middleware. Example:

app.onLoad(/\.md$/, function(file, next) {
  file.data.sitemap = file.data.sitemap || {};
  if (file.stem === 'index') {
    file.data.sitemap.priority = '1.0';
  } else {
    file.data.sitemap.priority = '0.5';
  }
  next();
});

Sitemap tags

The following tags are generated using the global sitemap data and/or the item.data for each file in the sitemap:

| Tag | Description | | <lastmod> | the date of last modification of the file. See the FAQ section for more details about <lastmod> | | <loc> | URL of the page. This URL must begin with the protocol (such as http) and end with a trailing slash, if your web server requires it. This value must be less than 2,048 characters. | | <changefreq> | How frequently the page is likely to change. | | <priority> | The priority of this URL relative to other URLs on your site. |

See the sitemaps protocol documentation for more information about these tags.

Generate a sitemap

Automatically generates a sitemap for the files in the current stream:

app.task('blog', function() {
  app.pages('src/posts/*.hbs');
  return app.toStream('pages')
    .pipe(app.sitemap())
    .pipe(app.renderFile())
    .pipe(app.dest('my-blog'));
});

Heads up!

• Make sure you add app.sitemap() before app.renderFile(), so the templates in the sitemap are rendered
• The sitemap plugin doesn't check to see if are actually writing the files in a collection to the file system.

Set the destination

Pass the destination as the second argument or options.dest to app.sitemap():

.pipe(app.sitemap(null, 'docs'))           // dest => "docs"
.pipe(app.sitemap('posts', 'blog'))        // dest => "blog"
.pipe(app.sitemap('posts', {dest: 'foo'})) // dest => "foo"
.pipe(app.sitemap({dest: 'foo'}))          // dest => "foo"

Sitemap for a specific collection

Generate a sitemap for a specific collection by passing the name of the collection to the plugin.

app.create('posts');
app.posts('src/posts/*.hbs');

app.task('blog', function() {
  return app.src('templates*.hbs')
    .pipe(app.sitemap('posts')) //<= generate sitemap for "posts"
    .pipe(app.renderFile())
    .pipe(app.dest('my-blog'));
});

Sitemap for multiple collections

Generate a sitemap for a multiple collections by passing an array of collection names to the plugin. This will generate one sitemap that includes paths to all files in the given collections.

app.task('pages', ['preload'], function() {
  return app.toStream('pages')
    .pipe(app.toStream('posts'))
    .pipe(app.sitemap(['pages', 'posts'])) 
    .pipe(app.renderFile())
    .pipe(app.dest(dest()));
});

Multiple sitemaps

Add the plugin multiple times to generate multiple sitemaps:

app.task('pages', ['preload'], function() {
  return app.toStream('pages')
    .pipe(app.toStream('posts'))
    .pipe(app.sitemap('pages', 'docs')) // dest => "docs"
    .pipe(app.sitemap('posts', 'blog')) // dest => "blog"
    .pipe(app.renderFile())
    .pipe(app.dest(dest()));
});

FAQ

How important is it to include <lastmod> in a sitemap?

Given that most crawlers will still check the content directly and ignore this value anyway (since it's almost always wrong), it's not that important to use <lastmod>.

It doesn't hurt to include it though.

For more information, see:

• Google: We Mostly Ignore The LastMod Tag In XML Sitemaps
• Should a Sitemap include the home page?

Should I include generated pages, like category or tag indexes that link to other pages?

No. It's recommended that you only include URLs for "original" pages. Crawlers see these indexes as duplicate information.

Where can I find more information about sitemaps?

• Visit sitemaps.org, the canonical resource for information about sitemaps, including protocols, XML tag definitions and more
• Learn how to build and submit a sitemap - from Google's Search Console Help Center
• Best practices for XML sitemaps & RSS/Atom feeds
• Wikipedia - sitemaps

Release history

v1.0.0 - 2017/07/20

Breaking changes

All built-in sitemap helper names are now prefixed with _. This will only affect you if you have created a custom sitemap template. In particular, the following helper names will need to be updated:

• collection => _collection
• filterItems => _filterItems
• url => _url
• urlset => _urlset

About

Related projects

• generate: Command line tool and developer framework for scaffolding out new GitHub projects. Generate offers the… more | homepage
• update: Be scalable! Update is a new, open source developer framework and CLI for automating updates… more | homepage
• verb: Documentation generator for GitHub projects. Verb is extremely powerful, easy to use, and is used… more | homepage

Contributing

Pull requests and stars are always welcome. For bugs and feature requests, please create an issue.

Building docs

(This project's readme.md is generated by verb, please don't edit the readme directly. Any changes to the readme must be made in the .verb.md readme template.)

To generate the readme, run the following command:

$ npm install -g verbose/verb#dev verb-generate-readme && verb

Running tests

Running and reviewing unit tests is a great way to get familiarized with a library and its API. You can install dependencies and run tests with the following command:

$ npm install && npm test

Author

Jon Schlinkert

• github/jonschlinkert
• twitter/jonschlinkert

License

Copyright © 2017, Jon Schlinkert. Released under the MIT License.

---

This file was generated by verb-generate-readme, v0.6.0, on July 20, 2017.