A plugin for Metalsmith that pulls content from the Contentful API
Branch: master
Clone or download
Pull request Compare This branch is 29 commits behind contentful:master.
Fetching latest commit…
Cannot retrieve the latest commit at this time.
Type Name Latest commit message Commit time
Failed to load latest commit information.



A Metalsmith's plugin to get content from Contentful


This plugin for metalsmith allows you to build a static site using the data stored at Contentful. This plugin is built on top of the Contentful JavaScript Client.


  1. Install it
  $ npm install contentful-metalsmith
  1. Configure it (example for metalsmith CLI)
  $ vim metalsmith.json


      "source": "src",
      "destination": "build",
      "plugins": {
        "contentful-metalsmith": {
            "accessToken" : "YOUR_CONTENTFUL_ACCESS_TOKEN"
  1. Create a source file
  title: OMG metalsmith-contentful
      space_id: AN_SPACE_ID
  template: entries.html

  1. Create the template (handlebarsjs on this case)
  <!doctype html>

  <html lang="en">
      <meta charset="utf-8">

      <title>Contentful-metalsmith plugin example</title>
      <meta name="description" content="No description">
      <meta name="author" content="Contentful">



            {{#each contentful.entries}}
  1. Enjoy


The first thing that you have to do to use this plugin is to install and configure it (see the TL;DR section for that). Once you have done this you can create and setup source files to fetch data from Contentful.

Setup a source file

To fetch data from Contentful you have to include some extra metadata in a metalsmith source file. The available configuration parameters are the following:

  • space_id (required), the id of the space from where you want to get entries.
  • entry_template (optional), the template that will be used to render each individual entry.
  • filter (optional), this parameter has to include some of the filtering options offered by the Contentful's Content Delivery API.

All this parameters have to be nested under the key contentful.

An example:

  title: OMG metalsmith-contentful
    space_id: cfexampleapi
      content_type: cat
        sys.id[in]: 'finn,jake'
      entry_template: entry.html
  template: example.html

Using the fetched entries on the templates

We have to make a distinction between two types of templates:

  • The template rendered for the source file.
  • And the template rendered for each individual entry.

In the context of the template rendered for the source file you will have access to a property named contentful. This property holds the following properties:

  • entries, an array with all the fetched entries. The structure of each of this entry objects will be the same as the explained below for the entry template.
  • contentTypes, an object with the id of the fetched contentTypes as keys. Under each key there will be an array with all the entries belonging to that particular contentType.

In the context of the template rendered for an individual entry you will have access to the following properties under the property data: