metalsmith-get-contentful

A Metalsmith plugin to read content from the Contentful API.

Lightweight wrapper around the Contentful API to query content, get the content's fields, and place the fields into metalsmith "files" for later processing. Typically done before the markdown stage.

This plugin works best if your Contentful Content has fields that match up to the YAML data needed for your metalsmith template engine. For example, they should probably have a "title", "template", and, most importantly, "contents".

If your content has a mismatch, see options.msFiles.addYAML and options.msFiles.postProcess().

Usage

To grab all "projects", use their field "slug" as a filename, and put them under the path "/projects/{slug}.md"

var getContentful = require('../getContentful.js');
...
.use(getContentful({
      client: {
         space: '<space_id>',
         accessToken: '<access_token>'
      },
      query : {
         content_type: 'project'
      },
      msFiles : {
         idField: 'slug',
         filename: "projects/${id}.md"
      }
   }) )

Options

client: required arg for Contentful.createClient(client)

You must provide:

• accessToken:
• space:

query: arg for client.getEntries(query)

Default is {}.

msFiles: how to manipulate and place the content into metalsmith

• idField: field to use for id. default is 'slug'. falsy means use sys.id
• filename: pattern to create the metalsmith "filename" based on id. default is "posts/${id}.md"
• postProcess(): Default is null. If present, the content will be replaced by postProcess(content). For example, if you need to rename fields.
• addYAML: default is {}. Gets added to each result. Useful if you want to add fields such as a template
• metadata: default is null. If present, also place all the data into metalsmith.metadata() here.

Notes, Todos, and Caveats

If the "file" is already present, getContentful calls done() with an Error.

After writing this, discovered a very similar approach and code in Bitbucket contentful-data

A different approach is in contentful-metalsmith

leviwheatcroft/metalsmith-contentful also gave me a few ideas.