@metalsmith/collections 1.3.0 → 2.0.0

package/lib/index.cjs

@@ -1,90 +1,116 @@
 'use strict';
 
 var get = require('lodash.get');
-var readMetadata = require('read-metadata');
+var path = require('path');
 
 function _interopDefaultLegacy (e) { return e && typeof e === 'object' && 'default' in e ? e : { 'default': e }; }
 
 var get__default = /*#__PURE__*/_interopDefaultLegacy(get);
 
-function sortBy(key) {
+function sortBy(key, order) {
+  order = order === 'asc' ? -1 : 1;
   let getKey = x => x[key];
-
   if (key.includes('.')) {
     getKey = x => get__default["default"](x, key);
   }
-
   return function defaultSort(a, b) {
     a = getKey(a);
     b = getKey(b);
-    if (!a && !b) return 0;
-    if (!a) return -1;
-    if (!b) return 1;
-    if (b > a) return -1;
-    if (a > b) return 1;
-    return 0;
+    let ret;
+    if (!a && !b) ret = 0;else if (!a) ret = 1 * order;else if (!b) ret = -1 * order;else if (b > a) ret = 1 * order;else if (a > b) ret = -1 * order;else ret = 0;
+    return ret;
   };
-} // for backwards-compatibility only, date makes as little sense as "pubdate" or any custom key
-
-
-const defaultSort = sortBy('date');
+}
 
+/**
+ * @param {import('metalsmith').File[]} items
+ * @param {CollectionConfig} config
+ */
+function Collection(items, {
+  metadata,
+  ...config
+}) {
+  const collection = [...items];
+  Object.assign(collection, metadata);
+  collection.config = config;
+  collection.constructor = Collection;
+  Object.seal(collection);
+  return collection;
+}
+const defaultSort = sortBy('path', 'asc');
 const defaultFilter = () => true;
+
 /**
  * @typedef {Object} CollectionConfig
- * @property {string|string[]} pattern - One or more glob patterns to match files to a collection
- * @property {string|(a,b) => 0|1|-1} sortBy - A key to sort by (e.g. `date`,`title`, ..) or a custom sort function
- * @property {number} limit - Limit the amount of items in a collection to `limit`
- * @property {boolean} refer - Adds `next` and `previous` keys to file metadata of matched files
- * @property {boolean} reverse - Whether to invert the sorting function results (asc/descending)
- * @property {Function} filterBy - A function that gets a `Metalsmith.File` as first argument and returns `true` for every file to include in the collection
- * @property {Object|string} metadata - An object with metadata to attach to the collection, or a `json`/`yaml`filepath string to load data from (relative to `Metalsmith.directory`)
+ * @property {string|string[]} [pattern] - One or more glob patterns to match files to a collection
+ * @property {string|(a,b) => 0|1|-1} [sort] - a sort string of the format `'<key_or_keypath>:<asc|desc>'`, followed by the sort order, or a custom sort function
+ * @property {number} [limit] - Limit the amount of items in a collection to `limit`
+ * @property {boolean} [refer] - Adds `next`, `previous`, `first` and `last` keys to `file.collection[name]` metadata of matched files
+ * @property {Function} [filter] - A function that gets a `Metalsmith.File` as first argument and returns `true` for every file to include in the collection
+ * @property {Object|string} [metadata] - An object with metadata to attach to the collection, or a `json`/`yaml`filepath string to load data from (relative to `Metalsmith.directory`)
  */
 
 /** @type {CollectionConfig} */
-
-
 const defaultOptions = {
   pattern: null,
-  reverse: false,
   metadata: null,
   limit: Infinity,
   refer: true,
-  sortBy: defaultSort,
-  filterBy: defaultFilter
+  sort: defaultSort,
+  filter: defaultFilter
 };
+
 /**
  * Normalize options
  * @param {Object.<string,CollectionConfig>} options
+ * @param {import('metalsmith').Files} files
+ * @param {import('metalsmith')} metalsmith
+ * @throws {}
  */
