hiro/metalsmith-collections
1
0
Fork 0
mirror of https://github.com/vale981/metalsmith-collections synced 2025-03-04 17:01:41 -05:00
Code Issues Projects Releases Packages Wiki Activity Actions

update readme

Browse source
This commit is contained in:
Ian Storm Taylor 2014-03-06 14:50:46 -08:00
parent e613b8cef7
commit 81dd81dca3
1 changed files with 40 additions and 50 deletions
Show stats Download patch file Download diff file Expand all files Collapse all files

90
Readme.md
View file

@ -1,7 +1,7 @@
# metalsmith-collections
A Metalsmith plugin that groups files together into collections and adds them to the global metadata. This is helpful for things like blog posts, where you want to display an index of each.
A Metalsmith plugin that groups files together into collections and adds them to the global metadata. This is helpful for things like blog posts, where you want to display an index of each.
## Features
@ -14,62 +14,45 @@
$ npm install metalsmith-collections
## CLI Usage
## Usage
Install via npm and then add the `metalsmith-collections` key to your `metalsmith.json` plugins.
There are two ways to create collections:
There are two ways to create collections:
- **by pattern** - this is just passing a globing pattern that will group any files that match into the same collection.
- **by metadata** - this is adding a specific `collection` metadata field to each item that you want to add to a collection.
The simplest way to create a collection is to use a pattern to match the files you want to group together:
The simplest way to create a collection is to use a pattern to match the files you want to group together:
```json
{
"plugins": {
"metalsmith-collections": {
"articles": "*.md"
}
}
}
```js
var collections = require('metalsmith-collections');
metalsmith.use(collections({
articles: '*.md'
}));
```
Which is just a shorthand. You could also add additional options:
Which is just a shorthand. You could also add additional options:
```json
{
"plugins": {
"metalsmith-collections": {
"articles": {
"pattern": "*.md",
"sortBy": "date",
"reverse": true
}
}
```
metalsmith.use(collections({
articles: {
pattern: '*.md',
sortBy: 'date',
reverse: true
}
}
}));
```
But you can also match based on a `collection` property in each file's metadata by omitting a pattern:
But you can also match based on a `collection` property in each file's metadata by omitting a pattern, and adding the property to your files:
```json
{
"plugins": {
"metalsmith-collections": {
"articles": {
"sortBy": "date",
"reverse": true
}
}
}
}
```
And then in your files themselves, add a `collection` and the optional field you want to sort by:
metalsmith.use(collections({
articles: {
sortBy: 'date',
reverse: true
}
}));
```
```markdown
---
title: My Article
@ -80,16 +63,23 @@ date: 2013-02-21
My article contents...
```
All of the files with a matching `collection` will be added to an array that is exposed as a key of the same name on the global Metalsmith `metadata`.
All of the files with a matching `collection` will be added to an array that is exposed as a key of the same name on the global Metalsmith `metadata`.
## Javascript Usage
## CLI Usage
Pass the plugin to `Metalsmith#use`:
All of the same options apply, just add them to the `"plugins"` key in your `metalsmith.json` configuration:
```js
var collections = require('metalsmith-collections');
metalsmith.use(collections('*.md'));
```json
{
"plugins": {
"metalsmith-collections": {
"articles": {
"sortBy": "date",
"reverse": true
}
}
}
}
```
## License