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 that adds a Post interface and MdxPost type to Gatsby sites.


Key Default Value Description
basePath / Basepath for deployments at path other than root.
collection posts The collection is added to Post nodes. 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.
mdxOtherwiseConfigured false Set this flag to true if gatsby-plugin-mdx is already configured for your site.

Any other options will have no effect on the theme, but they will get routed through all tempaltes via pageContext and you can access them from within a template.


Key Required Description
id You can override Gatsby’s internal ID with this field. This comes in handy when you want to be able to easily identify and query a specific post, e.g. for a pinned posts feature.
title Post title. A post’s slug is automatically derived from the title.
slug Use this field to overwrite the automatically derived slug.
date Date in yyyy-MM-dd format. This is the date as it should appear on the website. There is no timezone magic happening anywhere.
authors Array of author names.
description The default description for SEO purposes is the first paragraph in a post MDX file. With this field you can overrwrite the default.
images no List of relative paths to images that can be included into a post via MDX.


PostDescription interface

Field Type Description
id ID! Gatsby node GUID.
body String! String representation of the description.
text String! Text only representation of the description.

Post interface

Field Type Description
id ID! Gatsby node GUID unless overwritten in frontmatter.
collection String! Collection to which this post belongs.
title String! Post title.
date Date! Post date.
authors [String!] Array of author names.
description PostDescription! Post description (formatted and text).
body String! A string representation of the body of a post page.
images [File!] File nodes for images that can be embedded into a post.
path String! Path to generated post page.

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.

Tagging support

This theme is compatible with @maiertech/gatsby-theme-tags-core, which implements tagging for MDX files. Check its README for more information on how to wire it up. You can add the tagging theme more than once and create multiple independent tag collections. But the most common use case is one tag collection for multiple tagged collections. Use option mdxCollections to configure which collections should be included.

Once you have added the tagging theme to your gatsby-config.js you need to follow these steps:

  1. You can add an optional tags field to the frontmatter of posts. The tags theme will include them in the configured collection and corresponding tag pages. At this point any pages generated by the tags theme are unstyled.
  2. Shadow tag-page.js and Shadow tags-page.js to style tag pages.
  3. Modify the shadowed post-page.js to display the tags. You can use the Tags component to display the tags. Tags are already included in the template query. In oder to assemble paths to tag pages, you can add theme option tagCollection with the tag collection name. All theme options are routed through to the template and accessible via pageContext.

Note that Field description for tagged items is not supported, because description in frontmatter is optional in @undataforum/gatsby-theme-posts-core since descriptions default to the first paragraph in MDX files.

© 2023 Gatsby, Inc.