Migrate to Netlify Today

Netlify announces the next evolution of Gatsby Cloud. Learn more

ContactSign Up
Community Plugin
View plugin on GitHub


A Gatsby theme to add a Post interface and MdxPost type to Gatsby sites.


Option Default Description
basePath / Basepath for deployments at locations other than root.
collection posts The collection is added to Post nodes and as field to the underlying Mdx node. It is also part of the path.
contentPath content/posts Location of post MDX files and assets. You can organize them in whichever way you want, e.g. place them in sub-directories.
fullRelativePath false When set to true, include full path relative to contentPath in path of generated posts.
mdxOtherwiseConfigured false Set this flag true if gatsby-plugin-mdx is already configured for your site.


Key Required Description
title Post title, which will be slugified.
slug Override slugified title.
author Post author.
date Date in yyyy-MM-dd format. There is no timezone magic happening anywhere. Date is optional in the sense that every posts in a collection should have a date or no post should have a date. If the collection does not have dates, previous and next posts do not make sense, even though they are computed.
description Description for SEO and previews (text only).
tags For full tag support you need to install and configure @maiertech/gatsby-theme-tags-core.
images Array of images with src (relative path to image), optional title and mandatory alt text. Images can be embedded into MDX.
canonical_url Canonical URL for SEO.

Author and date are optional to support using this theme to model notes in @maiertech/gatsby-theme-digital-garden.

Schema customization

Post interface

Field Type Description
id ID! Gatsby node GUID.
collection String! Collection to which this post belongs.
title String! From frontmatter.
author String From frontmatter.
date Date From frontmatter.
description String! From frontmatter.
tags [String!] From frontmatter.
images [PostImage!] Images that can be embedded into a post.
body String! String representation of post body.
path String! Path to generated page starts with basePath, then collection, then full relative path if fullRelativePath is true, then slug derived from title.
canonicalUrl String Canonical URL for SEO.

Type MdxPost implements Post. If you prefer to use a data source other than MDX files, you can write a child theme that implements the Post interface.

PostImage type

Field Type Description
src File! Relative path to image.
title String Image title.
alt String! Image alt text.

Images in posts

This theme assumes that you will use gatsby-plugin-image to render images in MDX files. Since StaticImage does not work inside MDX files, you have to declare images in the frontmatter with the images prop.

When you shadow post-page.js, you need to create an images array with gatsbyImageData objects and provide the images array as prop to MDXRenderer. You can then access and render these images with GatsbyImage inside MDX files. This is not ideal and it is intended as workaround until StaticImage can be used inside MDX files.

The downside of dynamic images is that fragment post-fragment.js contains a hard-wired query for dynamic images as constrained images. Therefore, you cannot modify image options and have to go with what the fragment gives you.

© 2023 Gatsby, Inc.