Assemble pipeline plugin for generating one or more sitemaps, for one more more collections, to one or more destination paths.
(TOC generated by verb using markdown-toc)
Install with npm:
$ npm install --save assemble-sitemapsvar 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.
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>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();
});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.
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()beforeapp.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.
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"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'));
});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()));
});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()));
});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:
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
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=>_collectionfilterItems=>_filterItemsurl=>_urlurlset=>_urlset
- 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
Pull requests and stars are always welcome. For bugs and feature requests, please create an issue.
(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 && verbRunning 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 testJon Schlinkert
Copyright © 2017, Jon Schlinkert. Released under the MIT License.
This file was generated by verb-generate-readme, v0.6.0, on July 20, 2017.