A metalsmith plugin to create dedicated pages for tags from files included in collections. Designed to work closely with metalsmith-collections.
This plugin takes much inspiration (and some of its logic) from https://github.com/totocaster/metalsmith-tags, and its pagination behavior from https://github.com/RobinThrift/metalsmith-paginate.
$ npm install metalsmith-collection-tags
In your pages:
---
title: This is page with tags
tags: tagged, page, metalsmith, plugin
---
Hello World
You can use different handle for the tags, by configuring the handle
option.
tags
is the default.
If you're using handlebars or a similar templating engine, having a different
handle for the tags is useful, because of how these templaters merge file data
and global metadata. (That is, file.tags
will overwrite metadata.tags
.)
This has the lovely side effect of overloading the meaning of the tags
prop,
resulting in very strange behavior if you don't set file.tags
on every
page!
Install the node modules and then add the metalsmith-tags
key to your
metalsmith.json
plugins. The simplest use case just requires a collection
you want to look inside for tags, which points to an object that contains a
handle to parse for tags, and a template and path for the tag pages output:
{
"plugins": {
"metalsmith-collections": {
"blog": "blog/*.md"
},
"metalsmith-collection-tags": {
"blog": {
"handle": "tags",
"path": "blog/topics/:tag.html",
"template": "/partials/tag.hbt"
}
}
}
}
Pass the plugin to Metalsmith#use
:
var collection-tags = require('metalsmith-collection-tags');
metalsmith
.use(collections({
blog: "blog/*.md"
}))
.use(tags({
handle: "tags",
path: "blog/topics/:tag.html",
template: "/partials/tag.hbt"
}));
This will generate blog/topics/[tagname].html
pages in your build
directory with array of pagination.files
objects on which you can iterate
on. You can use tag
for tag name in your templates. (You can refer to tests
folder for tags template.)
The tags
property on your pages will remain but it will be modified to an
array of String containing the tags.
You can use metalsmith-permalink
to customize the permalink of the tag
pages as you would do with anything else.
Additionally you can paginate your tag pages. To do so add two additional
properties to your configuration object, pathPage
and perPage
, and modify
path
to point to the root pagination location:
{
"handle": "tags",
"path": "blog/topics/:tag/index.html",
"template": "/partials/tag.hbt",
"pathPage": "blog/topics/:tag/:num/index.html",
"perPage": 6
}
This will paginate your array of tags so that 6 appear per page, with additional tag pages being nested underneath the first page of tags. For additional details please look at the tests.
You can also add metadata to the generated tags pages using the following form:
var collection-tags = require('metalsmith-collection-tags');
metalsmith
.use(collections({
blog: "blog/*.md"
}))
.use(tags({
handle: "tags",
path: "blog/topics/:tag.html",
template: "/partials/tag.hbt"
metadata: {
title: ':tag - :num',
description: "this is the :num page for :tag"
}
}));
Just like within the path
props, each prop on the passed-in metadata
object will have :tag
and :num
replaced by the relevant data.
Feel free to contribute to this plug-in. Fork, commit, send pull request. Issues, suggestions and bugs are more than welcome.
In case you add functionality, please write corresponding test. Test using
npm test
.
Thanks!
MIT