contentful2md

Fetch entries from a Contentful space and write them as Markdown files.

Motivation

Use Contentful as a GUI to edit content for a static website made with Jekyll.

contentful2md can help you if you are in the following context:

• you have a static website, built by developers using Jekyll
• you want to enable writers to edit some of the website content (for example: a blog)

In this situation, it is common to use a dynamic Content Management System (like WordPress, for example) to build the website because it provides a GUI and writers find it easy to use.

Though, we believe that in many cases static websites are a more suitable solution than dynamic CMS: they are very easy to host, easier to customize, faster and more secure.

To allow writers to focus on writing and not on installing and keeping up-to-date the development environment, we provide a solution that makes it very easy to use the nice GUI of Contentful to write content that will end up in a Jekyll website.

The Solution

Development

Mostly at the beginning of the project:

• A space is created on Contentful
• Developers configure one or several content types to define a model of the content that needs to be edited by writers, and create example content (that remains unpublished on Contentful)
• Developers create a Jekyll project and develop the website they want
• Developers use contentful2md to fetch the preview API of Contentful so that they can develop and test the parts of the website that display content from Contentful

Writing

On a regular basis:

• Writers use Contentful to add or edit content, using the content types defined previously
• Writers or developers use a CI/CD system (such as GitLab CI) to:
  • fetch content from Contentful (using contentful2md)
  • build the website (using Jekyll)
  • deploy it

Usage

In your Jekyll project:

• install via npm: npm install contentful2md
• add the following script in package.json:

{
  "scripts": {
    "contentful2md": "contentful2md"
  }
}

• configure using environment variables (see next section)
• run: npm run contentful2md

Configuration

Configuration is done using environment variables. The following variables can/must be configured:

Name	Default Value	Description
CONTENTFUL_SPACE		Space ID, as given by Contentful.
CONTENTFUL_ACCESS_TOKEN		Access token, as given by Contentful. Depending on the value of CONTENTFUL_PREVIEW, this should be the Content Delivery API or the Content Preview API.
CONTENTFUL_PREVIEW	false	If the value if true, use the Preview API. Else use the Delivery API.
CONTENTFUL_CONTENT_TYPE_ID		The ID of the Content Type you want to fetch, as you defined in the Content Model of your space on Contentful.
CONTENTFUL_LOCALE		The locale to fetch. For example: fr-FR.
CONTENTFUL_CONTENT_FIELD	content	The field of your Content Type that should be considered as the main content and put in the body of the Markdown file.
CONTENTFUL_SLUG_FIELD	slug	The field of your Content Type that correspond to the URL your content should take. It will be used to name the Markdown file, so it must be unique.
OUTPUT_DIR		The path to a directory where Markdown files should be created. If the directory does not exist, it will be created. If it exists, its files might be overridden.

Every variable must be defined, except those which have a default value.

There are several ways to define them (which can be mixed):

• in your environment (Continous Integration often allow that)
• in a shell script:

export CONTENTFUL_SPACE="..."
# ...

npm run contentful2md

• directly in the command line: CONTENTFUL_SPACE="..." npm run contentful2md