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