Metalsmith taxonomy

Metalsmith plugin that organizes files into taxonomy trees in global metadata and auto-generates taxonomy page objects.

Features

• can pre-filter files by pattern
• adds taxonomies tree to global metadata
• supports multiple taxonomy namespaces (e.g. blog, products, etc.)
• works well in combination with metalsmith-filemetadata, collections and permalinks
• automatically generates overview, taxonomy & taxonomy term pages (e.g. taxonomies > categories > category)

Install

NPM:

npm i -D metalsmith-taxonomy

Yarn:

yarn add metalsmith-taxonomy

Usage

Quickstart

Simplest usage without parameters or with default parameters (all examples below yield the same results).

var default_taxonomy_set = {
  pattern: '**/*.{md,html}',
  namespace: null,
  pages: ['index', 'taxonomy', 'term'],
  taxonomies: ['tags', 'category']
};

metalsmith.use(taxonomy());

// is the same as
metalsmith.use(taxonomy(default_taxonomy_set));

// or the same as
metalsmith.use(taxonomy([default_taxonomy_set]);

Options

Pass one or more taxonomy sets to the plugin. A taxonomy set is an object with the following properties:

Global metadata

If you had two files with the following content:

---
title: Article 1
category: category1
tags:
  - tag1
  - tag2
---

---
title: Article 2
category: category2
tags:
  - tag2
---

The Quickstart example will generate the following results in global metadata:

  {
    ...metadata,
    taxonomies: {
      tags: {
        tag1: [article1],
        tag2: [article1, article2]
      },
      category: {
        category1: [article1],
        category2: [article2]
      }
    }
  }

Auto-generated index, taxonomy, and term pages

If the pages property of a taxonomy set is not an empty array, or false, metalsmith-taxonomy will auto-generate pages at the following paths:

If namespace is not defined, the index page path will default to index.html.

With the Quickstart example, metalsmith-taxonomy will generate:

{
  'index.html',
  'category.html',
  'category/category1.html',
  'category/category2.html',
  'tags.html',
  'tags/tag1.html',
  'tags/tag2.html',
  ...other_files
};

Generated file objects get the following metadata:

Index page metadata

Taxonomy page metadata

Term page metadata

Adding extra metadata to the generated pages

If a file already exists at the target path of a generated page, the generated metadata will be merged into the existing metadata of that file. Extra metadata can also be added with plugins like metalsmith-filemetadata further in the plugin chain.

Sorting the term matches

By default, the files will be sorted as they are read from the filesystem (alphabetically by file name).

The data available to metadata is a reference to the items under taxonomies[namespace][taxonomy][term], so you could use metalsmith-keymaster or a custom plugin to sort the data:

metalsmith
  .use(taxonomy)
  .use(function(files, metalsmith) {
    var taxonomies = metalsmith.metadata().taxonomies;

    Object.keys(taxonomies.tags).forEach(function(tagName) {
      taxonomies.tags[tagName].sort(function(a, b) {
        return a.order < b.order ? -1 : (a.order > b.order) ? 1 : 0;
      };
    });
  })

The example above shows how to sort all term collections under the tag taxonomy by an order property defined in each file's metadata.

Custom metadata & rendering with metalsmith-layouts/filemetadata/default-values

You can use metalsmith-filemetadata to add custom data to the generated file objects by pattern, e.g. to specify a layout property to be used later in the chain by metalsmith-layouts.

var taxonomy = require('metalsmith-taxonomy')({
  namespace: 'taxonomies',
  taxonomies: ['category', 'tags']
});

var filemetadata = require('metalsmith-filemetadata')([
  {
    pattern: 'taxonomies/**/*.html',
    metadata: { layout: 'taxonomy-term.hbs' }
  },
  {
    pattern: 'taxonomies/*.html',
    metadata: { layout: 'taxonomy.hbs' }
  },
  {
    pattern: 'taxonomies.html',
    metadata: { layout: 'taxonomy-index.hbs' }
  }
]);

var layouts = require('metalsmith-layouts')({
  directory: 'src/layouts',
  default: 'default.hbs',
  pattern: '**/*.{md,html}'
});

metalsmith.use(taxonomy).use(filemetadata).use(layouts);

metalsmith-default-values works exactly the same as above.

Custom or nested page paths with metalsmith-permalinks

You can use metalsmith-permalinks to move or nest taxonomy pages:

var taxonomy = require('metalsmith-taxonomy')({
  pages: ['index', 'taxonomy', 'term'],
  taxonomies: ['category', 'tags']
});

var collections = require('metalsmith-collections')({
  posts: 'posts/**/*.md'
});

var permalinks = {
  linksets: [
    {
      match: { collection: 'posts' },
      pattern: 'posts/:category/:title'
    },
    {
      match: { type: 'taxonomy:index' },
      pattern: 'posts'
    },
    {
      match: { type: 'taxonomy:term', taxonomy: 'category', namespace: 'blog' },
      pattern: 'posts/:category'
    },
    {
      match: { type: 'taxonomy:taxonomy' },
      pattern: 'posts/:taxonomy'
    },
    {
      match: { type: 'taxonomy:term', namespace: 'blog' },
      pattern: 'posts/:category'
    }
  ]
};

metalsmith.use(taxonomy).use(collections).use(permalinks);

with the example files from Global metadata would result in a directory tree like:

└── posts
    ├── index.html --> index page
    ├── tags
    |    ├── index.html --> taxonomy page
    |    ├── tag1
    |    |    └── index.html --> term page
    |    └── tag2
    |         └── index.html --> term page
    ├── category
    |    └── index.html --> taxonomy page
    ├── category1
    |    ├── index.html --> term page
    |    └── article-1
    |         └── index.html
    └── category2
         ├── index.html --> term page
         └── article-2
              └── index.html

Examples

Clone this repository and navigate to the example/licenses or more advanced example/blog directory, run npm install & npm start.

License

LGPL v0.3