-
-function normalizeOptions(options) {
+function normalizeOptions(options, files, metalsmith) {
   options = options || {};
-
+  const matter = metalsmith.matter;
   for (const config in options) {
     let normalized = options[config];
-
     if (typeof normalized === 'string' || Array.isArray(normalized)) {
       normalized = {
         pattern: normalized
       };
     }
-
     normalized = Object.assign({}, defaultOptions, normalized);
-
     if (typeof normalized.metadata === 'string') {
-      normalized.metadata = readMetadata.sync(normalized.metadata);
+      const absPath = path.resolve(metalsmith.source(), normalized.metadata);
+      const inSourcePath = path.relative(metalsmith.source(), absPath);
+      const metadataFile = files[inSourcePath];
+      if (!metadataFile) {
+        const err = new Error(`No collection metadata file at "${absPath}"`);
+        err.name = '@metalsmith/collections';
+        throw err;
+      }
+      normalized.metadata = matter.parse(matter.wrap(metadataFile.contents.toString()));
     }
 
-    if (typeof normalized.sortBy === 'string') {
-      normalized.sortBy = sortBy(normalized.sortBy);
+    // remap sort option
+    let sort = normalized.sort;
+    if (typeof sort === 'string') {
+      if (!sort.includes(':')) sort += ':desc';
+      const [key, order] = sort.split(':');
+      sort = sortBy(key, order);
     }
-
+    normalized.sort = sort;
     options[config] = normalized;
   }
-
   return options;
 }
+
+/**
+ * @typedef {import('../lib/index').ReferencesArray}
+ * @property {import('metalsmith').File[]} previous
+ * @property {import('metalsmith').File[]} next
+ * @property {import('metalsmith').File} first
+ * @property {import('metalsmith').File} last
+ */
+
 /**
  * Add `collections` of files to the global metadata as a sorted array.
  * @example
@@ -93,35 +119,37 @@ function normalizeOptions(options) {
  *   portfolio: {
  *     pattern: 'portfolio/*.md',
  *     metadata: { title: 'My portfolio' },
- *     sortBy: 'order'
+ *     sort: 'date:desc'
  *   }
  * }))
  *
  * @param {Object.<string,CollectionConfig|string>} options
  * @return {import('metalsmith').Plugin}
  */
-
-
-function initializeCollections(options) {
-  options = normalizeOptions(options);
-  const collectionNames = Object.keys(options);
-  const mappedCollections = collectionNames.map(name => {
-    return Object.assign({
-      name: name
-    }, options[name]);
-  });
+function collections(options) {
   return function collections(files, metalsmith, done) {
-    const metadata = metalsmith.metadata();
+    try {
+      options = normalizeOptions(options, files, metalsmith);
+    } catch (err) {
+      done(err);
+    }
+    const collectionNames = Object.keys(options);
+    const mappedCollections = collectionNames.map(name => {
+      return Object.assign({
+        name: name
+      }, options[name]);
+    });
     const fileNames = Object.keys(files);
     const debug = metalsmith.debug('@metalsmith/collections');
-    metadata.collections = {};
+    metalsmith.metadata({
+      collections: {}
+    });
+    const metadata = metalsmith.metadata();
     fileNames.forEach(filePath => {
-      // add path property to file metadata for convenience
-      // this is for backward-compatibility only and is pretty useless
       const file = files[filePath];
-      file.path = file.path || filePath; // dynamically add collections with default options when encountered in file metadata,
-      // and not explicitly defined in plugin options
 
+      // dynamically add collections with default options when encountered in file metadata,
+      // and not explicitly defined in plugin options
       if (file.collection) {
         (Array.isArray(file.collection) ? file.collection : [file.collection]).forEach(name => {
           if (!collectionNames.includes(name)) {
@@ -135,87 +163,90 @@ function initializeCollections(options) {
       }
     });
     debug('Identified %s collections: %s', mappedCollections.length, collectionNames.join());
-    mappedCollections.forEach(collection => {
+    mappedCollections.forEach(collectionConfig => {
       const {
         pattern,
-        filterBy,
-        sortBy,
-        reverse,
+        filter,
+        sort,
         refer,
         limit
-      } = collection;
-      const name = collection.name;
+      } = collectionConfig;
+      const name = collectionConfig.name;
       const matches = [];
-      debug('Processing collection %s with options %s:', name, collection); // first match by pattern if provided
+      debug('Processing collection %s with options %O:', name, collectionConfig);
 
+      // first match by pattern if provided
       if (pattern) {
         matches.push.apply(matches, metalsmith.match(pattern, fileNames).map(filepath => {
-          const data = files[filepath]; // pattern-matched files might or might not have a "collection" property defined in front-matter
+          const data = files[filepath];
+          // pattern-matched files might or might not have a "collection" property defined in front-matter
           // and might also be included in multiple collections
-
           if (!data.collection) {
             data.collection = [];
           } else if (typeof data.collection === 'string') {
             data.collection = [data.collection];
           }
-
-          if (!data.collection.includes(collection.name)) {
-            data.collection = [...data.collection, collection.name];
+          if (!data.collection.includes(collectionConfig.name)) {
+            data.collection = [...data.collection, collectionConfig.name];
           }
-
           return data;
         }));
-      } // next match by "collection" key, but only push if the files haven't been added through pattern matching first
-
+      }
 
+      // next match by "collection" key, but only push if the files haven't been added through pattern matching first
       matches.push.apply(matches, Object.values(files).filter(file => {
         const patternMatched = matches.includes(file);
-        const isInCollection = Array.isArray(file.collection) ? file.collection.includes(collection.name) : file.collection === collection.name;
+        const isInCollection = Array.isArray(file.collection) ? file.collection.includes(collectionConfig.name) : file.collection === collectionConfig.name;
         return !patternMatched && isInCollection;
+      }).map(file => {
+        if (!file.collection) {
+          file.collection = [];
+        } else if (typeof file.collection === 'string') {
+          file.collection = [file.collection];
+        }
+        return file;
       }));
 
-      if (Object.prototype.hasOwnProperty.call(metadata, name)) {
-        debug('Warning: overwriting previously set metadata property %s', name);
-      } // apply sort, reverse, filter, limit options in this order
-
-
-      metadata[name] = matches.sort(sortBy);
-
-      if (reverse) {
-        metadata[name].reverse();
-      }
-
-      metadata[name] = metadata[name].filter(filterBy).slice(0, limit);
-
-      if (collection.metadata) {
-        metadata[name].metadata = collection.metadata;
-      }
-
-      if (refer) {
-        if (reverse) {
-          metadata[name].forEach((file, i) => {
-            Object.assign(file, {
-              next: i > 0 ? metadata[name][i - 1] : null,
-              previous: i < metadata[name].length - 1 ? metadata[name][i + 1] : null
-            });
-          });
+      // apply sort, filter, limit options in this order
+
+      let currentCollection = matches;
+      // safely add to and remove from the sorting context 'path' property
+      const originalPaths = [];
+      currentCollection.forEach(item => {
+        if (item.path) originalPaths.push([item, item.path]);
+        item.path = metalsmith.path(Object.entries(files).find(entry => entry[1] === item)[0]);
+      });
+      currentCollection = currentCollection.sort(sort).filter(filter).slice(0, limit);
+      currentCollection.forEach(item => {
+        const original = originalPaths.find(([file]) => file === item);
+        if (original) {
+          item.path = original[1];
         } else {
-          metadata[name].forEach((file, i) => {
-            Object.assign(file, {
-              previous: i > 0 ? metadata[name][i - 1] : null,
-              next: i < metadata[name].length - 1 ? metadata[name][i + 1] : null
-            });
-          });
+          delete item.path;
         }
+      });
+      metadata.collections[name] = Collection(currentCollection, collectionConfig);
+      if (refer) {
+        const lastIndex = currentCollection.length - 1;
+        currentCollection.forEach((file, i) => {
+          file.collection[name] = Object.assign(file.collection[name] || {}, {
+            previous: [],
+            next: [],
+            first: currentCollection[0],
+            last: currentCollection[lastIndex]
+          });
+          // previous and next are arrays in which resp. the last & first item are merged
+          // so users can easily get a single prev/next vs a list. Without it, getting the single prev is tricky, eg in NJK: {% set coll = collection.some.previous | last %}{{ coll.title }}
+          if (i > 0) file.collection[name].previous = Object.assign(currentCollection.slice(0, i), currentCollection[i - 1]);
+          if (i < lastIndex) file.collection[name].next = Object.assign(currentCollection.slice(i + 1), currentCollection[i + 1]);
+        });
       }
-
-      metadata.collections[name] = metadata[name];
-      debug('Added %s files to collection %s', metadata[name].length, name);
+      debug('Added %s files to collection %s', currentCollection.length, name);
     });
     done();
   };
 }
+collections.defaults = defaultOptions;
 
-initializeCollections.defaults = defaultOptions;
-
-module.exports = initializeCollections;
+module.exports = collections;
+//# sourceMappingURL=index.cjs.map

package/lib/index.cjs.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.cjs","sources":["../src/index.js"],"sourcesContent":["import get from 'lodash.get'\nimport { relative, resolve } from 'path'\n\nfunction sortBy(key, order) {\n  order = order === 'asc' ? -1 : 1\n  let getKey = (x) => x[key]\n  if (key.includes('.')) {\n    getKey = (x) => get(x, key)\n  }\n  return function defaultSort(a, b) {\n    a = getKey(a)\n    b = getKey(b)\n    let ret\n    if (!a && !b) ret = 0\n    else if (!a) ret = 1 * order\n    else if (!b) ret = -1 * order\n    else if (b > a) ret = 1 * order\n    else if (a > b) ret = -1 * order\n    else ret = 0\n\n    return ret\n  }\n}\n\n/**\n * @param {import('metalsmith').File[]} items\n * @param {CollectionConfig} config\n */\nfunction Collection(items, { metadata, ...config }) {\n  const collection = [...items]\n  Object.assign(collection, metadata)\n  collection.config = config\n  collection.constructor = Collection\n  Object.seal(collection)\n  return collection\n}\n\nconst defaultSort = sortBy('path', 'asc')\nconst defaultFilter = () => true\n\n/**\n * @typedef {Object} CollectionConfig\n * @property {string|string[]} [pattern] - One or more glob patterns to match files to a collection\n * @property {string|(a,b) => 0|1|-1} [sort] - a sort string of the format `'<key_or_keypath>:<asc|desc>'`, followed by the sort order, or a custom sort function\n * @property {number} [limit] - Limit the amount of items in a collection to `limit`\n * @property {boolean} [refer] - Adds `next`, `previous`, `first` and `last` keys to `file.collection[name]` metadata of matched files\n * @property {Function} [filter] - A function that gets a `Metalsmith.File` as first argument and returns `true` for every file to include in the collection\n * @property {Object|string} [metadata] - An object with metadata to attach to the collection, or a `json`/`yaml`filepath string to load data from (relative to `Metalsmith.directory`)\n */\n\n/** @type {CollectionConfig} */\nconst defaultOptions = {\n  pattern: null,\n  metadata: null,\n  limit: Infinity,\n  refer: true,\n  sort: defaultSort,\n  filter: defaultFilter\n}\n\n/**\n * Normalize options\n * @param {Object.<string,CollectionConfig>} options\n * @param {import('metalsmith').Files} files\n * @param {import('metalsmith')} metalsmith\n * @throws {}\n */\nfunction normalizeOptions(options, files, metalsmith) {\n  options = options || {}\n  const matter = metalsmith.matter\n\n  for (const config in options) {\n    let normalized = options[config]\n    if (typeof normalized === 'string' || Array.isArray(normalized)) {\n      normalized = { pattern: normalized }\n    }\n    normalized = Object.assign({}, defaultOptions, normalized)\n    if (typeof normalized.metadata === 'string') {\n      const absPath = resolve(metalsmith.source(), normalized.metadata)\n      const inSourcePath = relative(metalsmith.source(), absPath)\n      const metadataFile = files[inSourcePath]\n      if (!metadataFile) {\n        const err = new Error(`No collection metadata file at \"${absPath}\"`)\n        err.name = '@metalsmith/collections'\n        throw err\n      }\n      normalized.metadata = matter.parse(matter.wrap(metadataFile.contents.toString()))\n    }\n\n    // remap sort option\n    let sort = normalized.sort\n    if (typeof sort === 'string') {\n      if (!sort.includes(':')) sort += ':desc'\n      const [key, order] = sort.split(':')\n      sort = sortBy(key, order)\n    }\n    normalized.sort = sort\n\n    options[config] = normalized\n  }\n\n  return options\n}\n\n/**\n * @typedef {import('../lib/index').ReferencesArray}\n * @property {import('metalsmith').File[]} previous\n * @property {import('metalsmith').File[]} next\n * @property {import('metalsmith').File} first\n * @property {import('metalsmith').File} last\n */\n\n/**\n * Add `collections` of files to the global metadata as a sorted array.\n * @example\n * metalsmith.use(collections({\n *   posts: 'posts/*.md',\n *   portfolio: {\n *     pattern: 'portfolio/*.md',\n *     metadata: { title: 'My portfolio' },\n *     sort: 'date:desc'\n *   }\n * }))\n *\n * @param {Object.<string,CollectionConfig|string>} options\n * @return {import('metalsmith').Plugin}\n */\nfunction collections(options) {\n  return function collections(files, metalsmith, done) {\n    try {\n      options = normalizeOptions(options, files, metalsmith)\n    } catch (err) {\n      done(err)\n    }\n    const collectionNames = Object.keys(options)\n    const mappedCollections = collectionNames.map((name) => {\n      return Object.assign({ name: name }, options[name])\n    })\n\n    const fileNames = Object.keys(files)\n    const debug = metalsmith.debug('@metalsmith/collections')\n\n    metalsmith.metadata({ collections: {} })\n    const metadata = metalsmith.metadata()\n\n    fileNames.forEach((filePath) => {\n      const file = files[filePath]\n\n      // dynamically add collections with default options when encountered in file metadata,\n      // and not explicitly defined in plugin options\n      if (file.collection) {\n        ;(Array.isArray(file.collection) ? file.collection : [file.collection]).forEach((name) => {\n          if (!collectionNames.includes(name)) {\n            collectionNames.push(name)\n            const normalized = Object.assign({}, defaultOptions)\n            mappedCollections.push(Object.assign({ name }, normalized))\n          }\n        })\n      }\n    })\n\n    debug('Identified %s collections: %s', mappedCollections.length, collectionNames.join())\n\n    mappedCollections.forEach((collectionConfig) => {\n      const { pattern, filter, sort, refer, limit } = collectionConfig\n      const name = collectionConfig.name\n      const matches = []\n      debug('Processing collection %s with options %O:', name, collectionConfig)\n\n      // first match by pattern if provided\n      if (pattern) {\n        matches.push.apply(\n          matches,\n          metalsmith.match(pattern, fileNames).map((filepath) => {\n            const data = files[filepath]\n            // pattern-matched files might or might not have a \"collection\" property defined in front-matter\n            // and might also be included in multiple collections\n            if (!data.collection) {\n              data.collection = []\n            } else if (typeof data.collection === 'string') {\n              data.collection = [data.collection]\n            }\n            if (!data.collection.includes(collectionConfig.name)) {\n              data.collection = [...data.collection, collectionConfig.name]\n            }\n            return data\n          })\n        )\n      }\n\n      // next match by \"collection\" key, but only push if the files haven't been added through pattern matching first\n      matches.push.apply(\n        matches,\n        Object.values(files)\n          .filter((file) => {\n            const patternMatched = matches.includes(file)\n            const isInCollection = Array.isArray(file.collection)\n              ? file.collection.includes(collectionConfig.name)\n              : file.collection === collectionConfig.name\n            return !patternMatched && isInCollection\n          })\n          .map((file) => {\n            if (!file.collection) {\n              file.collection = []\n            } else if (typeof file.collection === 'string') {\n              file.collection = [file.collection]\n            }\n            return file\n          })\n      )\n\n      // apply sort, filter, limit options in this order\n\n      let currentCollection = matches\n      // safely add to and remove from the sorting context 'path' property\n      const originalPaths = []\n      currentCollection.forEach((item) => {\n        if (item.path) originalPaths.push([item, item.path])\n        item.path = metalsmith.path(Object.entries(files).find((entry) => entry[1] === item)[0])\n      })\n\n      currentCollection = currentCollection.sort(sort).filter(filter).slice(0, limit)\n\n      currentCollection.forEach((item) => {\n        const original = originalPaths.find(([file]) => file === item)\n        if (original) {\n          item.path = original[1]\n        } else {\n          delete item.path\n        }\n      })\n\n      metadata.collections[name] = Collection(currentCollection, collectionConfig)\n\n      if (refer) {\n        const lastIndex = currentCollection.length - 1\n        currentCollection.forEach((file, i) => {\n          file.collection[name] = Object.assign(file.collection[name] || {}, {\n            previous: [],\n            next: [],\n            first: currentCollection[0],\n            last: currentCollection[lastIndex]\n          })\n          // previous and next are arrays in which resp. the last & first item are merged\n          // so users can easily get a single prev/next vs a list. Without it, getting the single prev is tricky, eg in NJK: {% set coll = collection.some.previous | last %}{{ coll.title }}\n          if (i > 0)\n            file.collection[name].previous = Object.assign(currentCollection.slice(0, i), currentCollection[i - 1])\n          if (i < lastIndex)\n            file.collection[name].next = Object.assign(currentCollection.slice(i + 1), currentCollection[i + 1])\n        })\n      }\n\n      debug('Added %s files to collection %s', currentCollection.length, name)\n    })\n    done()\n  }\n}\n\ncollections.defaults = defaultOptions\n\nexport default collections\n"],"names":["sortBy","key","order","getKey","x","includes","get","defaultSort","a","b","ret","Collection","items","metadata","config","collection","Object","assign","constructor","seal","defaultFilter","defaultOptions","pattern","limit","Infinity","refer","sort","filter","normalizeOptions","options","files","metalsmith","matter","normalized","Array","isArray","absPath","resolve","source","inSourcePath","relative","metadataFile","err","Error","name","parse","wrap","contents","toString","split","collections","done","collectionNames","keys","mappedCollections","map","fileNames","debug","forEach","filePath","file","push","length","join","collectionConfig","matches","apply","match","filepath","data","values","patternMatched","isInCollection","currentCollection","originalPaths","item","path","entries","find","entry","slice","original","lastIndex","i","previous","next","first","last","defaults"],"mappings":"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"}

package/lib/index.d.ts

@@ -1,36 +1,48 @@
 import Metalsmith from "metalsmith";
 
-export default initializeCollections;
+export default collections;
 export type CollectionConfig = {
     /**
      * - One or more glob patterns to match files to a collection
      */
-    pattern: string | string[];
+    pattern?: string | string[] | null;
     /**
-     * - A key to sort by (e.g. `date`,`title`, ..) or a custom sort function
+     * - a sort string of the format `'<key_or_keypath>:<asc|desc>'`, followed by the sort order, or a custom sort function
+     * @default 'path:asc'
+     * @example
+     * 'date'
+     * 'pubdate:desc'
+     * 'order:asc'
      */
-    sortBy: string | ((a: any, b: any) => 0 | 1 | -1);
+    sort?: string | ((a: any, b: any) => 0 | 1 | -1);
     /**
      * - Limit the amount of items in a collection to `limit`
      */
-    limit: number;
+    limit?: number;
     /**
-     * - Adds `next` and `previous` keys to file metadata of matched files
+     * - Adds `next`, `previous`, `first` and `last` keys to `file.collection[name]` metadata of matched files
+     * @default true
      */
-    refer: boolean;
-    /**
-     * - Whether to invert the sorting function results (asc/descending)
-     */
-    reverse: boolean;
+    refer?: boolean;
     /**
      * - A function that gets a `Metalsmith.File` as first argument and returns `true` for every file to include in the collection
+     * @default () => true
      */
-    filterBy: Function;
+    filter?: Function;
     /**
      * - An object with metadata to attach to the collection, or a `json`/`yaml`filepath string to load data from (relative to `Metalsmith.directory`)
      */
-    metadata: any | string;
+    metadata?: any | string | null;
 };
+
+/** Collection ordering metadata at `files[path].collection[name]` */
+export type ReferencesArray = string[] & {
+  previous: Metalsmith.File[] & Metalsmith.File;
+  next: Metalsmith.File[] & Metalsmith.File;
+  first: Metalsmith.File;
+  last: Metalsmith.File;
+}
+
 /**
  * Add `collections` of files to the global metadata as a sorted array.
  * @example
@@ -39,16 +51,16 @@ export type CollectionConfig = {
  *   portfolio: {
  *     pattern: 'portfolio/*.md',
  *     metadata: { title: 'My portfolio' },
- *     sortBy: 'order'
+ *     sort: 'order:asc'
  *   }
  * }))
  *
  * @param {Object.<string,CollectionConfig|string>} options
  */
-declare function initializeCollections(options: {
+declare function collections(options: {
     [x: string]: CollectionConfig | string;
 }): Metalsmith.Plugin;
-declare namespace initializeCollections {
+declare namespace collections {
     export { defaultOptions as defaults };
 }