Contentful integrations: static site generation with Metalsmith

Update: This project has not been maintained for some time and won't be maintained moving forward. While it might work with some older versions of metalsmith, it's known not to work with more recent versions.

Until now, you had to be a quite tech savvy person to manage static pages. We just changed that by integrating Contentful with Metalsmith.

One of the simplest outputs you can generate with the data on Contentful is static sites. This type of sites is basically a bunch of HTML around your data (and you can slap on some CSS and JavaScript to make it look nicer). The important thing about them is that once created you can just drop them into any web server which will in turn deliver them to your users.

Creating static sites, however, has a downside: they are tedious to create and maintain. For example, any time you change the content of one entry on Contentful you would have to go and edit the static site with data related to that entry. If you are facing this scenario, worry no more!

We already had a plugin for Middlemanapp. Now we are extending the set of tools that you can use to create static sites using the content stored at Contentful with a plugin for Metalsmith. Metalsmith is a JavaScript framework to create static sites. Here's the top three reasons we chose them:

• It is one of the most popular JavaScript static site generators out there;

• You can build all kind of things with it (blogs, project scaffolders, file processors, etc.);

• It's really simple and easy to use.

The plugin we built is pretty simple and doesn't require much configuration. You will need a Contentful account and at least one Space. Once you have created your account and space you will need an accessToken for that space so that the plugin can fetch its entries. This accessToken will allow the plugin to use the Content Delivery API to get data from Contentful.

With the accessToken in your possession, the next step is to configure the plugin. If you use the Metalsmith CLI you will have to do this:

Once you have configured the plugin you are good to create the source files that Metalsmith will pass to the enabled plugins to generate the static site. This source files have to have the following layout:

The FILE_METADATA part contains information that could be used by the plugins to transform the source files into the resulting static sites. The CONTENTS part is, as its name suggests, content that will be available to the plugins and that could be added to the resulting static sites. In our case we will extend the FILE_METADATA with information related to the data stored in Contentful. This information is used by the plugin to know which data to fetch using the Content Delivery API.

In its simplest form the FILE_METADATA required by the plugin includes only the spaceId. In this case the plugin will fetch all the entries from the given space. See example below:

All the space entries fetched will be available to the template used to render the source file in the contentful.entries context property. This source file and its template are examples of such configuration.

Besides the spaceId there are other optional configuration parameters that you can use in each source file. These configuration parameters include:

• content_type. With this configuration parameter you can restrict the contentType of the fetched entries. Follow this link for an example of a source file that uses this configuration parameter.

• entry_template. With this configuration parameter you can choose which template will be used to render each entry. Follow this link for an example of a source file that uses an entry template for each fetched entry.

• filter. With this configuration parameter you can apply further restrictions to the entries fetched from Contentful. Follow this link for an example of a source file which uses the filter configuration parameter.

The nice benefit of using Metalsmith is that is really easy for you to build new stuff on top of our plugin. All the plugins that are run after contentful-metalsmith will have access to all the information (entries, meta information, etc.) generated by our plugin. This information will be added to the metadata of each source file under the key 'contentful'. So besides our own plans for the future of the plugin (enabling sorting of the entries, use of the sync operation, etc.) you can roll your own ideas and even open a pull request to get them in the plugin if you find them interesting enough.

The plugin can be installed via npm or by cloning its repository. We have also created contentful-metalsmith-example, an example project to make it easier to understand the usage of the plugin. Note that this plugin is still in Contentful labs stage, i.e. an experimental project. So if you have plugin related requests please open an issue on Github or a support ticket.

In case want to use another JavaScript generator, this plugin can be useful for you. The plugin itself is small (less that 150 lines of source code) because it is built on top of the Contentful.js client, so extending, lets say, Assemble.io, would be as easy as creating a plugin that uses the Contentful.js client the same way we did here.

Subscribe for updates

Build better digital experiences with Contentful updates direct to your inbox.