Skip to content
Switch branches/tags
This branch is 29 commits behind contentful:master.
Fetch upstream

Latest commit


Git stats


Failed to load latest commit information.
Latest commit message
Commit time


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
      filter:[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:




A plugin for Metalsmith that pulls content from the Contentful API



No releases published


No packages published