Gatsby Contentful Markdown

• Gatsby Contentful Starter
• Contentful Cms

Gatsby is a static site generator based on React with much popularity nowadays.

Gatsby also provides a plugin to process Markdown into web-ready content, so no custom code is required to get up and running. An example of Markdown on the left, processed to web-ready content on the right. If your team is code savvy, or if controlling cost is a primary goal, Markdown is one of the best ways to manage content in your apps. Some time back I made a site with Gatsby and I've used static markdown for my pages. Now I wanted to move all my posts on Contentful and everything works fine in development. When I went on Netlif. Contentful enables embedding many kinds of external media content, including but not limited to images, videos, tweets and PDFs, into Markdown-formatted texts. Click Embed external content, paste the link to the external resource, and the editor will do the rest. Although you'll only see code snippet in the text editing mode, the preview will display the media resource as it should look like.

The list of sites powered by Gatsby is awe-inspiring:

• My website 😂

One of its most definite advantages is the ability to obtain content from many different sources:

• Wordpress API
• Contentful
• Markdown files

In this article, we will focus on the last one to build a page with separated sections organized by folders containing the different types of posts (blog, projects, and talks).

Files hierarchy

Configuration

To fetch data from the file system, we need to use a plugin called gatsby-source-filesystem.

After fetching the data, we need to convert the Markdown to valid HTML. For that, we are going to use gatsby-transformer-remark.

After installing the packages with npm or yarn, the next step is to configure Gatsby to read from each one of the content folders and parse the Markdown files:

Templates

For each section, we want to define a template for the posts list and optionally one for the post detail (the links for the talks and projects are external, so only the blog has detail page).

List page example

Let’s analyze what’s happening here:

1. We query all the Markdown content, filtering by collection (blog).
2. We also filter by published state. That way, we can include a flag in the frontmatter to mark the file as “unpublished.”
3. We add pagination ability. We are going to generate proper information later.
4. We pass the edges of the data, as well as the pagination information to a “functional” component, which renders the information correctly.

Detail page example

This case is even simpler, as there is no pagination or collection type involved. The query receives a slug as parameter. The data is passed then to a functional component.

Pages generation

Now, we need to update gatsby-node.js, to read for the separated content files in the proper directories.

To maintain our file clean, we are going to create a folder called gatsby, with two files inside: create-pages.js and on-create-node.js.

gatsby-node.js

on-create-node.js

With this hook, we are telling Gatsby to add two new fields when the node is created. We can access those fields later with GraphQL, to filter the pages by collection and to obtain the detail for a determined slug (which includes the collection).

create-pages.js

Let’s analyze what’s happening in this hook:

1. We query all the Markdown content, excluding the unpublished items.
2. For each type of content, we run a collection generator, which filters the content by type and creates the proper pages using the templates.

Note that we can define for each collection:

• How many items we want to display in each page
• If the collection must render individual detail pages

Real example

As I said previously, I’ve used this technique to build this page, so feel free to inspect the files to see a complete example.

There are two most common ways of using markdown in Gatsby with a headless CMS tool.

This post will present how to use them with Contentful service.Additionally it will include contenful image converter inside markdown.

Amazing plugin for converting and optimaizing images from contentful into Gatsby blog.

This is a very popular plugin mostly used for processing markdown and them placing it into the HTML.It is also usefull if you want not only process markdown but also include your own JSX components.

Adding markdown content from CMS in Gatsby blog

1. Install plugin

2. Add plugin into gatsby-config.js

3. Add markdown text field into Contentful Content Type.

• Add field
• Select Text field (Long text, full-text search)
• In configuration select Markdown

4. In your blog post template graphql query get markdown body

5. Use markdown in blog post template component

6. From now on you can put your imports and React components inside Contentful markdown field. It will be automatically detected and transformed.

Plugin powered by remark processor. It parses markdown but without included parser for React components.

1. Install plugin

Gatsby Contentful Starter

2. Add plugin into gatsby-config.js

3. Add markdown field in Contentful Content Type of your blog as in previous plugin description

4. In your blog post template graphql query get markdown body

5. Use markdown in blog post template component

6. If you want to use custom components inside markdown you need to use additional plugin gatsby-remark-component with rehype-react which is also very simple. Full description how to do it can be found in linked documentation.

It is your choice which plugin you will use. I have tried both and currenly I'm using gatsby-plugin-mdx for markdown processor including custom component.

Contentful Cms

I'm also very happy with plugin for simple image optimization gatsby-remark-images-contentful. If you are looking for low cost and simple image optimalization for your blog, this is it!